multica-skill-importing

将技能导入 Multica

当用户已经提供了技能 URL、slug，或明确表示要将某个特定技能导入当前 Multica 工作区时，使用本技能。

不要用本技能来判断用户需要哪个技能。如果用户只描述了某项能力，且没有已知 URL，外部搜索可能会给出候选 URL，但本导入技能只有在已知 URL 或具体导入目标后才会启动。

下文每一项论断都可在 references/skill-importing-source-map.md 中追溯到来源。如有疑问，请阅读该文件。

不变量

只有当技能存在于当前工作区的技能数据库中时，它才算为 Multica 安装完成。将其写入该数据库的唯一受支持路径是工作区导入端点。它接受托管 URL 或上传的本地归档（.skill / .zip），由以下 CLI 驱动：

multica skill import --url <url> --output json              # hosted source
multica skill import --file <path-to.skill> --output json   # local archive

该 CLI 默认使用 --on-conflict fail。URL 导入会发送：

POST /api/skills/import
Content-Type: application/json
body: { "url": "<url>", "on_conflict": "fail" }

--file 导入会以 multipart/form-data 形式命中同一路由，包含一个 file 部分（.skill / .zip 字节）和一个 on_conflict 字段。--url 和 --file 互斥；二者必须且只能提供一个。

不要以 npx skills add 结束。那会安装到外部/本地技能环境，而不是 Multica 工作区数据库，因此 Multica 无法管理或绑定它。

支持的 URL 来源类别

detectImportSource 接受以下主机（以及 www. 变体）。将以下任意形式传给 multica skill import --url <url> --output json：

multica skill import --url clawhub.ai/owner/skill --output json
multica skill import --url skills.sh/owner/repo/skill --output json
multica skill import --url github.com/owner/repo --output json
multica skill import --url github.com/owner/repo/tree/main/path/to/skill --output json
multica skill import --url github.com/owner/repo/blob/main/path/to/SKILL.md --output json

• clawhub.ai、skills.sh、github.com 是已识别的主机。
• GitHub URL 可以是裸 owner/repo、/tree/{ref}/... 目录，或 /blob/{ref}/.../SKILL.md 文件。
• 裸 ClawHub slug（无主机）会被接受并路由到 ClawHub。
• 任何其他主机都会被拒绝，并返回 400，指明支持的来源。

本地归档导入（.skill / .zip）

multica skill import --file <path> --output json 会从本地归档而非托管 URL 导入技能。.skill 文件是标准 zip —— Anthropic 的 skill-creator package_skill 生成的格式 —— 技能文件夹的普通 .zip 也可以。服务器会：

• 在同一 POST /api/skills/import 路由上以 multipart/form-data（一个 file 部分加一个可选的 on_conflict 字段）接受上传；
• 解压它，并以最浅层的 SKILL.md 为根，因此根级 SKILL.md 和嵌套的 my-skill/SKILL.md 包装布局都可接受；
• 从 SKILL.md frontmatter 中获取名称/描述，若没有则回退到包装目录名，再回退到上传的文件名；
• 携带支持文件 —— 丢弃任何 SKILL.md、dotfile、__MACOSX、许可证文件和二进制资产 —— 在每文件（1 MiB）、每包（8 MiB）和文件数（256）上限方面与 URL 导入相同，并拒绝路径遍历（zip-slip）；
• 返回与 URL 导入相同的结构化结果信封，并遵循相同的 --on-conflict 策略。

上传本身的上限为 16 MiB（压缩后）。任何非本地归档的来源仍走 --url。

直接 URL 流程

1. 当请求包含具体 URL 时，可以直接调用导入端点；API 不要求先进行搜索：

multica skill import --url <url> --output json

2. 将响应视为唯一事实来源。当前 CLI 导入使用结构化导入结果信封：

{
  "status": "created|updated|conflict|skipped|failed",
  "reason": "...",
  "skill": { "...": "SkillWithFilesResponse when created/updated" },
  "existing_skill": { "id": "...", "name": "...", "can_overwrite": true }
}

对于 created / updated，skill 是一个工作区 SkillWithFilesResponse：它嵌入标准的 SkillResponse，并新增支撑性的 files 数组。报告相关字段：

• status 与 reason（如果存在）。
• skill.id / skill.name / skill.description。
• skill.config.origin（来源：该技能是从哪个来源导入的 —— 仅当来源提供了 origin 时才设置，因此应视为可能不存在）。
• skill.files / 文件数量。
• skill.created_at / skill.updated_at。
• 当状态为 conflict、skipped，或因已存在技能而 failed 时，报告 existing_skill.id / existing_skill.name。

由于响应是结构化的，应读取这些返回字段，而不是猜测导入是否成功。

3. Agent 与技能的绑定是另一项可变操作。add 会保留现有分配并追加新 id：

multica agent skills add <agent-id> --skill-ids <skill-id> --output json
multica agent skills list <agent-id> --output json

在最后执行 multica agent skills list <agent-id> --output json 后，先确认目标技能 id 存在，再声称该技能对该 Agent 可用。

增量 add 与全量替换 set

multica agent skills add 是增量的：服务端插入这些分配，而不会清除现有分配（AddAgentSkills）。

multica agent skills set 是全量替换：服务端清除当前所有分配，然后重新添加你传入的 id，且仅添加这些 id（SetAgentSkills）。set 是替换路径。只向 set 传入一个 id，会让该 Agent 只剩下这一个技能，并丢弃此前所有分配。

保留的 SKILL.md 支撑文件

技能的主要内容是其 SKILL.md。该文件名是保留的：守护进程在准备执行环境时，会将主要内容写入 SKILL.md 本身，因此某个支撑文件也不能同样命名为 SKILL.md（IsReservedContentPath；该检查会清理路径且不区分大小写，因此 ./SKILL.md 和 sub/../SKILL.md 也会被捕获）。

导入或创建技能时的实际影响：如果清单中列出了一个名为 SKILL.md 的支撑文件，服务端会静默丢弃它 —— 导入仍然成功，但该条目不会出现在返回的 files 中。因此，如果你预期的某个支撑文件缺失，请检查它是否被命名为 SKILL.md；将其重命名为非保留路径。（硬性的 400 拒绝 —— “SKILL.md is reserved for the primary skill content” —— 只会在专用的单文件端点 PUT /api/skills/{id}/files 上触发，而不会在导入时触发。）

同名冲突：--on-conflict

默认行为是安全的：multica skill import --url <url> 等同于 --on-conflict fail。如果导入的技能名称已存在，命令会打印结构化的 conflict 结果并以非零状态退出；不会创建或更新任何技能。

仅在用户明确要求或意图清晰时，才选择显式策略：

• --on-conflict fail（默认）：遇到冲突时不执行任何操作；报告 status: conflict 并附带建议覆盖或重命名的原因。
• --on-conflict overwrite：就地更新已有的同名技能，但仅当当前用户是该技能的原始创建者时才可行。这会保留技能 ID、created_by、created_at 以及 agent-skill 绑定；它会替换描述、内容、来源配置和支持文件。非创建者会得到 status: failed。
• --on-conflict rename：创建一个带有自动后缀（如 -2 / -3）的新技能；现有技能不受影响。
• --on-conflict skip：不触碰现有技能，并报告 status: skipped。

具体示例：

# Safe default. Fails with status=conflict if review-helper already exists.
multica skill import --url https://skills.sh/acme/repo/review-helper --output json

# Replace the existing same-name skill, preserving its ID and agent bindings.
multica skill import --url https://skills.sh/acme/repo/review-helper --on-conflict overwrite --output json

# Keep the existing skill and import a copy such as review-helper-2.
multica skill import --url https://skills.sh/acme/repo/review-helper --on-conflict rename --output json

# Batch-friendly behavior: leave the existing skill alone and mark it skipped.
multica skill import --url https://skills.sh/acme/repo/review-helper --on-conflict skip --output json

旧版兼容性：不发送 on_conflict 的客户端保留旧契约。重复导入会返回 409，响应体携带现有工作区技能的身份信息：

{
  "error": "a skill with this name already exists",
  "existing_skill": {
    "id": "<skill-id>",
    "name": "<skill-name>"
  }
}

当前 CLI 会将这种旧格式规范化为 status: conflict，并对默认的 fail 策略以非零状态退出。将 existing_skill.id 和 existing_skill.name 视为事实来源，然后按需获取详细信息：

multica skill get <skill-id> --output json

较旧的服务器可能返回 409，其响应体只是一个字符串，如 a skill with this name already exists，没有 existing_skill 键。请自行查找现有的工作区技能以恢复：

multica skill list --output json
multica skill get <skill-id> --output json

然后报告该技能已存在，并包含其 id / name。不要循环重试，也不要为了绕过冲突而以不同的名称创建第二个技能。

更新已导入的技能：multica skill refresh

当目标是拉取工作区中已有技能的最新版本时，优先使用 refresh，而不是重新输入导入 URL：

multica skill refresh <skill-id> --output json

它会发送 POST /api/skills/{id}/refresh（空请求体）。服务器会从技能 config.origin 中存储的来源（github、skills_sh，或带 source_url 的 clawhub）重新下载 bundle，并就地覆盖该技能：

• 保留：技能 ID、created_by、created_at、agent-skill 绑定和标签——Agent 无需重新添加即可保留该技能。
• 替换：名称（采用上游重命名）、描述、SKILL.md 内容、来源配置以及完整的支持文件集。
• 权限：技能创建者或工作区 owner/admin——比 import --on-conflict overwrite 更宽泛，后者仅限创建者。

成功响应是普通的 SkillWithFilesResponse（与 multica skill get --with-content 形状相同），而不是导入结果封装。以下失败模式应报告，而不是循环重试：

• 422：该技能没有可刷新的来源（手动创建、从本地归档导入，或从本地运行时复制）。请改为重新导入。
• 409：上游重命名了该技能，而另一个工作区技能已使用该名称；未做任何更改。
• 403：调用者既不是创建者也不是工作区管理员。
• 502 / 503 / 504 / 413：上游获取失败（已删除、不可用、超时，或现在超出导入上限）；该技能保持不变。

回读 skill：默认仅返回元数据

multica skill get 和 multica skill files list 只返回元数据—— 每个文件的路径、字节大小和内容哈希，以及 SKILL.md 正文的大小和哈希。这正是上述冲突检测和校验步骤所需要的，也正是它让大型 skill 始终可被查看：把每个正文都内联进来，会导致一个约 600KB 的 skill 在慢速链路上无法获取（GH #7498）。

multica skill get <skill-id> --output json                  # metadata
multica skill get <skill-id> --with-content --output json   # bodies inlined
multica skill files list <skill-id>                         # paths and sizes

只有在你打算读取内容时才使用 --with-content。要查明某个 skill 为什么这么大，默认输出已经给出了答案：size 列会指明是哪个文件。

错误 → 正确

错误（绕过了 Multica）：

npx skills add https://skills.sh/owner/repo/skill

该 skill 可能在本地存在，但 Multica 无法将其作为工作区 skill 进行管理。

普通添加时的错误 Agent 绑定（会替换掉所有现有分配）：

仅用新 skill id 调用 set 会清除该 Agent 的其他 skill。若要添加，请使用 add。

正确导入：

multica skill import --url https://skills.sh/owner/repo/skill --output json

导入后的 Agent 绑定，适用于调用方有意要变更该 Agent 的 skill 分配的情况：

multica agent skills add <agent-id> --skill-ids <skill-id> --output json
multica agent skills list <agent-id> --output json

参考

• references/skill-importing-source-map.md —— 上述每项行为都映射到 server/ 中的 file:line，并附有可重新推导这些行号的校验命令。