skill-builder

name	skill-builder
description	极简的 skill 构建器。当用户说"创建/新建/做一个 skill""写一个 Claude Code skill / Codex skill""把这套流程做成 skill""skill 怎么写/怎么搭/骨架/模板""帮我搭个 skill""定稿/冻结/发布前检查/确认完成/可以发布了"等时使用。给出 skill 的标准结构、SKILL.md 模板、最小创建步骤,以及【迭代 → 定稿 → 同步 → 发布】分阶段流程:先在本地迭代,定稿(Definition of Done 检查)通过后,才推送 GitHub 并多端同步。

Skill Builder(极简)

从零搭一个 Claude Code / Codex skill。

一个 skill = 一个文件夹

SKILL.md 当入口,其余是零件:

<skill-name>/
├── SKILL.md        # 入口(必需):frontmatter + 指令
├── references/     # 按需细读的参考(可选)
├── assets/         # 图片/素材(可选)
└── examples/       # 示例(可选)

最小创建步骤

1. 定位:一句话说清"做什么 + 何时触发"。
2. 命名:kebab-case 英文,如 meeting-notes。
3. 建目录:99 skills/<name>/SKILL.md。
4. 写 frontmatter(命脉)——description 决定能否被触发,把用户可能说的关键词、同义词、场景都写进去。
5. 写主体四段:核心定位 → 先读这些 → 工作流 → 输出口径。
6. 拆细节:太长的内容挪进 references/,SKILL.md 只留骨架。
7. 自检:重读 description——哪些话能触发?流程是否自洽?

定稿(发布前的 gate)

定稿前:内容只在本地工作版 99 skills/<name>/ 反复改,不外传、不推送、不同步。

定稿 = 跑完这份 Definition of Done,全过才算 freeze:

• description 触发词充分(用户各种说法都能匹配)
• SKILL.md 无 TODO / 占位符 / FIXME / 草稿痕迹
• 流程自洽(通读一遍:步骤连贯、无矛盾、无遗漏)
• 被引用的 references/ assets/ examples/ 文件都真实存在
• 无敏感信息(本地路径、私人内容、密钥、token)
• 命名规范(kebab-case,目录名 == frontmatter name)
• 实跑一次,输出符合预期

定稿后物化标记(在发布版上打 tag):git tag v1.0 && git push origin v1.0

只有定稿通过,才进入下一步。

SKILL.md 模板

---
name: my-skill
description: <触发场景 + 关键词 + 同义词,写满>
---

# <标题>

## 核心定位
<做什么、不做什么,一两句>

## 先读这些
- `references/xxx.md`:<何时读>

## 工作流
### 1. <步骤>
### 2. <步骤>

## 输出口径
<交付什么、不交付什么>

四条原则

• description 是命脉:模型靠它决定是否调用,触发词/同义词写全。
• SKILL.md 要短:骨架在此,长内容拆进 references 按需读。
• 一个 skill 一件事:职责清晰,别做成大杂烩。
• examples 只校准不复刻:风格参考,不是模板。

定稿之后(同步与发布)

⚠️ 必须先通过上方「定稿」检查。定稿通过后,按这套流程把工作版推向各端:

1. 同步 Obsidian:rsync -a --exclude='.DS_Store' "99 skills/<name>/" "$HOME/Library/Mobile Documents/iCloud~md~obsidian/Documents/知识库/skills/<name>/"(保持嵌套结构)
2. 发布版:cp -R "99 skills/<name>" "99 skills/<name>-发布版本";清理 .DS_Store;基于他人作品则 README 顶部加 fork 来源说明、保留 LICENSE/NOTICE。
3. 部署 GitHub:git init -b main + .gitignore + 首次提交(配 git identity)→ PAT 调 api.github.com/user/repos 建仓库 → git -c http.extraHeader="Authorization: Basic $(printf '%s:%s' <user> <token> | base64 | tr -d '\n')" push -u origin main(token 不入 config)→ 加 topics、改 README clone URL → 用完撤销 PAT。
4. 多端一致:源 ⇄ 发布版 ⇄ Obsidian ⇄ GitHub,改完逐处同步。