mkdir -p ~/.claude/skills/release-notes/scripts
mkdir -p ~/.claude/skills/release-notes/examples

release-notes/
├── SKILL.md            # 入口,必填:frontmatter + 指令
├── template.md         # 输出模板,Claude 按它填
├── reference.md        # Conventional Commits 分类规则,按需加载
├── examples/
│   └── sample.md       # 一份期望输出样例
└── scripts/
    └── categorize.sh   # 可执行脚本,被运行而非被读

---
description: 帮助生成文档
---

---
name: release-notes
description: 为当前或指定版本生成发布说明(release notes / changelog)。当用户询问"这次发版改了什么""上一次 tag 到现在有哪些变更""帮我写 v2.3.0 的更新日志"时使用。
when_to_use: |
  触发短语举例:
  - "帮我写这次发布的 release notes"
  - "上个版本到现在改了什么"
  - "为 v2.3.0 生成更新日志"
  - "整理这周的 commit 做发布"
argument-hint: "[from-tag] [to-tag]"
arguments: [from, to]
allowed-tools: Bash(git log *) Bash(git tag *)
paths: "src/**, package.json, CHANGELOG.md"
---

## 当前发版范围
从 `$from` 到 `$to`(若未给参数,默认取最近两个 tag)。

## 提交历史(已自动拉取)
!`git log $from..$to --pretty=format:"- %s" --no-merges 2>/dev/null || git log --pretty=format:"- %s" --no-merges -20`

## 你的任务
1. 读取 `reference.md` 里的 Conventional Commits 分类规则(仅在需要分类细节时读)。
2. 按规则把上面的提交归类到:✨ 新功能 / 🐛 修复 / ⚠️ 破坏性变更 / ♻️ 重构 / 📦 其他。
3. 严格照 `template.md` 的结构产出发布说明。
4. 若检测到 `BREAKING CHANGE` 或 `!:` 提交,在顶部用醒目方式列出迁移提示。

# Conventional Commits 分类速查
- `feat:` / `feat(scope):` → 新功能 ✨
- `fix:` → 修复 🐛
- 后缀 `!` 或 footer `BREAKING CHANGE:` → 破坏性变更 ⚠️(必须置顶并附迁移说明)
- `refactor:` → 重构 ♻️(不改变外部行为)
- `docs:`,`chore:`,`test:`,`ci:`,`perf:` → 归到"其他 / 内务 📦"
- 中文提交信息(无前缀):按语义归类,拿不准归"其他"。

# v<版本号> 发布说明
> 发布日期:<YYYY-MM-DD>

## ⚠️ 破坏性变更(如有)
-

## ✨ 新功能
-

## 🐛 修复
-

## 📦 其他
-

## 资源
- 完整分类规则见 [reference.md](reference.md)
- 输出结构照 [template.md](template.md)
- 期望格式见 [examples/sample.md](examples/sample.md)

#!/usr/bin/env bash
# 读取 git log,按 Conventional Commits 归类计数
set -euo pipefail
FROM="${1:-}"; TO="${2:-HEAD}"
range="${FROM:+$FROM..}$TO"

git log $range --pretty=format:"%s" --no-merges 2>/dev/null \
| awk '
  /^feat(\(.+\))?!?:/   {feat++; next}
  /^fix(\(.+\))?!?:/     {fix++; next}
  /^refactor:/           {ref++; next}
  /!/                    {brk++; next}
                          {other++}
  END {
    printf "✨ 新功能:%d\n🐛 修复:%d\n♻️ 重构:%d\n⚠️ 破坏性:%d\n📦 其他:%d\n", \
           feat, fix, ref, brk, other
  }'

## 可选:先跑分类统计
在动笔前,可先运行统计,心里有数:
```bash
bash "${CLAUDE_SKILL_DIR}/scripts/categorize.sh" "$from" "$to"

> 给脚本加 `chmod +x` 并不强制(这里用 `bash xxx.sh` 调用),但养成习惯更好。脚本设计原则:**把确定性的脏活交给代码,把判断性的表达交给 Claude**——awk 负责数数,Claude 负责遣词造句和写迁移说明。

## 第 7 步:用 frontmatter 开关,精确控制"谁、在哪、怎么跑"

到这一步你的 Skill 已经能用了。剩下的 frontmatter 字段,是用来回答三个问题的:

**问题一:该你手动触发,还是让 Claude 自动触发?**

| 字段设置 | 你能 `/调用` | Claude 能自动触发 | 描述是否常驻上下文 |
| :--- | :--- | :--- | :--- |
| 默认 | 是 | 是 | 是 |
| `disable-model-invocation: true` | 是 | **否** | **否**(更省 token) |
| `user-invocable: false` | **否** | 是 | 是 |

`release-notes` 这类有明确"发布"动作、最好由人拍板时机的流程,适合加 `disable-model-invocation: true`,避免 Claude 看你 push 了就自作主张写发布说明。反过来,像"遗留系统背景知识"这种用户不会主动 `/`、却希望 Claude 在相关时自己想起来的,就该 `user-invocable: false`。

**问题二:要不要跑在隔离子代理里?**

加 `context: fork`(可配 `agent: Explore`)让 Skill 在独立上下文跑,`SKILL.md` 正文成为驱动子代理的 prompt。好处是不污染主对话、上下文干净;代价是**它看不到你的对话历史**。所以 `context: fork` 只适合"有明确任务步骤"的 Skill——纯指南型 Skill(只有约定没有任务)交给子代理,它会因为拿不到可执行动作而无功而返。

**问题三:要不要临时切模型/切算力?**

`model:` 可在 Skill 激活期间临时换模型(下一轮 prompt 自动恢复);`effort:` 可临时调档(`low/medium/high/xhigh/max`)。比如让 `release-notes` 用 `effort: low` 快速出一版草稿,省时省 token。

此外还有 `disallowed-tools`(激活期间**移除**某些工具,如让无人值守 Skill 不能调 `AskUserQuestion`)、`hooks`(绑定本 Skill 生命周期的钩子)、`shell: powershell`(Windows 下内联命令走 PowerShell)。这些字段官方文档列出有十余个,本教程挑了对触发与行为影响最大的几个讲透。

## 第 8 步:验证——别把"它动了"当成"它对了"

这是最被忽略、却最该做的一步。官方原话很到位:**"看到 Skill 被触发,只说明 Claude 找到了它,不说明它做到了你想要的。"**

按顺序做三件事:

**1. 确认它被发现且能被触发。**

Claude 会列出当前可用 Skill。确认 `release-notes` 在列、描述没被截断。然后故意用**自然语言**(不是 `/release-notes`)测自动触发:

如果 Claude 自动用了这个 Skill,说明 `description`/`when_to_use` 的关键词命中了。

**2. 用 `/doctor` 查描述预算。**

Skill 越多,描述越可能被砍。预算是**模型上下文窗口的 1%**,超了就**从你最不常调用的 Skill 开始砍描述**。`/doctor` 会直接告诉你哪些 Skill 的描述被缩短或丢弃。需要的话:

- 调大预算:`settings.json` 里设 `"skillListingBudgetFraction": 0.02`(2%),或环境变量 `SLASH_COMMAND_TOOL_CHAR_BUDGET` 设固定字符数;
- 给低优先 Skill 瘦身:`skillOverrides` 里把不常用的设成 `"name-only"`,只列名不占描述预算。

**3. 做"开/关"基线对照(判断质量,而非触发)。**

收集几条真实请求,**在全新会话**里分别跑两次:一次 Skill 可用、一次用 `skillOverrides` 设成 `"off"` 关掉,对比产出。为什么强调全新会话?因为你刚写完 Skill 时,作者上下文会掩盖指令的漏洞——同一个会话里 Claude "记得"你的意图,换一个干净会话才暴露真实差距。想做系统化对照,装官方 `skill-creator` 插件:

让它跑隔离的测试用例、打分、出 benchmark,甚至做两个版本的盲测 A/B,确认你的改动是真改进才提交。

> 改了 `SKILL.md` 不用重启——Claude Code 会**实时监听** Skill 目录变化,保存即生效(仅限文本;若 Skill 同时是插件,改了 `hooks/`、`.mcp.json` 等要 `/reload-plugins`)。

## 第 9 步:分发——从个人到团队到全组织

按受众选分发方式:

- **项目级**:把 `.claude/skills/release-notes/` 提交进版本控制,团队 clone 即得;
- **插件**:在仓库根加 `.claude-plugin/plugin.json`,就能以插件形式打包,顺带带上 agents、hooks、MCP server;
- **托管级**:通过 managed settings 全组织下发,用户无法覆盖。

插件 Skill 用 `plugin-name:skill-name` 命名空间,天然不会和其他层冲突。同名优先级是 **enterprise > personal > project**,任意一层都会盖掉同名内置 Skill(你在项目 `.claude/skills/` 放个 `code-review`,就会替掉内置的 `/code-review`)。

---

## 实战案例:完整可运行的 `release-notes` Skill

把前面零散的片段拼成最终产物。四个文件,复制即可跑(前提是仓库有 git 历史和 Conventional Commits 风格的提交)。

**`~/.claude/skills/release-notes/SKILL.md`**:

```yaml
---
name: release-notes
description: 为当前或指定版本生成发布说明(release notes / changelog)。当用户询问"这次发版改了什么""上一次 tag 到现在有哪些变更""帮我写 v2.3.0 的更新日志"时使用。
when_to_use: |
  触发短语:
  - "帮我写这次发布的 release notes"
  - "上个版本到现在改了什么"
  - "为 v2.3.0 生成更新日志"
  - "整理这周的 commit 做发布"
argument-hint: "[from-tag] [to-tag]"
arguments: [from, to]
allowed-tools: Bash(git log *) Bash(git tag *) Bash(bash *)
disable-model-invocation: false
---

## 范围
从 `$from` 到 `$to`;若用户未给参数,默认取最近两个 tag 之间。

## 提交历史(已自动拉取)
!`git log $from..$to --pretty=format:"- %s" --no-merges 2>/dev/null || git log --pretty=format:"- %s" --no-merges -30`

## 可选:先看分类统计
```bash
bash "${CLAUDE_SKILL_DIR}/scripts/categorize.sh" "$from" "$to"

**`template.md`**、**`reference.md`**、**`scripts/categorize.sh`** 见第 4–6 步,原样落入目录即可。

**预期效果**:在一个有提交历史的仓库里输入"把 v1.2.0 到现在的改动整理成发布说明",Claude 自动触发本 Skill,先 `git log` 拉真实提交,跑一遍分类统计,再照模板输出带 emoji 分组、破坏性变更置顶的发布说明。若没自动触发,直接 `/release-notes v1.2.0 HEAD` 手动调用。

---

## 工作流全景图

下面这张图把"从用户输入到 Skill 正文加载"的完整生命周期画清楚了,也是排查触发问题的思维地图:

```mermaid
flowchart TD
    A[用户输入一句话] --> B{Skill 描述预算内?}
    B -- 否:被砍/丢弃 --> X[/doctor 查看<br/>调 skillListingBudgetFraction/]
    B -- 是:描述常驻 --> C[Claude 用描述+when_to_use 匹配]
    C --> D{命中且未被禁?}
    D -- disable-model-invocation:true --> E[仅 /手动调用可达]
    D -- paths 限定 --> F{正在编辑匹配文件?}
    F -- 否 --> G[不自动加载]
    F -- 是 --> H[触发:加载 SKILL.md 正文]
    D -- 默认 --> H
    H --> I[执行 !动态注入:git log 等]
    I --> J{context: fork?}
    J -- 是 --> K[在隔离子代理跑<br/>看不到主对话历史]
    J -- 否 --> L[正文常驻主上下文<br/>直到会话结束/压缩]
    K --> M[按正文产出发布说明]
    L --> M
    M --> N[对照无 Skill 基线<br/>验证产出质量]