cnb-rs skill init

cnb-rs skill init [<NAME>] [--dir <PATH>] [--force]

在目标目录创建一个 SKILL.md 模板（含完整 frontmatter + 中文引导注释），让你 0 摩擦开始写新 skill。

参数

• <NAME>：skill 名（可选）。不传时用目标目录的 basename。例如在 ~/code/my-skill/ 跑 cnb-rs skill init 会拿 my-skill 作为 name

选项

• --dir <PATH>：输出目录（默认当前目录）。会自动 mkdir -p
• --force：覆盖已存在的 SKILL.md（注意：会丢失手工编辑内容）

行为：3 步流程

1. 解析 name：显式 <NAME> 优先；否则取目标目录 basename
2. 安全检查：<dir>/SKILL.md 已存在 → fail-fast，提示用 --force 覆盖；name 含 / 或 \ → 拒绝（防意外路径穿越）
3. 写盘：std::fs::write 模板内容（${NAME} 占位符已替换）+ stdout 打印「下一步」3 行引导

关键设计

0 网络 / 0 lockfile / 0 cnb-* 注入

init 是纯本地操作：不调 API，不读写 lockfile，不在 frontmatter 写任何 cnb-host / cnb-repo 等元数据。

后者刻意为之 —— 这些字段只在被 install 安装时由 frontmatter::inject_cnb_metadata 注入。作者自己写的 skill 模板不应该硬编码这些（否则 publish 到其它仓库就错了）。

模板内容

模板含：

• 完整 frontmatter：name / description / allowed-tools / license / compatibility / metadata.version
• 3 个章节骨架：适用场景 / 步骤 / 示例 / 注意事项（含 HTML 注释引导填写要点）
• 作者备忘块（末尾大段 HTML 注释）：
  • frontmatter 关键字段说明
  • 附属文件目录约定（references/ / scripts/ / assets/ / templates/）
  • 如何推到 CNB 仓库供 install
  • 本地测试方法（install . <NAME> --dir /tmp/preview --copy）
  • 提醒「cnb-* 字段交给 install 注入，作者不要手写」

模板大小约 1.8 KB，按 agentskills.io 规范写。

路径安全

name 含 / 或 \ → 直接拒绝（防 cnb-rs skill init "../../etc" 这类意外写盘到 cwd 之外）。

输出示例

当前目录创建

$ cd my-new-skill
$ cnb-rs skill init
✓ 已创建 SKILL.md（1830 bytes）→ /home/alice/my-new-skill/SKILL.md

下一步：
  1. 编辑 SKILL.md，填好 description + 步骤 / 示例
  2. 把目录推到 CNB 仓库 skills/my-new-skill/ 下（与其它 skill 一起）
  3. 别人即可用 cnb-rs skill install <REPO> my-new-skill 装到本地

指定 name + 目录

$ cnb-rs skill init my-skill --dir ~/code/skills-repo/skills/my-skill
✓ 已创建 SKILL.md（1830 bytes）→ /home/alice/code/skills-repo/skills/my-skill/SKILL.md

下一步：
  ...

错误示例

SKILL.md 已存在（无 --force）

$ cnb-rs skill init
错误: SKILL.md 已存在：/home/alice/my-skill/SKILL.md

提示：用 --force 覆盖（注意：会丢失手工编辑的内容）

name 含路径分隔符

$ cnb-rs skill init "../../etc"
错误: skill 名 '../../etc' 不合法：必须非空且不含路径分隔符

提示：用 cnb-rs skill init <NAME> 显式指定一个合法名

cwd basename 无法提取（极端情况，如 cwd 是 /）

$ cd /
$ cnb-rs skill init
错误: 无法从目录路径 '/' 提取 basename 作为 skill 名

提示：用 cnb-rs skill init <NAME> 显式指定

退出码

• 0：SKILL.md 成功创建
• 1：业务错误（已存在 / name 不合法 / 写盘失败）
• 2：clap 参数错（很难触发，因为所有 args 都是 optional）

完整 workflow

# 1. 创建新 skill 目录 + 生成模板
$ mkdir -p ~/code/my-skills-repo/skills/awesome-tool
$ cd ~/code/my-skills-repo/skills/awesome-tool
$ cnb-rs skill init

# 2. 编辑 SKILL.md（用任何编辑器）
$ $EDITOR SKILL.md

# 3. （可选）加附属文件
$ mkdir references
$ $EDITOR references/api-reference.md

# 4. 本地预览安装（不污染真实 ~/.agents）
$ cd ~/code/my-skills-repo
$ git add . && git commit -m "feat: awesome-tool skill"

# 5. 推到 CNB
$ git push origin main

# 6. 让别人装
$ cnb-rs skill install <YOUR-OWNER>/<YOUR-GROUP>/<YOUR-REPO> awesome-tool

与其它脚手架的对比

维度	cnb-rs skill init	gh skill init	npx create-skill
依赖	无	需 gh CLI	需 npm / node
输出大小	1.8 KB	~3 KB	~10 KB（含 lint）
中文引导	✅	❌	❌
--force	✅	✅	✅
自定义目录	--dir	cwd only	--dir
作者备忘块	✅（HTML 注释）	部分	❌
不注入 cnb-*	✅（design 决策，避免 publish 错乱）	n/a	n/a

另请参阅

• cnb-rs skill
• cnb-rs skill install — 装别人写的 skill
• cnb-rs skill preview — 看别人怎么写的
• cnb-rs skill list
• agentskills.io — skill 规范