Skill 示例：发布说明生成

适用场景

每次发版都要手动翻提交记录，整理成「新增、修复、变更」。这是典型适合做成 Skill 的工作：步骤固定、需要读取仓库实时状态、输出格式有要求，但又不值得写进每次会话都加载的 CLAUDE.md。

Skill 是一个目录，里面的 SKILL.md 写明指令。Claude 觉得相关时会自己加载，你也可以用 /skill-name 直接调用。支持文件按需读取，不占用平时的上下文。

模板

目录结构：

.claude/skills/release-notes/
├── SKILL.md        # 必需：概述与步骤
├── template.md     # 输出格式模板（需要时才读取）
└── examples.md     # 过往好例子（需要时才读取）

.claude/skills/release-notes/SKILL.md：

---
name: release-notes
description: 根据上一个版本以来的 git 提交，生成面向用户的发布说明。在用户要发版、写 changelog、整理版本更新内容时使用。
when_to_use: 例如「帮我写 v1.4.0 的发布说明」「整理一下上次发布以来的改动」。
argument-hint: [上一个版本标签，如 v1.3.0]
allowed-tools: Bash(git log *) Bash(git describe *) Bash(git show *) Bash(git diff *)
---

# 发布说明生成

## 仓库当前状态
最近的版本标签：
!`git describe --tags --abbrev=0 || true`

## 步骤
1. 确定范围：起点是用户给的参数 $ARGUMENTS；为空时用上面的最近标签；仍然没有就询问用户。终点是 HEAD。
2. 读取提交：`git log <起点>..HEAD --no-merges --pretty=format:'%h %s'`。
   提交信息看不出影响时，用 `git show --stat <hash>` 查看改动文件，必要时读 diff。
3. 过滤：忽略纯内部改动（CI 配置、重命名变量、格式化、依赖小版本升级），除非影响使用者。
4. 分类：新增 / 改进 / 修复 / 破坏性变更。破坏性变更必须单独列出并写明迁移方法。
5. 改写：用使用者能看懂的话写「你现在可以做什么」，不要照抄提交信息，不出现内部类名与哈希。
6. 按 [template.md](template.md) 的格式输出，并对照 [examples.md](examples.md) 检查语气。

## 规则
- 只写能从提交和 diff 中确认的内容；拿不准的功能点放进末尾的「待确认」让用户判断。
- 不编造版本号、日期和数字。
- 只输出文本，不修改文件、不打标签、不推送。

怎么用 / 怎么改

1. 把目录放到仓库的 .claude/skills/release-notes/，提交后团队共享；放到 ~/.claude/skills/release-notes/ 则只有你自己所有项目可用。个人和项目的 Skill 会被监视，修改后立即生效。如果是会话中新建的顶层 skills 目录，运行 /reload-skills。
2. 调用方式：输入 /release-notes v1.3.0，参数会代入 $ARGUMENTS。也可以直接说「给我写一下发布说明」，由 Claude 根据描述自动选用。
3. template.md 里放你的固定版式，例如：

## 【版本号】（【日期】）
### 新增
- 【一句话】
### 改进
### 修复
### 破坏性变更
- 【变化】。迁移方法：【步骤】

4. 字段速查：name 是命令名，默认取目录名；description 与 when_to_use 合起来是 Claude 判断是否使用它的依据，要把关键场景写在前面；allowed-tools 列出这次调用中无需再弹权限确认的工具，用空格分隔；argument-hint 只是补全时的提示。
5. 想只允许手动触发（比如会产生副作用的发布、部署类技能），加上 disable-model-invocation: true。本例只读，所以保持默认。

常见问题或注意事项

• 动态命令必须预先授权。 ! 开头的命令会在内容发给 Claude 之前执行，其输出替换占位符。命令若没有被 allowed-tools 或权限规则放行，调用会中止。命令以非零状态退出同样会中止，所以可能失败的命令要补 || true，就像例子里没有任何标签时那样。
• 字段名必须一字不差。 未识别的字段会被静默忽略，不会报错。注意 when_to_use 是下划线，argument-hint、allowed-tools 是连字符。
• SKILL.md 保持精简。 官方建议控制在 500 行以内，细节放进旁边的文件，并在正文里说明什么时候读它们。
• 参数含空格要加引号。 比如 /release-notes "v1.3.0 rc1"，否则会被拆成两个参数。
• 别用保留的目录名。 不要把技能目录命名为 synced 或 anthropic-skills，它们留给从 claude.ai 同步的技能。
• 命名冲突时的优先级。 企业级高于个人，个人高于项目。