Skip to content

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

docs(sandbox): clarify skill source requirements in installation process

wizardchenb6cfb34be669
diff --git a/client/README.md b/client/README.md
index cd9ac297f..dfc03710c 100644
--- a/client/README.md
+++ b/client/README.md
@@ -389,6 +389,8 @@ if err != nil {
### 示例:从托管平台安装沙箱技能
+`source` 必须写明确:ClawHub 用 `@owner/slug`,GitHub / SkillHub 粘贴完整 URL。不要传裸的 `owner/slug`。
+
```go
skillID, err := apiClient.InstallSandboxSkillFromSource(
context.Background(), sandboxConfigID, "@owner/slug")
diff --git a/client/README_EN.md b/client/README_EN.md
index 6c676018e..7ee448f18 100644
--- a/client/README_EN.md
+++ b/client/README_EN.md
@@ -202,6 +202,8 @@ 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.
+
```go
skillID, err := apiClient.InstallSandboxSkillFromSource(
context.Background(), sandboxConfigID, "@owner/slug")
diff --git a/client/skill.go b/client/skill.go
index d2f93e5a1..b8f7b9cc3 100644
--- a/client/skill.go
+++ b/client/skill.go
@@ -52,9 +52,10 @@ func (c *Client) ListSkills(ctx context.Context, sandboxConfigID string) ([]Skil
}
// InstallSandboxSkillFromSource installs a skill onto a sandbox config from a
-// ClawHub / SkillHub / skills.sh / GitHub / GitLab locator or a direct archive
-// URL. The source must be readable anonymously. The call is accepted
-// asynchronously; follow progress on the skill ID.
+// 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.
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 8ba484bbc..bb1377cd3 100644
--- a/docs/agent-skills.md
+++ b/docs/agent-skills.md
@@ -158,13 +158,13 @@ Docker、Local、CubeSandbox、E2B 均通过同一套空间配置 CRUD、连接
### 安装租户技能
-空间「技能沙箱」设置里可以把技能装进当前配置的镜像。除上传 zip 外,也支持从托管平台粘贴来源:
+空间「技能沙箱」设置里可以把技能装进当前配置的镜像。除上传 zip 外,也支持从托管平台粘贴来源(每种写法只对应一种来源,不会猜测):
-- ClawHub / SkillHub / [skillhub.cn](https://skillhub.cn) 页面链接或 slug(`@owner/slug`)
-- skills.sh、GitHub、GitLab 仓库或目录链接
+- ClawHub:`@owner/slug`,或不含 `/` 的 slug(如 `my-team--skill`)
+- 页面链接:ClawHub / [skillhub.cn](https://skillhub.cn) / 自托管 SkillHub、skills.sh、GitHub、GitLab
- 直接的 zip / `SKILL.md` URL
-来源必须可匿名读取,服务端下载时不携带任何凭据;私有仓库请先导出 zip 再上传。安装仍走原有镜像快照流程。
+不要粘贴裸的 `owner/slug`:请改成 `@owner/slug` 或完整 `https://github.com/...` 链接。来源必须可匿名读取,服务端下载时不携带任何凭据;私有仓库请先导出 zip 再上传。安装仍走原有镜像快照流程。
**有沙箱在跑时改不了身份字段。** 身份字段分两组,成因不同但后果都足够严重:
diff --git a/docs/api/skill.md b/docs/api/skill.md
index 8d83f4911..fa2b20420 100644
--- a/docs/api/skill.md
+++ b/docs/api/skill.md
@@ -69,11 +69,17 @@ curl --location 'http://localhost:8080/api/v1/sandbox-configs/{id}/skills' \
### 2. 从托管平台安装(JSON)
-`source` 可以是:
+`source` 只接受一种明确写法,不会根据下载结果猜测:
-- ClawHub / SkillHub / skillhub.cn 页面链接或 slug(`@owner/slug`、`my-team--skill`)
-- skills.sh / GitHub / GitLab 仓库或目录链接
-- 直接的 zip / `SKILL.md` URL
+| 输入 | 含义 |
+| --- | --- |
+| `@owner/slug`、`@owner/[email protected]` | ClawHub(默认 registry) |
+| `my-skill`、`[email protected]`(不含 `/`) | ClawHub slug |
+| `https://clawhub.ai/...`、`https://skillhub.cn/...`、自托管 SkillHub 页面 | 对应 registry |
+| `https://github.com/...`、`https://gitlab.com/...`、`https://skills.sh/...` | Git 托管 |
+| `https://…/foo.zip` 或 `…/SKILL.md` | 直接下载 |
+
+`owner/slug`(无 `@`、无 URL)会 400:它既是 ClawHub id 也是 GitHub 仓库,请改成 `@owner/slug` 或粘贴完整链接。
来源必须可匿名读取:服务端不会为这次下载附带任何凭据,因此私有仓库/私有 registry 需要先自行导出 zip 再上传。
diff --git a/docs/docs.go b/docs/docs.go
index e51e472be..cfab866f9 100644
--- a/docs/docs.go
+++ b/docs/docs.go
@@ -11632,7 +11632,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 from ClawHub, SkillHub, skills.sh, GitHub, GitLab, or a\ndirect archive URL. The source must be readable anonymously.\nThe install boots a sandbox and runs for minutes, so the\nrequest is only accepted; follow it via the install-events\nstream.",
+ "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.",
"consumes": [
"application/json",
"multipart/form-data"
@@ -24243,7 +24243,7 @@ const docTemplate = `{
"type": "object",
"properties": {
"source": {
- "description": "Source is a ClawHub/SkillHub slug or page URL, a skills.sh / GitHub /\nGitLab locator, or a direct zip/SKILL.md URL. It must be readable\nanonymously: the fetch carries no credential of any kind.",
+ "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.",
"type": "string"
}
}
diff --git a/docs/swagger.json b/docs/swagger.json
index fd115ee36..14e2fc59e 100644
--- a/docs/swagger.json
+++ b/docs/swagger.json
@@ -11625,7 +11625,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 from ClawHub, SkillHub, skills.sh, GitHub, GitLab, or a\ndirect archive URL. The source must be readable anonymously.\nThe install boots a sandbox and runs for minutes, so the\nrequest is only accepted; follow it via the install-events\nstream.",
+ "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.",
"consumes": [
"application/json",
"multipart/form-data"
@@ -24236,7 +24236,7 @@
"type": "object",
"properties": {
"source": {
- "description": "Source is a ClawHub/SkillHub slug or page URL, a skills.sh / GitHub /\nGitLab locator, or a direct zip/SKILL.md URL. It must be readable\nanonymously: the fetch carries no credential of any kind.",
+ "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.",
"type": "string"
}
}
diff --git a/docs/swagger.yaml b/docs/swagger.yaml
index d8e4f45b9..29ff4cbe6 100644
--- a/docs/swagger.yaml
+++ b/docs/swagger.yaml
@@ -6023,9 +6023,10 @@ definitions:
properties:
source:
description: |-
- Source is a ClawHub/SkillHub slug or page URL, a skills.sh / GitHub /
- GitLab locator, or a direct zip/SKILL.md URL. It must be readable
- anonymously: the fetch carries no credential of any kind.
+ 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 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
type: object
internal_handler.storageBackendRequest:
@@ -13681,11 +13682,13 @@ paths:
description: |-
Install a skill onto this sandbox config's image. Send a zip
as multipart form field "file", or JSON {"source":"..."} to
- pull from ClawHub, SkillHub, skills.sh, GitHub, GitLab, or a
- direct archive URL. The source must be readable anonymously.
- The install boots a sandbox and runs for minutes, so the
- request is only accepted; follow it via the install-events
- stream.
+ 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
+ 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
+ via the install-events stream.
parameters:
- description: Sandbox config ID
in: path
diff --git a/frontend/src/i18n/locales/en-US.ts b/frontend/src/i18n/locales/en-US.ts
index 979541ea8..ee9f0d820 100755
--- a/frontend/src/i18n/locales/en-US.ts
+++ b/frontend/src/i18n/locales/en-US.ts
@@ -1281,7 +1281,7 @@ export default {
skillUploadDrag: 'or drop a file here',
skillUploadHint: 'Install writes the skill onto the current image and takes a new snapshot. This can take several minutes. The current chat turn is not interrupted; open sessions rebuild their sandbox on the next turn, which clears the session workspace scratch.',
skillUploadHintNewSession: 'Install writes the skill onto the current image and takes a new snapshot. This can take several minutes. Already-open sessions keep their current sandbox until they end; only newly started sessions pick up this install.',
- skillSourcePlaceholder: 'Paste a URL or {\'@\'}owner/slug',
+ skillSourcePlaceholder: 'ClawHub: {\'@\'}owner/slug. GitHub/SkillHub: paste the full URL',
skillSourceInstall: 'Install',
skillInstallOr: 'or',
skillSourceFailed: 'Failed to install the skill from the registry',
diff --git a/frontend/src/i18n/locales/ko-KR.ts b/frontend/src/i18n/locales/ko-KR.ts
index d41013075..79f1b60f0 100755
--- a/frontend/src/i18n/locales/ko-KR.ts
+++ b/frontend/src/i18n/locales/ko-KR.ts
@@ -5120,7 +5120,7 @@ export default {
skillUploadDrag: '또는 여기로 드래그',
skillUploadHint: '설치하면 현재 이미지에 스킬을 쓰고 새 스냅샷을 만듭니다. 몇 분이 걸릴 수 있습니다. 현재 대화 턴은 중단되지 않으며, 이미 열린 세션은 다음 턴에서 새 이미지로 샌드박스를 다시 만들고 그때 세션 작업 공간 초안이 지워집니다.',
skillUploadHintNewSession: '설치하면 현재 이미지에 스킬을 쓰고 새 스냅샷을 만듭니다. 몇 분이 걸릴 수 있습니다. 이미 열린 세션은 세션이 끝날 때까지 기존 샌드박스를 유지하며, 이번에 설치한 스킬은 새로 시작한 세션에만 적용됩니다.',
- skillSourcePlaceholder: 'URL 또는 {\'@\'}owner/slug 붙여넣기',
+ skillSourcePlaceholder: 'ClawHub는 {\'@\'}owner/slug, GitHub/SkillHub는 전체 URL을 붙여넣으세요',
skillSourceInstall: '설치',
skillInstallOr: '또는',
skillSourceFailed: '레지스트리에서 스킬을 설치하지 못했습니다',
diff --git a/frontend/src/i18n/locales/ru-RU.ts b/frontend/src/i18n/locales/ru-RU.ts
index 2e6fe2c01..c8741b215 100755
--- a/frontend/src/i18n/locales/ru-RU.ts
+++ b/frontend/src/i18n/locales/ru-RU.ts
@@ -5120,7 +5120,7 @@ export default {
skillUploadDrag: 'или перетащите файл сюда',
skillUploadHint: 'Установка записывает навык в текущий образ и создаёт новый снимок. Это может занять несколько минут. Текущий ход диалога не прерывается; открытые сессии пересоздадут песочницу при следующем сообщении, и тогда черновики рабочей области сессии будут очищены.',
skillUploadHintNewSession: 'Установка записывает навык в текущий образ и создаёт новый снимок. Это может занять несколько минут. Уже открытые сессии продолжают использовать текущую песочницу до своего завершения; этот навык появится только у новых сессий.',
- skillSourcePlaceholder: 'Вставьте URL или {\'@\'}owner/slug',
+ skillSourcePlaceholder: 'ClawHub: {\'@\'}owner/slug. GitHub/SkillHub: вставьте полный URL',
skillSourceInstall: 'Установить',
skillInstallOr: 'или',
skillSourceFailed: 'Не удалось установить навык из реестра',
diff --git a/frontend/src/i18n/locales/zh-CN.ts b/frontend/src/i18n/locales/zh-CN.ts
index 272b380cc..dc6024d88 100755
--- a/frontend/src/i18n/locales/zh-CN.ts
+++ b/frontend/src/i18n/locales/zh-CN.ts
@@ -5122,7 +5122,7 @@ export default {
skillUploadDrag: '或将文件拖到此处',
skillUploadHint: '安装会在当前镜像上生成新快照,可能需要数分钟。当前这一轮对话不会中断;下一轮提问时才会按新镜像重建沙箱,会话工作区草稿会在那时清空。',
skillUploadHintNewSession: '安装会在当前镜像上生成新快照,可能需要数分钟。已打开的会话继续使用原沙箱,直到该会话结束;只有新打开的会话才会带上这次安装的技能。',
- skillSourcePlaceholder: '粘贴链接或 {\'@\'}owner/slug',
+ skillSourcePlaceholder: 'ClawHub 用 {\'@\'}owner/slug,GitHub / SkillHub 请粘贴完整链接',
skillSourceInstall: '安装',
skillInstallOr: '或',
skillSourceFailed: '从托管平台安装技能失败',
diff --git a/internal/application/service/tenant_skill_source.go b/internal/application/service/tenant_skill_source.go
index 710f4c1ea..199bc15eb 100644
--- a/internal/application/service/tenant_skill_source.go
+++ b/internal/application/service/tenant_skill_source.go
@@ -35,7 +35,6 @@ var (
skillSourceHTTPDefault *http.Client
semverLike = regexp.MustCompile(`^v?\d+\.\d+(\.\d+)?([.-][0-9A-Za-z.-]+)?$`)
- gitSHALike = regexp.MustCompile(`^[0-9a-fA-F]{7,40}$`)
)
type skillSourceKind string
@@ -118,40 +117,21 @@ func fetchSkillArchive(ctx context.Context, source string, client *http.Client)
httpClient := skillSourceHTTPClient(client)
fetched, err := fetchSkillSourceBytes(ctx, httpClient, parsed, 0)
if err != nil {
- // A bare "owner/slug" is both a GitHub repo and a registry slug, and
- // the paste usually came from the registry listing. Only the failure
- // of the first reading tells us which one it was.
- alt, ok := registrySlugFallback(source, parsed)
- if !ok {
- return nil, err
- }
- altFetched, altErr := fetchSkillSourceBytes(ctx, httpClient, alt, 0)
- if altErr != nil {
- return nil, err
- }
- fetched = altFetched
+ return nil, err
}
return normalizeFetchedSkillArchive(fetched.body, fetched.contentType, fetched.subdir)
}
-// registrySlugFallback re-reads a shorthand that was taken for a GitHub repo as
-// a registry slug. It applies only to a bare "owner/slug": anything carrying a
-// ref, a subdirectory or a scheme said what it meant.
-func registrySlugFallback(raw string, parsed parsedSkillSource) (parsedSkillSource, bool) {
- if parsed.Kind != skillSourceGitHub || parsed.Subdir != "" || parsed.Ref != "HEAD" {
- return parsedSkillSource{}, false
- }
- spec := strings.TrimRight(strings.TrimSpace(raw), "/")
- if spec == "" || strings.Contains(spec, "://") || strings.Contains(spec, "@") {
- return parsedSkillSource{}, false
- }
- alt, err := parseRegistrySlug(defaultSkillRegistryOrigin, spec)
- if err != nil {
- return parsedSkillSource{}, false
- }
- return alt, true
-}
-
+// parseSkillSource maps one paste onto exactly one kind. It does not probe
+// the network to guess: owner/slug is both a ClawHub id and a GitHub repo,
+// so a slash without a URL or a leading @ is refused rather than fetched
+// twice.
+//
+// @owner/slug ClawHub (default registry)
+// my-skill ClawHub slug (no slash)
+// [email protected] ClawHub slug + version
+// https://… host decides (GitHub / GitLab / ClawHub / SkillHub /
+// skills.sh / zip|SKILL.md / self-hosted registry)
func parseSkillSource(raw string) (parsedSkillSource, error) {
input := strings.TrimSpace(raw)
if input == "" {
@@ -165,8 +145,10 @@ func parseSkillSource(raw string) (parsedSkillSource, error) {
if strings.HasPrefix(input, "@") {
return parseRegistrySlug(defaultSkillRegistryOrigin, strings.TrimPrefix(input, "@"))
}
- if looksLikeGitHubShorthand(input) {
- return parseGitHubShorthand(input)
+ if strings.Contains(input, "/") {
+ return parsedSkillSource{}, fmt.Errorf(
+ "%w: %q is ambiguous; use @%s for ClawHub, or paste a github.com / gitlab.com / skills.sh / skillhub URL",
+ ErrSkillSourceInvalid, input, input)
}
return parseRegistrySlug(defaultSkillRegistryOrigin, input)
}
@@ -423,63 +405,6 @@ func parseSkillsShURL(u *url.URL) (parsedSkillSource, error) {
return src, nil
}
-func parseGitHubShorthand(spec string) (parsedSkillSource, error) {
- ownerRepo, suffix, ok := strings.Cut(spec, "@")
- parts := splitPath(ownerRepo)
- if len(parts) < 2 {
- return parsedSkillSource{}, fmt.Errorf("%w: expected owner/repo", ErrSkillSourceInvalid)
- }
- 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:], "/")
- }
- if !ok || suffix == "" {
- return src, nil
- }
- if looksLikeGitRef(suffix) {
- src.Ref = suffix
- return src, nil
- }
- // owner/repo@skill-name selects one skill out of a monorepo by directory
- // (or by matching the last path segment).
- if src.Subdir == "" {
- src.Subdir = suffix
- } else {
- src.Subdir = path.Join(src.Subdir, suffix)
- }
- return src, nil
-}
-
-func looksLikeGitHubShorthand(spec string) bool {
- ownerRepo, _, _ := strings.Cut(spec, "@")
- parts := splitPath(ownerRepo)
- if len(parts) < 2 {
- return false
- }
- for _, p := range parts[:2] {
- if p == "" || strings.ContainsAny(p, " \\") {
- return false
- }
- }
- return true
-}
-
-func looksLikeGitRef(s string) bool {
- switch strings.ToLower(s) {
- case "head", "main", "master", "develop", "trunk":
- return true
- }
- if semverLike.MatchString(s) || gitSHALike.MatchString(s) {
- return true
- }
- return strings.HasPrefix(s, "refs/")
-}
-
func splitTrailingVersion(spec string) (slug, version string) {
i := strings.LastIndex(spec, "@")
if i <= 0 {
diff --git a/internal/application/service/tenant_skill_source_test.go b/internal/application/service/tenant_skill_source_test.go
index 932fa7e5d..8e201e4a1 100644
--- a/internal/application/service/tenant_skill_source_test.go
+++ b/internal/application/service/tenant_skill_source_test.go
@@ -50,6 +50,14 @@ func TestParseSkillSource(t *testing.T) {
Slug: "my-team--email-sender",
},
},
+ {
+ name: "registry slug with version",
+ want: parsedSkillSource{
+ Kind: skillSourceRegistry, Registry: defaultSkillRegistryOrigin,
+ Slug: "my-skill", Version: "1.2.0",
+ },
+ },
{
name: "skillhub page with version",
in: "https://skillhub.example.com/[email protected]",
@@ -105,14 +113,6 @@ func TestParseSkillSource(t *testing.T) {
Ref: "HEAD", Subdir: "web-design",
},
},
- {
- name: "github shorthand",
- in: "vercel-labs/agent-skills@frontend-design",
- want: parsedSkillSource{
- Kind: skillSourceGitHub, Owner: "vercel-labs", Repo: "agent-skills",
- Ref: "HEAD", Subdir: "frontend-design",
- },
- },
{
name: "gitlab project",
in: "https://gitlab.com/group/project/-/tree/main/skills/foo",
@@ -144,6 +144,30 @@ func TestParseSkillSourceRejects(t *testing.T) {
_, err = parseSkillSource("file:///etc/passwd")
require.ErrorIs(t, err, ErrSkillSourceInvalid)
require.ErrorContains(t, err, "http(s)")
+
+ // owner/slug is a ClawHub id and a GitHub repo. Refuse rather than guess.
+ _, err = parseSkillSource("clawhub_pskoett/self-improving-agent")
+ require.ErrorIs(t, err, ErrSkillSourceInvalid)
+ require.ErrorContains(t, err, "ambiguous")
+ require.ErrorContains(t, err, "@clawhub_pskoett/self-improving-agent")
+
+ _, err = parseSkillSource("vercel-labs/agent-skills@frontend-design")
+ require.ErrorIs(t, err, ErrSkillSourceInvalid)
+ require.ErrorContains(t, err, "ambiguous")
+}
+
+func TestParseSkillSourceAtSlugIsRegistryNotGitHub(t *testing.T) {
+ got, err := parseSkillSource("@clawhub_pskoett/self-improving-agent")
+ require.NoError(t, err)
+ require.Equal(t, skillSourceRegistry, got.Kind)
+ require.Equal(t, defaultSkillRegistryOrigin, got.Registry)
+ require.Equal(t, "clawhub_pskoett/self-improving-agent", got.Slug)
+}
+
+func TestFetchSkillArchiveRejectsAmbiguousShorthandWithoutFetching(t *testing.T) {
+ _, err := fetchSkillArchive(t.Context(), "owner/demo", http.DefaultClient)
+ require.ErrorIs(t, err, ErrSkillSourceInvalid)
+ require.ErrorContains(t, err, "ambiguous")
}
func TestSkillHubCNMapsToDownloadAPI(t *testing.T) {
@@ -263,32 +287,6 @@ func TestFetchSkillArchiveRejectsUnusableHandoffURL(t *testing.T) {
require.ErrorContains(t, err, "archive URL is not usable")
}
-// A bare "owner/slug" reads as a GitHub repo and as a registry slug. The
-// registry is the fallback, but only for a shorthand that named nothing else.
-func TestRegistrySlugFallback(t *testing.T) {
- bare := "clawhub_pskoett/self-improving-agent"
- parsed, err := parseSkillSource(bare)
- require.NoError(t, err)
- require.Equal(t, skillSourceGitHub, parsed.Kind)
-
- alt, ok := registrySlugFallback(bare, parsed)
- require.True(t, ok)
- require.Equal(t, skillSourceRegistry, alt.Kind)
- require.Equal(t, defaultSkillRegistryOrigin, alt.Registry)
- require.Equal(t, bare, alt.Slug)
-
- withSubdir := "vercel-labs/agent-skills@frontend-design"
- parsed, err = parseSkillSource(withSubdir)
- require.NoError(t, err)
- _, ok = registrySlugFallback(withSubdir, parsed)
- require.False(t, ok, "a shorthand that named a skill directory meant GitHub")
-
- parsed, err = parseSkillSource("https://github.com/vercel-labs/agent-skills")
- require.NoError(t, err)
- _, ok = registrySlugFallback("https://github.com/vercel-labs/agent-skills", parsed)
- require.False(t, ok, "an explicit GitHub URL is not a registry slug")
-}
-
func TestFetchSkillArchiveFollowsGitHubHandoff(t *testing.T) {
archive := zipBundle(t, map[string]string{
"repo-main/README.md": "# repo",
diff --git a/internal/handler/sandbox_skill.go b/internal/handler/sandbox_skill.go
index c69747d58..424afe85f 100644
--- a/internal/handler/sandbox_skill.go
+++ b/internal/handler/sandbox_skill.go
@@ -189,11 +189,13 @@ func (h *SandboxSkillHandler) Get(c *gin.Context) {
// @Summary Install a skill
// @Description Install a skill onto this sandbox config's image. Send a zip
// @Description as multipart form field "file", or JSON {"source":"..."} to
-// @Description pull from ClawHub, SkillHub, skills.sh, GitHub, GitLab, or a
-// @Description direct archive URL. The source must be readable anonymously.
-// @Description The install boots a sandbox and runs for minutes, so the
-// @Description request is only accepted; follow it via the install-events
-// @Description stream.
+// @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 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
+// @Description via the install-events stream.
// @Tags SandboxConfig
// @Accept json
// @Accept multipart/form-data
@@ -258,9 +260,10 @@ func (h *SandboxSkillHandler) Upload(c *gin.Context) {
}
type skillSourceRequest struct {
- // Source is a ClawHub/SkillHub slug or page URL, a skills.sh / GitHub /
- // GitLab locator, or a direct zip/SKILL.md URL. It must be readable
- // anonymously: the fetch carries no credential of any kind.
+ // 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 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"`
}
diff --git a/internal/handler/sandbox_skill_test.go b/internal/handler/sandbox_skill_test.go
index e7c15e618..1f18b9349 100644
--- a/internal/handler/sandbox_skill_test.go
+++ b/internal/handler/sandbox_skill_test.go
@@ -324,6 +324,24 @@ func TestSandboxSkillInstallFromSourceInvalidReturns400(t *testing.T) {
require.Contains(t, w.Body.String(), "only http(s) sources are allowed")
}
+func TestSandboxSkillInstallFromSourceAmbiguousShorthandReturns400(t *testing.T) {
+ svc := &fakeSandboxSkillService{
+ sourceErr: fmt.Errorf("%w: %q is ambiguous; use @owner/slug for ClawHub",
+ service.ErrSkillSourceInvalid, "owner/slug"),
+ }
+ router := newSkillTestRouter(NewSandboxSkillHandler(svc, nil))
+
+ req := httptest.NewRequest(http.MethodPost, "/sandbox-configs/cfg-a/skills",
+ strings.NewReader(`{"source":"owner/slug"}`))
+ req.Header.Set("Content-Type", "application/json")
+ w := httptest.NewRecorder()
+ router.ServeHTTP(w, req)
+
+ require.Equal(t, http.StatusBadRequest, w.Code)
+ require.Contains(t, w.Body.String(), "ambiguous")
+ require.Equal(t, "owner/slug", svc.installSource)
+}
+
func TestSandboxSkillUploadWithoutFileReturns400(t *testing.T) {
svc := &fakeSandboxSkillService{}
router := newSkillTestRouter(NewSandboxSkillHandler(svc, nil))