cnb-rs skill install

cnb-rs skill install <REPO> [SKILL]... [options]

从 CNB 仓库装一个或多个 skill 到本地 AI agent：递归下载整个 skills/<name>/ 目录（含 references/ / templates/ 等子目录），向 SKILL.md frontmatter 注入 cnb-* 元数据，然后写盘到指定 scope，并在每个 agent 目录创建 symlink（Windows 自动 fallback 到 copy）。

最后向 lockfile (~/.agents/.skill-lock.json schema v3) upsert 一条 sourceType: "cnb" 的 entry。

参数

• <REPO>：CNB 仓库标识，三段路径 <owner>/<group>/<repo>（如 wwvo/cnb-rs/cnb-rs-skills）或完整 URL；支持 @<ref> 后缀指定 branch / tag / commit
• [SKILL]...：要装的 skill 名（多个空格分隔）；不指定则装仓库 skills/ 下所有 skill

选项

• --scope <SCOPE>：安装 scope，project（默认，当前 git repo root）或 user（home dir）
• --dir <PATH>：自定义目标根目录，覆盖 --scope；测试 / 临时安装友好
• --agent <LIST>：目标 agent（comma 分隔，如 claude-code,windsurf）；不指定则 auto-detect 已装 agent
• --all-agents：装到所有已 detect 的 agent（与 --agent 互斥）
• --pin <REF>：锁定到指定 ref；cnb-rs skill update --all（Phase 2）会跳过此 skill
• --copy：用 copy 而非 symlink 复制到 agent 目录（Windows 上 symlink 失败时自动 fallback 也走 copy）
• --force：lockfile 已有该 skill 时强制覆盖（删旧 + 装新）

继承的全局选项：

• --domain <DOMAIN>：指定目标域名（默认：cnb.cool），当 <REPO> 是非 URL 形式时用作默认 host

行为：9 步安装流程

1. 解析 source：拆 URL → host + <owner>/<group>/<repo> + 可选 @ref
2. 解析 ref：显式 @ref / --pin > 仓库最新 release > 默认分支
3. discover skills/：列仓库 skills/ 目录，过滤出 tree 类型子目录
4. BFS 递归：对每个目标 skill，BFS 列出所有 blob（深度限制 5、总文件 200、总字节 50 MB）
5. 批量下载：用 cnb-api get_raw_text wrapper 拉每个 blob 的 raw bytes（单文件硬上限 5 MB）
6. frontmatter 注入：解析 SKILL.md YAML frontmatter，加入 cnb-host / cnb-repo / cnb-ref / cnb-path / cnb-pinned-ref / cnb-installed-at
7. 写盘：在 <base>/.agents/skills/<name>/ 原子写入所有文件（先 .tmp 再 rename）
8. agent fanout：在每个 target agent 目录创建 skills/<name> 指向 canonical 副本的 symlink；Windows symlink 失败自动 fallback 到 copy
9. lockfile upsert：向 ~/.agents/.skill-lock.json 写入 entry（含 files 列表 + sha + size，update 时 diff 用）

输出示例

基本安装

$ cnb-rs skill install wwvo/cnb-rs/cnb-rs-skills
📦 source: wwvo/cnb-rs/cnb-rs-skills (host=cnb.cool, repo=wwvo/cnb-rs/cnb-rs-skills)
🔖 ref:    main
🎯 targets: 4 skill(s) - skill-foo, skill-bar, skill-baz, skill-qux
🤖 agents: 2 (claude-code, windsurf)
📂 base:   /home/alice/myproj

── skill-foo ──
  [discover] 7 files
  [download] 12345 bytes
  [install]  /home/alice/myproj/.agents/skills/skill-foo → 2 agent dirs
  ✓ installed

── skill-bar ──
  ...

🎉 installed 4 skill(s) / 28 files total to 2 agent(s)

锁定到指定 tag + user scope

$ cnb-rs skill install wwvo/cnb-rs/cnb-rs-skills skill-foo --pin v1.0.0 --scope user
📦 source: wwvo/cnb-rs/cnb-rs-skills (host=cnb.cool, repo=wwvo/cnb-rs/cnb-rs-skills)
🔖 ref:    v1.0.0
🎯 targets: 1 skill(s) - skill-foo
🤖 agents: 1 (claude-code)
📂 base:   /home/alice

── skill-foo ──
  [discover] 7 files
  [download] 12345 bytes
  [install]  /home/alice/.agents/skills/skill-foo → 1 agent dirs
  ✓ installed

🎉 installed 1 skill(s) / 7 files total to 1 agent(s)

错误示例

skill name 在仓库下不存在

$ cnb-rs skill install wwvo/cnb-rs/cnb-rs-skills skill-nonexistent
错误: skill 'skill-nonexistent' 在仓库 wwvo/cnb-rs/cnb-rs-skills 的 skills/ 下不存在

可选: skill-foo, skill-bar, skill-baz, skill-qux

skill 已安装

$ cnb-rs skill install wwvo/cnb-rs/cnb-rs-skills skill-foo
错误: skill 'skill-foo' 已安装（lockfile 已有记录）

提示：用 --force 覆盖（删旧 + 装新）

未 detect 到 agent

$ cnb-rs skill install wwvo/cnb-rs/cnb-rs-skills skill-foo
错误: 未检测到任何已安装的 AI agent

提示：用 --agent <name> 显式指定（如 claude-code / windsurf / cursor），
或先装一个 agent（创建对应目录如 ~/.claude）

skill 缺 SKILL.md

$ cnb-rs skill install wwvo/cnb-rs/cnb-rs-skills skill-broken
错误: skill 'skill-broken' 缺 SKILL.md（agentskills.io spec 必须有）

提示：实际发现的文件：README.md, references/foo.md

仓库 skills/ 目录不存在

$ cnb-rs skill install wwvo/cnb-rs/cnb-rs
错误: 列 'skills/' 目录失败（wwvo/cnb-rs/cnb-rs 是否有 skills/ 子目录？）

退出码

• 0：所有 skill 都安装成功
• 1：任何一步失败（source 解析 / API / 下载 / 写盘 / lockfile）

与 gh skill install 的差异

特性	cnb-rs skill install	gh skill install
source host	cnb.cool（cnb-api JSON）	github.com（GitHub Contents API）
ref 解析	显式 > 最新 release > 默认分支	同
递归子目录	✅ BFS（depth 5 / 200 文件 / 50 MB 硬上限）	✅
单文件硬上限	5 MB	1 MB
frontmatter 注入	✅ cnb-host / cnb-repo / cnb-ref / cnb-path	✅ github-* 系列
Windows symlink fallback	✅ 自动 copy	⚠ 报错退出
lockfile pass-through	✅ 保留 gh / vercel 写的 entry	✅ 保留 cnb / vercel
pin 到指定 ref	✅ --pin	✅ --pin
多 agent fanout	✅ 55 个 agent 配置	✅ 同源

另请参阅

• cnb-rs skill
• cnb-rs skill list — install 后用 list 看 lockfile 元数据
• agentskills.io — skill 规范