Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

fix(skills): install ClawHub skills.sh catalog pages via the install resolver

wizardchen3d40ee0affe9
diff --git a/client/README.md b/client/README.md
index 02f49830f..d3a36f69e 100644
--- a/client/README.md
+++ b/client/README.md
@@ -391,7 +391,7 @@ if err != nil {
### 示例:从托管平台安装沙箱技能
-`source` 必须写明确:ClawHub 用 `@owner/slug`,GitHub / SkillHub 粘贴完整 URL。不要传裸的 `owner/slug`。
+`source` 必须写明确:ClawHub 用 `@owner/slug`,ClawHub 上的 skills.sh 条目用完整 `https://clawhub.ai/skills-sh/owner/repo/slug` 或 `skills-sh:owner/repo/slug`,GitHub / SkillHub 粘贴完整 URL。不要传裸的 `owner/slug`。
```go
skillID, err := apiClient.InstallSandboxSkillFromSource(
diff --git a/client/README_EN.md b/client/README_EN.md
index ff714f404..99e9fd411 100644
--- a/client/README_EN.md
+++ b/client/README_EN.md
@@ -203,7 +203,7 @@ if err != nil {
### Example: Install a sandbox skill from a registry
-`source` must be explicit: `@owner/slug` for ClawHub, or a full GitHub / SkillHub URL. Bare `owner/slug` is rejected.
+`source` must be explicit: `@owner/slug` for ClawHub, a full `https://clawhub.ai/skills-sh/owner/repo/slug` (or `skills-sh:owner/repo/slug`) for federated skills.sh listings, or a full GitHub / SkillHub URL. Bare `owner/slug` is rejected.
```go
skillID, err := apiClient.InstallSandboxSkillFromSource(
diff --git a/client/skill.go b/client/skill.go
index d0dc0119d..9a3b01d3f 100644
--- a/client/skill.go
+++ b/client/skill.go
@@ -53,9 +53,11 @@ func (c *Client) ListSkills(ctx context.Context, sandboxConfigID string) ([]Skil
// InstallSandboxSkillFromSource installs a skill onto a sandbox config from a
// public locator. Use "@owner/slug" (ClawHub), a github.com / gitlab.com /
-// skills.sh / skillhub URL, or a direct zip/SKILL.md URL. Bare "owner/slug"
-// is rejected as ambiguous. The call is accepted asynchronously; follow
-// progress on the skill ID.
+// skills.sh / skillhub URL, a ClawHub skills-sh catalog page
+// (https://clawhub.ai/skills-sh/owner/repo/slug), a skills-sh:owner/repo/slug
+// locator, or a direct zip/SKILL.md URL. Bare "owner/slug" is rejected as
+// ambiguous. The call is accepted asynchronously; follow progress on the
+// skill ID.
func (c *Client) InstallSandboxSkillFromSource(
ctx context.Context, configID, source string,
) (string, error) {
diff --git a/docs/agent-skills.md b/docs/agent-skills.md
index 3daa4dd3b..0d27e950e 100644
--- a/docs/agent-skills.md
+++ b/docs/agent-skills.md
@@ -160,6 +160,7 @@ Docker、CubeSandbox、E2B 均通过同一套空间配置 CRUD、连接检查和
空间「技能沙箱」设置里可以把技能装进当前配置的镜像。除上传 zip 外,也支持从托管平台粘贴来源(每种写法只对应一种来源,不会猜测):
- ClawHub:`@owner/slug`,或不含 `/` 的 slug(如 `my-team--skill`)
+- ClawHub skills.sh 联邦页:`https://clawhub.ai/skills-sh/owner/repo/slug` 或 `skills-sh:owner/repo/slug`(服务端向 ClawHub 解析钉死的 GitHub commit,不会把 URL 最后一段当成仓库子目录)
- 页面链接:ClawHub / [skillhub.cn](https://skillhub.cn) / 自托管 SkillHub、skills.sh、GitHub、GitLab
- 直接的 zip / `SKILL.md` URL
diff --git a/docs/api/skill.md b/docs/api/skill.md
index 61f119d83..53fbdefdf 100644
--- a/docs/api/skill.md
+++ b/docs/api/skill.md
@@ -85,8 +85,9 @@ curl --location 'http://localhost:8080/api/v1/sandbox-configs/{id}/skills' \
| --- | --- |
| `@owner/slug`、`@owner/[email protected]` | ClawHub(默认 registry) |
| `my-skill`、`[email protected]`(不含 `/`) | ClawHub slug |
+| `https://clawhub.ai/skills-sh/owner/repo/slug`、`skills-sh:owner/repo/slug` | ClawHub 上的 skills.sh 联邦条目(经 ClawHub install API 解析到钉死的 GitHub commit;仓库内路径可能比 URL slug 更深) |
| `https://clawhub.ai/...`、`https://skillhub.cn/...`、自托管 SkillHub 页面 | 对应 registry |
-| `https://github.com/...`、`https://gitlab.com/...`、`https://skills.sh/...` | Git 托管 |
+| `https://github.com/...`、`https://gitlab.com/...`、`https://skills.sh/...` | Git 托管;`skills.sh` 的 `owner/repo/slug` 页面同样走 ClawHub resolver |
| `https://…/foo.zip` 或 `…/SKILL.md` | 直接下载 |
`owner/slug`(无 `@`、无 URL)会 400:它既是 ClawHub id 也是 GitHub 仓库,请改成 `@owner/slug` 或粘贴完整链接。
diff --git a/docs/docs.go b/docs/docs.go
index 6ec42a534..2ba0a205d 100644
--- a/docs/docs.go
+++ b/docs/docs.go
@@ -11867,7 +11867,7 @@ const docTemplate = `{
"ApiKeyAuth": []
}
],
- "description": "Install a skill onto this sandbox config's image. Send a zip\nas multipart form field \"file\", or JSON {\"source\":\"...\"} to\npull a public skill. source is one of: \"@owner/slug\" or a\nslash-free slug (ClawHub), a github.com / gitlab.com /\nskills.sh / clawhub / skillhub URL, or a direct zip/SKILL.md\nURL. Bare \"owner/slug\" is rejected as ambiguous. The source\nmust be readable anonymously. The install boots a sandbox and\nruns for minutes, so the request is only accepted; follow it\nvia the install-events stream.",
+ "description": "Install a skill onto this sandbox config's image. Send a zip\nas multipart form field \"file\", or JSON {\"source\":\"...\"} to\npull a public skill. source is one of: \"@owner/slug\" or a\nslash-free slug (ClawHub), a github.com / gitlab.com /\nskills.sh / clawhub / skillhub URL, a ClawHub skills-sh\ncatalog page (https://clawhub.ai/skills-sh/owner/repo/slug),\na skills-sh:owner/repo/slug locator, or a direct zip/SKILL.md\nURL. Bare \"owner/slug\" is rejected as ambiguous. The source\nmust be readable anonymously. The install boots a sandbox and\nruns for minutes, so the request is only accepted; follow it\nvia the install-events stream.",
"consumes": [
"application/json",
"multipart/form-data"
@@ -24713,7 +24713,7 @@ const docTemplate = `{
"type": "object",
"properties": {
"source": {
- "description": "Source is exactly one of: \"@owner/slug\" or a slash-free slug (ClawHub),\na github.com / gitlab.com / skills.sh / clawhub / skillhub page URL, or\na direct zip/SKILL.md URL. Bare \"owner/slug\" is rejected: it is both a\nClawHub id and a GitHub repo. The fetch carries no credential.",
+ "description": "Source is exactly one of: \"@owner/slug\" or a slash-free slug (ClawHub),\na github.com / gitlab.com / skills.sh / clawhub / skillhub page URL, a\nClawHub skills-sh catalog page or \"skills-sh:owner/repo/slug\" locator, or\na direct zip/SKILL.md URL. Bare \"owner/slug\" is rejected: it is both a\nClawHub id and a GitHub repo. The fetch carries no credential.",
"type": "string"
}
}
diff --git a/docs/swagger.json b/docs/swagger.json
index 8ee20c3c0..6d55c4293 100644
--- a/docs/swagger.json
+++ b/docs/swagger.json
@@ -11860,7 +11860,7 @@
"ApiKeyAuth": []
}
],
- "description": "Install a skill onto this sandbox config's image. Send a zip\nas multipart form field \"file\", or JSON {\"source\":\"...\"} to\npull a public skill. source is one of: \"@owner/slug\" or a\nslash-free slug (ClawHub), a github.com / gitlab.com /\nskills.sh / clawhub / skillhub URL, or a direct zip/SKILL.md\nURL. Bare \"owner/slug\" is rejected as ambiguous. The source\nmust be readable anonymously. The install boots a sandbox and\nruns for minutes, so the request is only accepted; follow it\nvia the install-events stream.",
+ "description": "Install a skill onto this sandbox config's image. Send a zip\nas multipart form field \"file\", or JSON {\"source\":\"...\"} to\npull a public skill. source is one of: \"@owner/slug\" or a\nslash-free slug (ClawHub), a github.com / gitlab.com /\nskills.sh / clawhub / skillhub URL, a ClawHub skills-sh\ncatalog page (https://clawhub.ai/skills-sh/owner/repo/slug),\na skills-sh:owner/repo/slug locator, or a direct zip/SKILL.md\nURL. Bare \"owner/slug\" is rejected as ambiguous. The source\nmust be readable anonymously. The install boots a sandbox and\nruns for minutes, so the request is only accepted; follow it\nvia the install-events stream.",
"consumes": [
"application/json",
"multipart/form-data"
@@ -24706,7 +24706,7 @@
"type": "object",
"properties": {
"source": {
- "description": "Source is exactly one of: \"@owner/slug\" or a slash-free slug (ClawHub),\na github.com / gitlab.com / skills.sh / clawhub / skillhub page URL, or\na direct zip/SKILL.md URL. Bare \"owner/slug\" is rejected: it is both a\nClawHub id and a GitHub repo. The fetch carries no credential.",
+ "description": "Source is exactly one of: \"@owner/slug\" or a slash-free slug (ClawHub),\na github.com / gitlab.com / skills.sh / clawhub / skillhub page URL, a\nClawHub skills-sh catalog page or \"skills-sh:owner/repo/slug\" locator, or\na direct zip/SKILL.md URL. Bare \"owner/slug\" is rejected: it is both a\nClawHub id and a GitHub repo. The fetch carries no credential.",
"type": "string"
}
}
diff --git a/docs/swagger.yaml b/docs/swagger.yaml
index 285c3a3b5..584de6834 100644
--- a/docs/swagger.yaml
+++ b/docs/swagger.yaml
@@ -6058,7 +6058,8 @@ definitions:
source:
description: |-
Source is exactly one of: "@owner/slug" or a slash-free slug (ClawHub),
- a github.com / gitlab.com / skills.sh / clawhub / skillhub page URL, or
+ a github.com / gitlab.com / skills.sh / clawhub / skillhub page URL, a
+ ClawHub skills-sh catalog page or "skills-sh:owner/repo/slug" locator, or
a direct zip/SKILL.md URL. Bare "owner/slug" is rejected: it is both a
ClawHub id and a GitHub repo. The fetch carries no credential.
type: string
@@ -13882,7 +13883,9 @@ paths:
as multipart form field "file", or JSON {"source":"..."} to
pull a public skill. source is one of: "@owner/slug" or a
slash-free slug (ClawHub), a github.com / gitlab.com /
- skills.sh / clawhub / skillhub URL, or a direct zip/SKILL.md
+ skills.sh / clawhub / skillhub URL, a ClawHub skills-sh
+ catalog page (https://clawhub.ai/skills-sh/owner/repo/slug),
+ a skills-sh:owner/repo/slug locator, or a direct zip/SKILL.md
URL. Bare "owner/slug" is rejected as ambiguous. The source
must be readable anonymously. The install boots a sandbox and
runs for minutes, so the request is only accepted; follow it
diff --git a/internal/application/service/tenant_skill_source.go b/internal/application/service/tenant_skill_source.go
index b59ecb4cf..2323c81f4 100644
--- a/internal/application/service/tenant_skill_source.go
+++ b/internal/application/service/tenant_skill_source.go
@@ -41,11 +41,14 @@ type skillSourceKind string
const (
skillSourceRegistry skillSourceKind = "registry"
+ skillSourceSkillsSh skillSourceKind = "skills-sh"
skillSourceGitHub skillSourceKind = "github"
skillSourceGitLab skillSourceKind = "gitlab"
skillSourceDirect skillSourceKind = "direct"
)
+const skillsShRefPrefix = "skills-sh:"
+
// parsedSkillSource is one install input after host-specific URL/slug rules
// have been applied, and before any bytes are fetched.
type parsedSkillSource struct {
@@ -61,11 +64,29 @@ type parsedSkillSource struct {
}
type skillSourceHandoff struct {
- SourceRef string `json:"sourceRef"`
- Repo string `json:"repo"`
- Commit string `json:"commit"`
- Path string `json:"path"`
- ArchiveURL string `json:"archiveUrl"`
+ OK *bool `json:"ok"`
+ Message string `json:"message"`
+ Reason string `json:"reason"`
+ InstallKind string `json:"installKind"`
+ SourceRef string `json:"sourceRef"`
+ Repo string `json:"repo"`
+ Commit string `json:"commit"`
+ Path string `json:"path"`
+ ArchiveURL string `json:"archiveUrl"`
+ DownloadURL string `json:"downloadUrl"`
+ GitHub *skillSourceGitHubHandoff `json:"github"`
+ Archive *skillSourceArchiveHandoff `json:"archive"`
+}
+
+type skillSourceGitHubHandoff struct {
+ Repo string `json:"repo"`
+ Path string `json:"path"`
+ Commit string `json:"commit"`
+ SourceURL string `json:"sourceUrl"`
+}
+
+type skillSourceArchiveHandoff struct {
+ Version string `json:"version"`
DownloadURL string `json:"downloadUrl"`
}
@@ -138,6 +159,11 @@ func fetchNormalizedSkillBundle(
// last segment; owner becomes ownerHandle.
// my-skill ClawHub slug (no slash)
// [email protected] ClawHub slug + version
+// skills-sh:owner/repo/slug
+// ClawHub federated skills.sh listing. Resolved
+// through ClawHub's install API to a pinned GitHub
+// commit; the GitHub path is often deeper than the
+// URL slug (e.g. tools/image/ai-image-generation).
// https://… host decides (GitHub / GitLab / ClawHub / SkillHub /
// skills.sh / zip|SKILL.md / self-hosted registry)
func parseSkillSource(raw string) (parsedSkillSource, error) {
@@ -150,6 +176,9 @@ func parseSkillSource(raw string) (parsedSkillSource, error) {
if strings.Contains(input, "://") {
return parseSkillSourceURL(input)
}
+ if payload, ok := skillsShBarePayload(input); ok {
+ return parseSkillsShLocator(defaultSkillRegistryOrigin, splitPath(payload))
+ }
if strings.HasPrefix(input, "@") {
return parseRegistrySlug(defaultSkillRegistryOrigin, strings.TrimPrefix(input, "@"))
}
@@ -265,6 +294,10 @@ func parseRegistryURL(u *url.URL) (parsedSkillSource, error) {
DirectURL: u.String(),
}, nil
}
+ parts := splitPath(trimmed)
+ if len(parts) > 0 && strings.EqualFold(parts[0], "skills-sh") {
+ return parseSkillsShLocator(origin, parts[1:])
+ }
slug, version, err := slugAndVersionFromPath(trimmed, u.Fragment)
if err != nil {
return parsedSkillSource{}, err
@@ -434,18 +467,61 @@ func parseSkillsShURL(u *url.URL) (parsedSkillSource, error) {
if len(parts) < 2 {
return parsedSkillSource{}, fmt.Errorf("%w: skills.sh URL must be owner/repo", ErrSkillSourceInvalid)
}
+ if len(parts) >= 3 {
+ // Catalog pages are owner/repo/slug. ClawHub's install resolver is
+ // what names the GitHub subdir (often not the slug itself).
+ return parseSkillsShLocator(defaultSkillRegistryOrigin, parts)
+ }
src := parsedSkillSource{
Kind: skillSourceGitHub,
Owner: parts[0],
Repo: strings.TrimSuffix(parts[1], ".git"),
Ref: "HEAD",
}
- if len(parts) > 2 {
- src.Subdir = strings.Join(parts[2:], "/")
- }
return src, nil
}
+func skillsShBarePayload(input string) (string, bool) {
+ lower := strings.ToLower(input)
+ switch {
+ case strings.HasPrefix(lower, skillsShRefPrefix):
+ return strings.TrimSpace(input[len(skillsShRefPrefix):]), true
+ case strings.HasPrefix(lower, "skills-sh/"):
+ return strings.TrimSpace(input[len("skills-sh/"):]), true
+ default:
+ return "", false
+ }
+}
+
+// parseSkillsShLocator maps a ClawHub/OpenClaw skills-sh reference onto the
+// install resolver. The locator is always owner/repo/slug — three segments.
+// The GitHub folder is not assumed to equal the slug; fetch asks ClawHub.
+func parseSkillsShLocator(registry string, parts []string) (parsedSkillSource, error) {
+ if len(parts) != 3 {
+ return parsedSkillSource{}, fmt.Errorf(
+ "%w: skills.sh locator must be owner/repo/slug", ErrSkillSourceInvalid)
+ }
+ owner := strings.ToLower(strings.TrimSpace(parts[0]))
+ repo := strings.ToLower(strings.TrimSuffix(strings.TrimSpace(parts[1]), ".git"))
+ slug := strings.ToLower(strings.TrimSpace(parts[2]))
+ slug, _ = splitTrailingVersion(slug)
+ if owner == "" || repo == "" || slug == "" ||
+ strings.Contains(owner, "..") || strings.Contains(repo, "..") || strings.Contains(slug, "..") {
+ return parsedSkillSource{}, fmt.Errorf(
+ "%w: skills.sh locator must be owner/repo/slug", ErrSkillSourceInvalid)
+ }
+ if registry == "" {
+ registry = defaultSkillRegistryOrigin
+ }
+ return parsedSkillSource{
+ Kind: skillSourceSkillsSh,
+ Registry: registry,
+ Owner: owner,
+ Repo: repo,
+ Slug: slug,
+ }, nil
+}
+
func splitTrailingVersion(spec string) (slug, version string) {
i := strings.LastIndex(spec, "@")
if i <= 0 {
@@ -514,6 +590,19 @@ func (s parsedSkillSource) fetchURL() (string, error) {
}
u.RawQuery = q.Encode()
return u.String(), nil
+ case skillSourceSkillsSh:
+ registry := strings.TrimRight(s.Registry, "/")
+ if registry == "" {
+ registry = defaultSkillRegistryOrigin
+ }
+ u, err := url.Parse(registry + "/api/v1/skills/" + url.PathEscape(s.Slug) + "/install")
+ if err != nil {
+ return "", fmt.Errorf("%w: invalid registry origin", ErrSkillSourceInvalid)
+ }
+ q := u.Query()
+ q.Set("reference", skillsShRefPrefix+s.Owner+"/"+s.Repo+"/"+s.Slug)
+ u.RawQuery = q.Encode()
+ return u.String(), nil
case skillSourceGitHub:
ref := s.Ref
if ref == "" {
@@ -582,13 +671,53 @@ func fetchSkillSourceBytes(
}
func sourceFromHandoff(prev parsedSkillSource, handoff skillSourceHandoff) (parsedSkillSource, error) {
+ if handoff.OK != nil && !*handoff.OK {
+ msg := strings.TrimSpace(handoff.Message)
+ if msg == "" {
+ msg = strings.TrimSpace(handoff.Reason)
+ }
+ if msg == "" {
+ msg = "registry refused the skill"
+ }
+ return parsedSkillSource{}, fmt.Errorf("%w: %s", ErrSkillSourceInvalid, truncateSkillError(msg))
+ }
+
archiveURL := strings.TrimSpace(handoff.ArchiveURL)
if archiveURL == "" {
archiveURL = strings.TrimSpace(handoff.DownloadURL)
}
- if archiveURL == "" {
- return parsedSkillSource{}, fmt.Errorf("%w: registry response has no archive URL", ErrSkillSourceInvalid)
+ if archiveURL == "" && handoff.Archive != nil {
+ archiveURL = strings.TrimSpace(handoff.Archive.DownloadURL)
+ }
+ if archiveURL != "" {
+ return sourceFromArchiveHandoff(prev, handoff, archiveURL)
+ }
+ if gh := handoffGitHub(handoff); gh != nil {
+ return sourceFromGitHubHandoff(*gh)
+ }
+ return parsedSkillSource{}, fmt.Errorf("%w: registry response has no archive URL", ErrSkillSourceInvalid)
+}
+
+func handoffGitHub(handoff skillSourceHandoff) *skillSourceGitHubHandoff {
+ if handoff.GitHub != nil {
+ return handoff.GitHub
+ }
+ if !strings.EqualFold(strings.TrimSpace(handoff.InstallKind), "github") {
+ return nil
}
+ if strings.TrimSpace(handoff.Repo) == "" && strings.TrimSpace(handoff.Commit) == "" {
+ return nil
+ }
+ return &skillSourceGitHubHandoff{
+ Repo: handoff.Repo,
+ Path: handoff.Path,
+ Commit: handoff.Commit,
+ }
+}
+
+func sourceFromArchiveHandoff(
+ prev parsedSkillSource, handoff skillSourceHandoff, archiveURL string,
+) (parsedSkillSource, error) {
if strings.HasPrefix(archiveURL, "/") {
if prev.Registry == "" {
return parsedSkillSource{}, fmt.Errorf(
@@ -605,15 +734,72 @@ func sourceFromHandoff(prev parsedSkillSource, handoff skillSourceHandoff) (pars
return parsedSkillSource{}, fmt.Errorf(
"%w: registry archive URL is not usable: %v", ErrSkillSourceInvalid, err)
}
- if next.Subdir == "" && strings.TrimSpace(handoff.Path) != "" {
- next.Subdir = strings.Trim(handoff.Path, "/")
+ path := strings.TrimSpace(handoff.Path)
+ if path == "" && handoff.GitHub != nil {
+ path = strings.TrimSpace(handoff.GitHub.Path)
}
- if next.Kind == skillSourceGitHub && next.Ref == "HEAD" && strings.TrimSpace(handoff.Commit) != "" {
- next.Ref = handoff.Commit
+ if next.Subdir == "" && path != "" {
+ next.Subdir = strings.Trim(path, "/")
+ }
+ commit := strings.TrimSpace(handoff.Commit)
+ if commit == "" && handoff.GitHub != nil {
+ commit = strings.TrimSpace(handoff.GitHub.Commit)
+ }
+ if next.Kind == skillSourceGitHub && next.Ref == "HEAD" && commit != "" {
+ next.Ref = commit
}
return next, nil
}
+func sourceFromGitHubHandoff(gh skillSourceGitHubHandoff) (parsedSkillSource, error) {
+ srcURL := strings.TrimSpace(gh.SourceURL)
+ if srcURL != "" {
+ next, err := parseSkillSourceURL(srcURL)
+ if err == nil && next.Kind == skillSourceGitHub {
+ applyGitHubHandoffMeta(&next, gh)
+ return next, nil
+ }
+ }
+ owner, repo, ok := splitGitHubRepo(gh.Repo)
+ if !ok {
+ return parsedSkillSource{}, fmt.Errorf(
+ "%w: registry github handoff is missing repo", ErrSkillSourceInvalid)
+ }
+ src := parsedSkillSource{
+ Kind: skillSourceGitHub,
+ Owner: owner,
+ Repo: repo,
+ Ref: strings.TrimSpace(gh.Commit),
+ Subdir: strings.Trim(strings.TrimSpace(gh.Path), "/"),
+ }
+ if src.Ref == "" {
+ src.Ref = "HEAD"
+ }
+ return src, nil
+}
+
+func applyGitHubHandoffMeta(next *parsedSkillSource, gh skillSourceGitHubHandoff) {
+ if next.Kind != skillSourceGitHub {
+ return
+ }
+ if commit := strings.TrimSpace(gh.Commit); commit != "" {
+ next.Ref = commit
+ }
+ if next.Subdir == "" && strings.TrimSpace(gh.Path) != "" {
+ next.Subdir = strings.Trim(gh.Path, "/")
+ }
+}
+
+func splitGitHubRepo(spec string) (owner, repo string, ok bool) {
+ spec = strings.TrimSpace(spec)
+ spec = strings.TrimSuffix(spec, ".git")
+ owner, repo, found := strings.Cut(spec, "/")
+ if !found || owner == "" || repo == "" || strings.Contains(repo, "/") {
+ return "", "", false
+ }
+ return owner, repo, true
+}
+
func getSkillURL(
ctx context.Context, client *http.Client, rawURL string,
) ([]byte, string, error) {
diff --git a/internal/application/service/tenant_skill_source_test.go b/internal/application/service/tenant_skill_source_test.go
index c415b9960..3cb486718 100644
--- a/internal/application/service/tenant_skill_source_test.go
+++ b/internal/application/service/tenant_skill_source_test.go
@@ -116,11 +116,51 @@ func TestParseSkillSource(t *testing.T) {
},
},
{
- name: "skills.sh maps to github",
+ name: "clawhub skills-sh catalog page",
+ in: "https://clawhub.ai/skills-sh/skills-101/superpowers/ai-image-generation",
+ want: parsedSkillSource{
+ Kind: skillSourceSkillsSh, Registry: "https://clawhub.ai",
+ Owner: "skills-101", Repo: "superpowers", Slug: "ai-image-generation",
+ },
+ },
+ {
+ name: "clawhub skills-sh repo named skills",
+ in: "https://clawhub.ai/skills-sh/doany-ai/skills/ai-image-generation",
+ want: parsedSkillSource{
+ Kind: skillSourceSkillsSh, Registry: "https://clawhub.ai",
+ Owner: "doany-ai", Repo: "skills", Slug: "ai-image-generation",
+ },
+ },
+ {
+ name: "skills-sh colon reference",
+ in: "skills-sh:skills-101/superpowers/ai-image-generation",
+ want: parsedSkillSource{
+ Kind: skillSourceSkillsSh, Registry: defaultSkillRegistryOrigin,
+ Owner: "skills-101", Repo: "superpowers", Slug: "ai-image-generation",
+ },
+ },
+ {
+ name: "skills-sh slash reference",
+ in: "skills-sh/skills-101/superpowers/ai-image-generation",
+ want: parsedSkillSource{
+ Kind: skillSourceSkillsSh, Registry: defaultSkillRegistryOrigin,
+ Owner: "skills-101", Repo: "superpowers", Slug: "ai-image-generation",
+ },
+ },
+ {
+ name: "skills.sh catalog page uses clawhub resolver",
in: "https://skills.sh/vercel-labs/agent-skills/web-design",
+ want: parsedSkillSource{
+ Kind: skillSourceSkillsSh, Registry: defaultSkillRegistryOrigin,
+ Owner: "vercel-labs", Repo: "agent-skills", Slug: "web-design",
+ },
+ },
+ {
+ name: "skills.sh owner/repo stays github",
+ in: "https://skills.sh/vercel-labs/agent-skills",
want: parsedSkillSource{
Kind: skillSourceGitHub, Owner: "vercel-labs", Repo: "agent-skills",
- Ref: "HEAD", Subdir: "web-design",
+ Ref: "HEAD",
},
},
{
@@ -164,6 +204,14 @@ func TestParseSkillSourceRejects(t *testing.T) {
_, err = parseSkillSource("vercel-labs/agent-skills@frontend-design")
require.ErrorIs(t, err, ErrSkillSourceInvalid)
require.ErrorContains(t, err, "ambiguous")
+
+ _, err = parseSkillSource("https://clawhub.ai/skills-sh/skills-101/superpowers")
+ require.ErrorIs(t, err, ErrSkillSourceInvalid)
+ require.ErrorContains(t, err, "owner/repo/slug")
+
+ _, err = parseSkillSource("https://clawhub.ai/foo/bar/baz/qux")
+ require.ErrorIs(t, err, ErrSkillSourceInvalid)
+ require.ErrorContains(t, err, "unrecognized registry path")
}
func TestParseSkillSourceAtSlugIsRegistryNotGitHub(t *testing.T) {
@@ -181,6 +229,80 @@ func TestFetchSkillArchiveRejectsAmbiguousShorthandWithoutFetching(t *testing.T)
require.ErrorContains(t, err, "ambiguous")
}
+func TestClawHubSkillsShMapsToInstallResolver(t *testing.T) {
+ cases := []string{
+ "https://clawhub.ai/skills-sh/skills-101/superpowers/ai-image-generation",
+ "skills-sh:skills-101/superpowers/ai-image-generation",
+ "skills-sh/skills-101/superpowers/ai-image-generation",
+ "https://www.skills.sh/skills-101/superpowers/ai-image-generation",
+ }
+ for _, in := range cases {
+ got, err := parseSkillSource(in)
+ require.NoError(t, err, in)
+ u, err := got.fetchURL()
+ require.NoError(t, err, in)
+ parsed, err := url.Parse(u)
+ require.NoError(t, err, in)
+ require.Equal(t, "https://clawhub.ai/api/v1/skills/ai-image-generation/install",
+ parsed.Scheme+"://"+parsed.Host+parsed.Path, in)
+ require.Equal(t, "skills-sh:skills-101/superpowers/ai-image-generation",
+ parsed.Query().Get("reference"), in)
+ }
+}
+
+func TestSourceFromHandoffSkillsShGitHubNestedPath(t *testing.T) {
+ ok := true
+ next, err := sourceFromHandoff(parsedSkillSource{
+ Kind: skillSourceSkillsSh, Registry: defaultSkillRegistryOrigin,
+ }, skillSourceHandoff{
+ OK: &ok,
+ InstallKind: "github",
+ GitHub: &skillSourceGitHubHandoff{
+ Repo: "skills-101/superpowers",
+ Path: "tools/image/ai-image-generation",
+ Commit: "becc25649700d5457772a00e5143e28ccf9e5afa",
+ SourceURL: "https://github.com/skills-101/superpowers/tree/" +
+ "becc25649700d5457772a00e5143e28ccf9e5afa/tools/image/ai-image-generation",
+ },
+ })
+ require.NoError(t, err)
+ require.Equal(t, skillSourceGitHub, next.Kind)
+ require.Equal(t, "skills-101", next.Owner)
+ require.Equal(t, "superpowers", next.Repo)
+ require.Equal(t, "becc25649700d5457772a00e5143e28ccf9e5afa", next.Ref)
+ require.Equal(t, "tools/image/ai-image-generation", next.Subdir)
+}
+
+func TestSourceFromHandoffSkillsShGitHubWithoutSourceURL(t *testing.T) {
+ ok := true
+ next, err := sourceFromHandoff(parsedSkillSource{Kind: skillSourceSkillsSh}, skillSourceHandoff{
+ OK: &ok,
+ InstallKind: "github",
+ GitHub: &skillSourceGitHubHandoff{
+ Repo: "openai/skills",
+ Path: "skills/.curated/pdf",
+ Commit: "49f948faa9258a0c61caceaf225e179651397431",
+ },
+ })
+ require.NoError(t, err)
+ require.Equal(t, skillSourceGitHub, next.Kind)
+ require.Equal(t, "openai", next.Owner)
+ require.Equal(t, "skills", next.Repo)
+ require.Equal(t, "49f948faa9258a0c61caceaf225e179651397431", next.Ref)
+ require.Equal(t, "skills/.curated/pdf", next.Subdir)
+}
+
+func TestSourceFromHandoffSkillsShRefused(t *testing.T) {
+ ok := false
+ _, err := sourceFromHandoff(parsedSkillSource{Kind: skillSourceSkillsSh}, skillSourceHandoff{
+ OK: &ok,
+ Reason: "github_upstream_missing",
+ Message: "upstream listing is gone",
+ })
+ require.ErrorIs(t, err, ErrSkillSourceInvalid)
+ require.ErrorContains(t, err, "upstream listing is gone")
+}
+
func TestClawHubOwnerSlugMapsToDownloadAPI(t *testing.T) {
cases := []string{
"@jixinyi546-maker/emar-ppt-skill",
@@ -208,6 +330,48 @@ func TestSkillHubCNMapsToDownloadAPI(t *testing.T) {
require.Equal(t, skillHubCNAPIOrigin+"/api/v1/download?slug=self-improving-agent", u)
}
+func TestFetchSkillArchiveFromSkillsShInstallResolver(t *testing.T) {
+ archive := zipBundle(t, map[string]string{
+ "repo-main/README.md": "# repo",
+ "repo-main/tools/image/ai-image-generation/SKILL.md": validSkillMD,
+ "repo-main/tools/image/ai-image-generation/run.py": "print(1)\n",
+ "repo-main/other/SKILL.md": strings.Replace(
+ validSkillMD, "name: pdf-tools", "name: other-skill", 1),
+ })
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ switch r.URL.Path {
+ case "/api/v1/skills/ai-image-generation/install":
+ require.Equal(t, "skills-sh:skills-101/superpowers/ai-image-generation",
+ r.URL.Query().Get("reference"))
+ _ = json.NewEncoder(w).Encode(skillSourceHandoff{
+ InstallKind: "github",
+ GitHub: &skillSourceGitHubHandoff{
+ Repo: "skills-101/superpowers",
+ Path: "tools/image/ai-image-generation",
+ Commit: "abc123",
+ },
+ ArchiveURL: "http://" + r.Host + "/archive.zip",
+ })
+ case "/archive.zip":
+ w.Header().Set("Content-Type", "application/zip")
+ _, _ = w.Write(archive)
+ default:
+ http.NotFound(w, r)
+ }
+ }))
+ t.Cleanup(server.Close)
+ allowLoopbackSkillFetch(t)
+
+ got, err := fetchSkillArchive(t.Context(),
+ server.URL+"/skills-sh/skills-101/superpowers/ai-image-generation", server.Client())
+ require.NoError(t, err)
+ bundle, err := ParseSkillBundle(got)
+ require.NoError(t, err)
+ require.Equal(t, "pdf-tools", bundle.Name)
+ require.Contains(t, bundle.Files, "run.py")
+ require.NotContains(t, bundle.Files, "README.md")
+}
+
func TestFetchSkillArchiveFromRegistry(t *testing.T) {
archive := zipBundle(t, map[string]string{"SKILL.md": validSkillMD})
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
diff --git a/internal/handler/sandbox_skill.go b/internal/handler/sandbox_skill.go
index c382bb42b..934e24368 100644
--- a/internal/handler/sandbox_skill.go
+++ b/internal/handler/sandbox_skill.go
@@ -275,7 +275,9 @@ func (h *SandboxSkillHandler) GetFile(c *gin.Context) {
// @Description as multipart form field "file", or JSON {"source":"..."} to
// @Description pull a public skill. source is one of: "@owner/slug" or a
// @Description slash-free slug (ClawHub), a github.com / gitlab.com /
-// @Description skills.sh / clawhub / skillhub URL, or a direct zip/SKILL.md
+// @Description skills.sh / clawhub / skillhub URL, a ClawHub skills-sh
+// @Description catalog page (https://clawhub.ai/skills-sh/owner/repo/slug),
+// @Description a skills-sh:owner/repo/slug locator, or a direct zip/SKILL.md
// @Description URL. Bare "owner/slug" is rejected as ambiguous. The source
// @Description must be readable anonymously. The install boots a sandbox and
// @Description runs for minutes, so the request is only accepted; follow it
@@ -341,7 +343,8 @@ func (h *SandboxSkillHandler) Upload(c *gin.Context) {
type skillSourceRequest struct {
// Source is exactly one of: "@owner/slug" or a slash-free slug (ClawHub),
- // a github.com / gitlab.com / skills.sh / clawhub / skillhub page URL, or
+ // a github.com / gitlab.com / skills.sh / clawhub / skillhub page URL, a
+ // ClawHub skills-sh catalog page or "skills-sh:owner/repo/slug" locator, or
// a direct zip/SKILL.md URL. Bare "owner/slug" is rejected: it is both a
// ClawHub id and a GitHub repo. The fetch carries no credential.
Source string `json:"source"`