这个教程解决什么问题
团队里总有一些固定流程的 AI 任务：每周写发版说明、按固定格式整理周报、把日志翻译成人话。每次都要粘贴一大段 prompt，忘了贴就翻车。这篇教程带你把其中一类任务封装成 Claude Skill——做完之后，一句话就能触发整套流程，prompt 不用再管。
先划清两个容易混的概念：slash command 是手动触发的快捷指令，你不敲 /xxx 它绝不执行；Skill 是自动路由的，模型读每个技能的 description，判断当前任务相关才展开正文。Skill 的本体朴素到只有一句话：一个带 SKILL.md 的文件夹。平时只有几十字符的元数据常驻上下文，命中才加载正文和脚本，所以攒几十个也不心疼。这篇用一个真实场景贯穿：写发版说明的 release-notes 技能。
环境与版本
Claude Code 装好即可（Node.js 18.0 以上、内存 4GB 以上是 npm 安装路线的最低门槛，原生安装路线连 Node 都不需要）。实际版本【待补：claude —version 输出】。
claude --version # 确认可用【待补：实际版本号】
mkdir -p .claude/skills/release-notes技能放两级目录，任选其一或都放：~/.claude/skills/ 是个人全局，所有项目可用；项目内 .claude/skills/ 随仓库走，队友克隆即用。同名时项目级覆盖全局级——团队要统一口径，就把技能提交进仓库吃这个机制。目录名即技能名，用小写字母加连字符。
第一步：最小可用版，两个 frontmatter 字段
SKILL.md 里只有 YAML frontmatter 是协议，其余正文都是写给模型看的操作说明。最小可用版只需要 name 和 description 两个字段（协议约束：name 用小写字母、数字、连字符，上限 64 字符；description 上限 1024 字符）：
---
name: release-notes
description: 写发版说明时使用。读取自上个 git tag 以来的提交记录，按
feature/fix/docs 分组生成中文 CHANGELOG 草稿。用户提到"发版说明、
changelog、release notes"时触发。
---
# 发版说明生成
1. 收集自上个 tag 以来的全部提交（方法见下）
2. 按提交前缀分组：feat / fix / docs / refactor
3. 每条翻译成用户视角的一句话，不出现内部模块名
4. 输出 markdown 到 CHANGELOG-draft.md，末尾注明本次提交总数description 是整个机制的关键。模型靠它决定任务路由给谁，写法必须用”用户会原样说出口的话”。反例是”辅助开发者进行版本变更文档的自动化生成”——抽象、没人这么说、永不触发。写完做个自测：把用户最可能说的三句话写下来，逐句检查 description 里有没有对应词，三句全落空这个技能就等于不存在。
第二步：把主流程写成模型能执行的指令
正文写法三条规则：动词开头、给检查点、明确输出契约。“输出 markdown 到 CHANGELOG-draft.md，末尾注明本次提交总数”就是输出契约——模型知道自己该交付什么，你验收有标准。完善后的正文：
# 发版说明生成
## 步骤
1. 运行 scripts/collect-commits.sh，拿到原始提交列表
2. 若脚本失败，改用 git log 逐条手工收集，不要中断流程
3. 按前缀分组：feat→新特性，fix→问题修复，docs→文档，refactor→内部重构
4. 每条提交改写成用户视角：说清"能得到什么"，不说"改了哪个模块"
5. 输出到 CHANGELOG-draft.md；refactor 部分默认折叠，避免吓到用户
## 禁止
- 编造没有的提交；脚本输出为空就直接说明"本周期无提交"
- 在正文出现数据库表名、内部服务名“脚本失败怎么办”这一条别省。生产级和玩具版的差别就在这些分支路径：脚本挂了模型会自己找台阶下（跳过、编造、瞎猜），提前把降级路径写死，它才会老老实实报告异常。
第三步：重活下沉到脚本与 references
确定性的工作（查 git、跑统计）不要让模型逐步推理，写成脚本让技能调用——一次执行，结果确定，还不耗 token：
#!/usr/bin/env bash
# scripts/collect-commits.sh — 输出上个 tag 以来的提交（哈希 + 标题）
set -euo pipefail
last_tag=$(git describe --tags --abbrev=0)
git log "${last_tag}..HEAD" --pretty=format:"%h %s" --no-merges目录最终形态：
release-notes/
├── SKILL.md # 触发条件 + 主流程，模型按需读
├── scripts/
│ └── collect-commits.sh # 确定性操作，直接执行
└── references/
└── style-guide.md # 文风细则，正文里引用，用到才读这利用了技能的渐进加载设计：会话启动时只读 name 和 description；命中后读 SKILL.md 正文；正文里引用的 references 文件和脚本，用到才碰。所以 SKILL.md 正文别超过两百行，固定细节全部外移，技能本体永远只放”路由信息 + 主流程”。
Windows 用户注意：脚本要在 Git Bash 里跑，保存为 LF 换行，CRLF 会让 shebang 行解析出错【待补：实际报错原文】；首次使用前 chmod +x scripts/collect-commits.sh。
第四步：生产级调优与分发
调优只做两件事。其一，触发调优：开新会话用真实话术试触发，命中不了就往 description 里补用户会用词；同一句触发语多试几次记录命中率【待补：实测命中率】。frontmatter 还支持 allowed-tools 等可选字段，用来收紧技能可用的工具范围，取值规则以官方文档为准。其二，分发：把 .claude/skills/release-notes/ 整个目录提交进仓库，走正常的 code review——技能就是代码，改 description 也要过评审，不然半年后没人知道”为什么它总被触发”。
常见坑
坑一：description 写成功能概括。“用于生成 CHANGELOG”这种写法人和模型都难命中。正解是塞进触发词、场景、输入输出各一个：什么任务、用户会说什么话、产出什么东西。
坑二：SKILL.md 变成 prompt 垃圾场。 今天加一条格式要求、明天贴一段示例，三个月后正文八百行，模型读不完、人也改不动。超过两百行就拆 references，正文只留主流程。
坑三：同名技能互相覆盖。 全局和项目各有一个 release-notes 时，生效的永远是项目级。排查”我改的技能怎么不生效”，第一件事就是查有没有同名目录在覆盖。
坑四：老会话里测试新技能。 技能在会话启动时扫描，改完 SKILL.md 必须开新会话再测，旧会话里怎么试都不触发，白白怀疑人生。
最终效果
改造前后是两种工作方式：以前每次写发版说明要人工跑 git log、粘 prompt、手工整理，全程十来分钟还容易漏；现在开个会话说”写个发版说明”，技能自动收集提交、分组、翻译、落文件，人只审一遍草稿。实际耗时对比与草稿截图【待补：实测数据与截图】。这套方法原样适用于周报、站会纪要、客服话术检查——凡”流程固定、输入可变”的任务，都值得先做成 Skill 再说。
