从零写一个 Claude Code Skill：release-notes 实操教程

这篇教程从空文件夹开始，带你写一个把 git commits 转成面向用户 release notes 的 Skill，覆盖 SKILL.md 的格式、description 怎么写才能被触发、脚本和参考文件的拆分，以及测试和常见踩坑。适合想自己动手写 Skill 而不只是下载别人现成包的 Claude Code 用户。

Skill 是什么、放在哪

• 一个 Skill 就是一个文件夹里放一个 SKILL.md，是 Claude Code 在请求匹配时才读取的指令集，不装软件、不连账号
• 个人级放在 ~/.claude/skills/<name>/SKILL.md，所有项目可用；项目级放在 .claude/skills/<name>/SKILL.md，随仓库提交给全团队共享
• 文件名必须是大写的 SKILL.md，直接放在 Skill 文件夹内，路径多套一层或小写都会加载失败

SKILL.md 的关键：description

• 文件开头是 YAML front matter，name 用小写加连字符、不能含 claude 或 anthropic，且要与文件夹同名
• Claude 不会通读所有 Skill，只看 name 和 description 来决定是否加载，所以 description 必须同时写清做什么和什么时候用
• 差的写法如 Release notes helper 几乎不触发；好的写法要包含用户实际会说的词，比如 release notes、changelog、what shipped
• 也可以输入 / 加名字直接调用，确保它一定运行

动手写 release-notes Skill

• mkdir -p ~/.claude/skills/release-notes 建文件夹，写入带 front matter 的 SKILL.md
• 步骤设计：先用 git log --oneline 列出提交，剔除用户感知不到的改动（重构、测试、CI、依赖升级），再按 New / Improved / Fixed 三栏各写一行
• 规则部分要求用平实语言、不编造提交里没有的改动、结尾注明覆盖范围如 Changes since v1.4.0
• 新开一个 Claude Code 会话，用自然语言请求 release notes，检查输出是否符合三条规则

用脚本和参考文件给 Skill 瘦身

• SKILL.md 只留步骤和规则，可重复的命令放 scripts/（如 commits.sh），长材料放 references/（如 style.md）
• 指令里用相对路径引用，脚本先 chmod +x 并手动跑通；明确写出何时打开哪个参考文件，避免 Claude 每次都全读
• 脚本适合必须每次结果一致的操作，参考文件适合风格指南、产品名列表这类偶尔才需要的长内容

测试与常见坑

• 用三四种不同说法触发，包括不含 Skill 名字的问法；没触发就把那些词加进 description
• 问一个相近但不同的任务（如总结单个 commit）确认不会误触发，误触发就收窄 description
• 常见错误：description 缺少使用场景、front matter 格式坏（引号包住含冒号的描述）、路径多一层、一个 Skill 干五件事、两个 Skill 描述重叠、把长示例全塞进 SKILL.md
• 规则被反复跳过通常是写得太模糊，要改写成具体指令；最后一定要在真实仓库上跑一遍再分享