用 Skill 造一个发布日志生成器：从 Git 历史到结构化 CHANGELOG

flowchart LR
    A[Skill 文件夹<br/>release-notes/] --> B[SKILL.md<br/>入口与契约]
    A --> C[scripts/<br/>可执行脚本]
    A --> D[references/<br/>按需加载的参考资料]
    B -->|第一阶段| E[模型发现层<br/>只读 frontmatter]
    B -->|第二阶段| F[模型决策层<br/>读 SKILL.md 正文]
    D -->|第三阶段| G[深度展开层<br/>按需 Read 引用文件]
    C -.调用.-> G

/skill-creator 创建一个名为 release-notes 的 skill，用途是从 git 历史生成 changelog

# 个人级 Skill（所有项目可用）
mkdir -p ~/.claude/skills/release-notes/scripts
mkdir -p ~/.claude/skills/release-notes/references

# 或项目级 Skill（仅当前仓库可用，更推荐用于与代码强绑定的 skill）
mkdir -p .claude/skills/release-notes/scripts
mkdir -p .claude/skills/release-notes/references

release-notes/
├── SKILL.md            ← 入口文件，契约 + 指令
├── scripts/
│   └── parse_commits.py
└── references/
    └── conventional-commits.md

---
name: release-notes
description: "Generate a structured CHANGELOG.md from a repository's git history using the Conventional Commits spec. Group entries by type (feat/fix/perf/...), highlight breaking changes, and emit Markdown. Use when: the user asks to generate release notes, draft a changelog, summarize commits since a tag, or prep a version bump. Not for: analyzing a single commit or writing commit messages."
allowed-tools: Read, Write, Bash, Grep
argument-hint: "[<from-rev>] [--to <rev>] [--dry-run]"
tags:
  - tool:git
  - type:documentation
  - lang:python
user-invokable: true
---

allowed-tools: Read, Write, Bash, Grep

python3 -c "import yaml,sys; d=open(sys.argv[1]).read().split('---')[1]; print(yaml.safe_load(d))" \
  ~/.claude/skills/release-notes/SKILL.md

#!/usr/bin/env python3
"""Parse git log into Conventional Commits groups. Output: JSON to stdout.

Usage:
    parse_commits.py [<from-rev>]            # defaults to <from-rev>..HEAD
    parse_commits.py v1.1.0                  # commits since tag v1.1.0
    parse_commits.py v1.1.0 HEAD             # explicit range
"""
import subprocess, json, re, sys

# feat(api)!: add pagination  ->  type=feat, scope=api, breaking=True
SUBJECT_RE = re.compile(
    r'^(?P<type>\w+)(?:\((?P<scope>[\w-]+)\))?(?P<breaking>!)?:\s*(?P<desc>.+)$'
)

def git(*args):
    return subprocess.run(['git', *args], capture_output=True,
                          text=True, check=True).stdout

def main():
    argv = sys.argv[1:]
    since = argv[0] if argv else None
    until = argv[1] if len(argv) > 1 else 'HEAD'
    rng = f'{since}..{until}' if since else until

    # %H hash, %s subject, %b body; \t and \x1e as separators
    fmt = '%H%x09%s%x09%b%x1e'
    out = git('log', f'--pretty={fmt}', rng)
    records = [r for r in out.split('\x1e') if r.strip()]

    groups, unknown = {}, []
    for rec in records:
        parts = rec.strip().split('\t')
        if len(parts) < 2:
            continue
        h, subj, body = parts[0], parts[1], parts[2] if len(parts) > 2 else ''
        m = SUBJECT_RE.match(subj)
        breaking = 'BREAKING CHANGE' in body
        if not m:
            unknown.append({'hash': h[:7], 'subject': subj})
            continue
        t = m.group('type')
        groups.setdefault(t, []).append({
            'hash': h[:7], 'scope': m.group('scope') or '',
            'desc': m.group('desc').strip(),
            'breaking': breaking or bool(m.group('breaking')),
        })

    print(json.dumps({'range': rng, 'groups': groups,
                      'unknown': unknown, 'count': len(records)}, indent=2))

if __name__ == '__main__':
    main()

chmod +x ~/.claude/skills/release-notes/scripts/parse_commits.py
cd /path/to/your-repo
~/.claude/skills/release-notes/scripts/parse_commits.py v1.1.0

{
  "range": "v1.1.0..HEAD",
  "groups": {
    "feat": [
      {"hash": "a3f2c10", "scope": "auth", "desc": "add OAuth2 login", "breaking": false}
    ],
    "fix": [
      {"hash": "b71e098", "scope": "", "desc": "crash on empty cart", "breaking": false}
    ]
  },
  "unknown": [],
  "count": 2
}

# Conventional Commits 速查

## 提交格式
<type>[optional scope][!]: <description>
[optional body]
[optional footer(s)]

## 类型语义与 CHANGELOG 章节
| type     | 章节               | 严重度  |
|----------|--------------------|---------|
| feat     | Features           | 高      |
| fix      | Bug Fixes          | 高      |
| perf     | Performance        | 中      |
| refactor | Refactor           | 低/省略 |
| docs     | Documentation      | 低/省略 |
| test     | Tests              | 低/省略 |
| chore    | Maintenance        | 省略    |

## 破坏性变更
- subject 里 `type!:` 或 footer `BREAKING CHANGE:` 均算
- CHANGELOG 顶部独立 "⚠ Breaking Changes" 区块

## 版本号推断（SemVer）
- 含 breaking → MAJOR
- 含 feat     → MINOR
- 仅 fix/perf → PATCH

# Release Notes Generator

根据 Git 历史生成结构化 CHANGELOG。

## 工作流

1. **确定范围**。若无参数，用 `git describe --tags --abbrev=0` 取最近 tag 作为起点；
   若无任何 tag，则用仓库首个提交。
2. **解析提交**。运行脚本（确定性步骤，避免幻觉）：
   ```bash
   python3 scripts/parse_commits.py <from-rev>
   ```
   得到 JSON：`{groups, unknown, count}`。
3. **归类渲染**。按 `references/conventional-commits.md` 中的类型→章节映射，
   把 `groups` 渲染为 Markdown。`docs/test/chore` 默认折叠或省略。
4. **破坏性变更**。任何 `breaking: true` 顶部独立成 "⚠ Breaking Changes" 区块。
5. **兜底**。若 `unknown` 非空且占比 >30%，在 CHANGELOG 末尾附
   "## Other Changes" 原样列出，并在回复中提醒用户提交规范不统一。
6. **写文件**。默认追加到仓库根的 `CHANGELOG.md` 顶部（新版本在上）。
   带 `--dry-run` 时只打印不写盘。

## 输出格式
使用 Keep a Changelog 风格：`## [vX.Y.Z] - YYYY-MM-DD` 作版本标题，
下方分 `### Features` / `### Bug Fixes` 等。每条 `- <desc> (<hash>)`。

## 何时加载 references
当你不确定某 type 对应哪个章节、或需要推断版本号时，再 Read
`references/conventional-commits.md`。无需每次都读。

> 帮我生成 v1.2.0 的发布日志，基于上个 tag

> /release-notes v1.1.0 --dry-run

# 回归用例 1：dry-run 应只打印不写盘
claude -p "用 release-notes 基于 v1.1.0 生成 changelog，dry-run 模式" \
  | grep -q "## \[v1.2.0\]" && echo "PASS: 渲染正确" || echo "FAIL"

# 回归用例 2：破坏性变更应出现在顶部区块
claude -p "用 release-notes v1.1.0..HEAD，确认 breaking 变更在最前" \
  | grep -q "Breaking Changes" && echo "PASS" || echo "FAIL"

# 回归用例 3：未知提交占比高时应提醒
claude -p "用 release-notes（该仓库提交不规范）" \
  | grep -qi "提交规范" && echo "PASS: 兜底生效" || echo "FAIL"

mkdir demo-shop && cd demo-shop && git init -q
git config user.email "[email protected]"; git config user.name "Dev"
echo "# demo-shop" > README.md && git add . && git commit -qm "chore: init"
git tag v1.0.0
git commit --allow-empty -qm "feat(auth): add OAuth2 login"
git commit --allow-empty -qm "fix(cart): crash on empty cart"
git commit --allow-empty -qm "feat!(api): rename /users to /accounts

BREAKING CHANGE: endpoint renamed"
git commit --allow-empty -qm "docs: update readme"

> 基于 v1.0.0 生成 v1.2.0 的 CHANGELOG

## [v1.2.0] - 2026-06-26

### ⚠ Breaking Changes
- rename /users to /accounts (5e...)

### Features
- add OAuth2 login (a3f2c10)

### Bug Fixes
- crash on empty cart (b71e098)

### Other Changes
- docs: update readme (c9...)

sequenceDiagram
    participant U as 用户
    participant C as Claude Code
    participant S as SKILL.md
    participant P as parse_commits.py
    participant R as references/
    participant F as CHANGELOG.md

    U->>C: 生成 v1.2.0 changelog
    C->>S: 发现阶段：读 description 命中
    C->>S: 决策阶段：读正文工作流
    C->>P: Bash 跑 parse_commits.py v1.0.0
    P-->>C: 返回 JSON {groups,unknown}
    C->>R: Read conventional-commits.md（按需）
    R-->>C: 类型→章节映射表
    C->>F: Write 渲染后的 Markdown
    F-->>U: 展示生成的 CHANGELOG