cnb-rs-skills

把团队/个人反复教 AI 的「怎么用 cnb-rs」这件事，按 agentskills.io 开放标准沉淀为可分发、可版本管理的 SKILL.md 文件。AI agent 在启动时只读 name + description（每个 skill 约 100 tokens），命中任务才加载完整正文，需要细节才读 references/ 子文档 — 渐进式披露，对上下文友好。

19 个 skill = 1 个入口/路由 (cnb-rs) + 18 个专题，按主题分组，覆盖 cnb-rs 除少数 client-side 命令（completion / version / licenses）外的全部能力：

按"我想做什么"反向查 skill 见 INDEX.md。

跳过的命令：completion（shell setup）、version（--version 已覆盖）、licenses（看 cnb-rs 第三方依赖 license，meta 命令 agent 几乎不用）。

提供三种安装方式，按场景三选一：

需要 cnb-rs CLI ≥ 0.12；首次使用先跑 cnb-rs auth login 完成 CNB 认证

# 一次装本仓库全部 19 个 skill（1 入口 + 18 专题）到 auto-detect 的 agent
cnb-rs skill install wwvo/cnb-rs/cnb-rs-skills

# 装到指定 agent（claude-code / copilot / cursor / windsurf / codex / gemini …）
cnb-rs skill install wwvo/cnb-rs/cnb-rs-skills --agent windsurf

# 只装指定 skill（多个用空格分隔）
cnb-rs skill install wwvo/cnb-rs/cnb-rs-skills cnb-rs-pr cnb-rs-issue

# pin 到具体版本（生产推荐，避免 skill 漂移）
cnb-rs skill install wwvo/cnb-rs/cnb-rs-skills --pin v0.2.0

后续维护：

cnb-rs skill list                # 看本机已装哪些 skill
cnb-rs skill update --all        # 升级所有非 pinned skill 到最新
cnb-rs skill remove cnb-rs-pr    # 卸载某个 skill

本仓库根目录已提供 .claude-plugin/marketplace.json，把 19 个 skill 打包成 1 个总包 + 4 个主题 plugin，可直接走 Claude Code /plugin 命令 一键安装：

# 1. 一次性把本仓库注册成 marketplace（只做一次）
/plugin marketplace add https://cnb.cool/wwvo/cnb-rs/cnb-rs-skills.git

# 2a. 装全部 19 个 skill（懒人路线）
/plugin install cnb-rs-skills-all@cnb-rs-skills

# 2b. 按主题分组装（按需路线，主题与下文 Skill 清单一一对应）
/plugin install cnb-rs-core@cnb-rs-skills        # 5 个：入口 + api + auth + info + local
/plugin install cnb-rs-collab@cnb-rs-skills      # 4 个：issue + pr + label + repo
/plugin install cnb-rs-ci@cnb-rs-skills          # 4 个：build + commit + release + download
/plugin install cnb-rs-platform@cnb-rs-skills    # 6 个：group + knowledge + registry + user + workspace + extension

后续维护：

/plugin                                       # 进入交互式 plugin 管理面板
/plugin uninstall cnb-rs-ci@cnb-rs-skills     # 卸载某个 plugin
/plugin marketplace update cnb-rs-skills      # 拉取本仓库最新 SKILL.md

优势：原生 /plugin UI、namespace 隔离防冲突、/plugin marketplace update 一行升级 / 回滚，未来可在同一 plugin 里附带 hooks / slash commands / MCP servers。

要求：Claude Code ≥ 2026-01（plugin 系统上线版本）。CNB 仓库走 git URL 形式，官方文档 明确支持 GitHub 之外的任意 git host。

Claude Code 扫描的标准路径是 ~/.claude/skills/<skill-name>/SKILL.md（只看一层），所以必须把 19 个 skill 子目录分别软链上去，不能直接 clone 整个仓库到 ~/.claude/skills/cnb-rs-skills/（那样 SKILL.md 多嵌套一层，全部 skill 失效）。

# Unix (macOS / Linux / WSL)
git clone https://cnb.cool/wwvo/cnb-rs/cnb-rs-skills.git ~/cnb-rs-skills
mkdir -p ~/.claude/skills
for d in ~/cnb-rs-skills/skills/*/; do
  ln -sfn "$d" "$HOME/.claude/skills/$(basename "$d")"
done

# Windows PowerShell（需管理员权限或开启 dev mode 才能创建 SymbolicLink）
git clone https://cnb.cool/wwvo/cnb-rs/cnb-rs-skills.git $HOME\cnb-rs-skills
New-Item -ItemType Directory -Force -Path $HOME\.claude\skills | Out-Null
Get-ChildItem $HOME\cnb-rs-skills\skills -Directory | ForEach-Object {
  New-Item -ItemType SymbolicLink -Path "$HOME\.claude\skills\$($_.Name)" -Target $_.FullName -Force
}

升级时只需 cd ~/cnb-rs-skills && git pull，软链会自动指到新内容。

如果只想给单个项目用，可以把 skill 放到该项目自己的 .claude/skills/ 下，配合 git submodule 实现"跟随项目仓库版本":

# 在目标项目根目录执行
git submodule add https://cnb.cool/wwvo/cnb-rs/cnb-rs-skills.git .claude/_cnb-rs-skills
mkdir -p .claude/skills
for d in .claude/_cnb-rs-skills/skills/*/; do
  ln -sfn "../_cnb-rs-skills/skills/$(basename "$d")" ".claude/skills/$(basename "$d")"
done

# 把软链加到 .gitignore，submodule 本体跟随项目 commit
echo '.claude/skills/cnb-rs-*' >> .gitignore

团队成员 clone 项目后只需 git submodule update --init 即可拉齐，无需再额外装 cnb-rs CLI。

装好后，AI agent 会自动根据 description 中的关键词触发对应 skill，例如：

> 帮我看下 wwvo/cnb-rs/cnb-rs 里 open 状态的 PR 列表，按更新时间倒序

Claude Code 会命中 cnb-rs-pr skill，自动用 cnb-rs --repo wwvo/cnb-rs/cnb-rs pr list --state open --json 之类的命令完成任务。

也可以显式调用：

> 用 cnb-rs-api skill 帮我 POST /{repo}/-/issues 创建一个 issue

1. 本地 dev 优先：本仓库 skill 主要为本地 agent 设计，假定 cnb-rs 安装在 $PATH 且已 auth login。CI Pipeline 内的 npc 自动化场景请用 cnb/skills/cnb-skill 官方 skill。
2. 渐进式披露：SKILL.md 主文件控制在 < 500 行，详细参数表、踩坑清单放进 references/，agent 按需读。
3. 中英双 description：frontmatter description 中英混排，覆盖中英文用户的触发关键词，例如 "创建 PR / create pull request"。
4. 不重复 --help：SKILL 写命令使用模式 + 踩坑，rote 的参数列表请用户 cnb-rs <cmd> --help。
5. dogfood：本仓库的创建就是 cnb-rs repo create cnb-rs-skills --group wwvo/cnb-rs --license Apache-2.0 --clone 一行完成的。

仓库根有 .cnb.yml 在 push / PR 触发自动校验 SKILL.md frontmatter 合规。

本地预检 = CI 同一条命令（唯一推荐入口）：

uv sync && uv run --frozen scripts/validate.py

首次跑 uv sync 会按 pyproject.toml + uv.lock 自建 .venv/；后续 uv run --frozen 直接复用。无需手动 pip install / python -m venv。

scripts/ 下另有两个辅助工具，按需手动跑：

# 字段长度 / form 分布报表 — 看哪些 description / compatibility 字段过长、哪些还是 plain 形式
uv run scripts/analyze.py

# 把 long-form 字段批量转 YAML block scalar (`>-`)，roundtrip 校验保字面值零漂移
uv run scripts/fix-block-scalar.py --field compatibility --dry-run
uv run scripts/fix-block-scalar.py --field description --normalize-cjk-spacing

校验内容（按 agentskills.io 0.1 规范 + cnb-rs 仓库约束）：

• frontmatter 首行 ---、紧跟另一个 ---；YAML 解析失败时输出 line / col / caret 定位 + 针对性修复提示
• name 字段非空、符合 [a-z0-9-]{1,64}、禁首尾连字符、禁连续 --、与父目录名完全相等
• description 字段非空、长度 ≤ 1024、不含 < / >
• license 字段（可选）非空
• metadata 字段（可选）必须是 mapping；含手写 cnb-* 保留键时 WARN（提醒会被 cnb-rs skill install/update 覆盖）
• 主文件 ≤ 500 行（超过 warn）
• 清单一致性：README.md / INDEX.md / skills/cnb-rs/SKILL.md / skills/cnb-rs/references/routing.md 必须每个 skill 都至少出现一次；不存在的 cnb-rs-* token 会 WARN（防止重命名 / 删除后漂移）
• metadata.version 形态：建议存在且符合 semver MAJOR.MINOR.PATCH[-prerelease][+build]；缺失 / 非字符串 / 非 semver 形式都会 WARN（非字符串字段同时 FAIL）

依赖管理：pyproject.toml 声明依赖（PyYAML），uv.lock 锁版本，CI 用 uv run --frozen 保 reproducibility。镜像：ghcr.io/astral-sh/uv:python3.13-bookworm-slim（uv 官方，含 Python 3.13）。

每个 SKILL.md 的 metadata.version 用 semver 表达该 skill 主文档 / 触发关键词 / 子命令清单的演进，与上游 cnb-rs CLI 自身版本号互相独立（CLI 的版本由 cnb-rs --version 表示，不在本仓库管）。

bump 节奏建议（warn-only，CI 不强卡）：

全仓库当前都是 1.0.0，后续按上表 bump。cnb-rs skill install/update 在装入 agent 目录时会把 version 一并带过去，便于 agent 端排查"装的是哪一版"。

欢迎 PR。提交前必须 0 FAIL：直接跑 CI 校验 节里的「本地预检」命令；规则细节也在那一节列出。

CI 不校验、但 reviewer 会关心的软约束：

• description 含具体触发关键词（中英双语），让 LLM 能 semantic match 各类用户 query phrasing
• 主文件超 500 行（CI WARN）—— 拆细节到 references/<topic>.md，主文档保持 ≤ 500 行
• 改命令引用前用 cnb-rs <cmd> --help 校对参数 / flag 拼写，避免文档与 CLI 行为漂移
• Commit 遵循 Conventional Commits + emoji（与 cnb-rs 主仓库一致）

• cnb-rs CLI — 非官方 Rust CLI（本仓库教 AI 用的就是它）
• cnb-rs 文档站 — 命令文档（VitePress）
• CNB 官方 skill 仓库 — Pipeline npc 场景
• agentskills.io 规范 — SKILL.md 格式定义
• Anthropic Skill authoring best practices

Apache-2.0