# Skill 示例：发布说明生成

> 一个完整的 SKILL.md 示例，读取上个版本以来的 git 提交，按用户视角生成发布说明，含目录结构、frontmatter 字段、参数与动态命令用法。

## 适用场景

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

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

## 模板

目录结构：

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

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

````markdown
---
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` 里放你的固定版式，例如：

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

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 同步的技能。
- **命名冲突时的优先级。** 企业级高于个人，个人高于项目。