description: >-
  Drafts a changelog from git history grouped by conventional-commit type.
  Use when the user asks to "generate release notes", "write a changelog",
  or "what changed since the last release". Emits Keep-a-Changelog format.

.claude/skills/release-notes-drafter/
├── SKILL.md
├── scripts/
│   └── group_commits.py
└── references/
    └── keepachangelog.md

---
name: release-notes-drafter
description: >-
  Drafts a changelog from git history grouped by conventional-commit type.
  Use when the user asks to "generate release notes", "write a changelog",
  or "what changed since last release", or before tagging a version. Emits
  Keep-a-Changelog format from commits since the last tag.
---

# Release Notes Drafter

You draft human-readable release notes from a repository's git history,
following Keep-a-Changelog. Deterministic grouping is delegated to a bundled
script; you own the prose and the judgment calls.

## When to use
- User asks for release notes / changelog / "what changed".
- About to cut a tag or publish a release.

## When NOT to use (negative triggers)
- User just wants a raw commit log — run `git log` directly.
- User only needs a semver bump — defer to a dedicated tool.
- Repo has no conventional commits — warn first, do not silently guess types.

## Workflow (plan → validate → execute)
1. PLAN: run `scripts/group_commits.py <range> --dry-run` to confirm scope.
2. VALIDATE: if the script exits with code 2 (empty range), ask the user for
   the correct revision range instead of guessing.
3. EXECUTE: run `scripts/group_commits.py <range>`, read the JSON, then write
   the changelog. Bucket order: Breaking, Added, Fixed, Performance, Changed,
   then Others. Reference each entry's short SHA.
4. Return the draft in a fenced block; list any commits you could not classify.

See `references/keepachangelog.md` for exact section headings and tone.

#!/usr/bin/env python3
"""Group conventional commits into changelog buckets.
Agent-facing: CLI args in, JSON out, meaningful exit codes."""
import sys, json, subprocess, re, argparse

TYPE_MAP = {
    "feat": "Added", "fix": "Fixed", "perf": "Performance",
    "refactor": "Changed", "docs": "Documentation", "test": "Tests",
    "chore": "Maintenance", "build": "Build", "ci": "CI",
}
CONV = re.compile(
    r'^(feat|fix|perf|refactor|docs|test|chore|build|ci)(\([^)]+\))?(!)?:\s*(.+)$',
    re.I)

def resolve_range(rng):
    if rng:
        return rng
    try:
        tag = subprocess.check_output(
            ["git", "describe", "--tags", "--abbrev=0"],
            stderr=subprocess.DEVNULL, text=True).strip()
        return f"{tag}..HEAD"
    except subprocess.CalledProcessError:
        return ""

def collect(rng):
    cmd = ["git", "log", "--pretty=format:%H%x09%s"]
    if rng:
        cmd.append(rng)
    out = subprocess.check_output(cmd, text=True, stderr=subprocess.DEVNULL)
    groups, misc = {}, []
    for line in out.splitlines():
        if "\t" not in line:
            continue
        sha, subj = line.split("\t", 1)
        m = CONV.match(subj)
        if m:
            typ, scope, bang, msg = m.groups()
            label = "Breaking" if bang else TYPE_MAP.get(typ.lower(), "Changed")
            groups.setdefault(label, []).append(
                {"sha": sha[:8], "scope": scope or "", "msg": msg.strip()})
        else:
            misc.append({"sha": sha[:8], "msg": subj.strip()})
    return {"range": rng or "all", "groups": groups, "misc": misc}

def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("range", nargs="?", default="")
    ap.add_argument("--dry-run", action="store_true")
    args = ap.parse_args()
    if args.dry_run:
        print(json.dumps({"action": "would-parse", "range": args.range or "auto"}))
        return 0
    result = collect(resolve_range(args.range))
    if not result["groups"] and not result["misc"]:
        print(json.dumps({"error": "no commits in range", "range": result["range"]}))
        return 2
    print(json.dumps(result, indent=2, ensure_ascii=False))
    return 0

if __name__ == "__main__":
    sys.exit(main())

{
  "range": "v1.2.0..HEAD",
  "groups": {
    "Added": [{"sha": "a1b2c3d4", "scope": "(auth)", "msg": "support OIDC login"}],
    "Fixed":  [{"sha": "e5f6g7h8", "scope": "",       "msg": "null crash on empty payload"}]
  },
  "misc": []
}

# Keep-a-Changelog 参考
- 段落顺序：Added → Changed → Deprecated → Removed → Fixed → Security
- 语气：过去时、面向使用者，不要写实现细节
- 每条以短 SHA 收尾，便于回溯

allowed-tools:
  - Read
  - Bash(python3 scripts/group_commits.py:*)
  - Bash(git log:*)
  - Bash(git describe:*)

flowchart TD
    U[用户: 生成本次发布说明] --> CC{Claude Code 会话}
    CC -->|L1 扫描全部 frontmatter| D[匹配 description?]
    D -->|是| L2[加载 SKILL.md 正文]
    D -->|否| SKIP[跳过, 不消耗 token]
    L2 --> PLAN[1.PLAN: dry-run 确认范围]
    PLAN --> VAL[2.VALIDATE: 退出码=2?]
    VAL -->|是| ASK[反问用户范围]
    VAL -->|否| EXE[3.EXECUTE: 运行脚本取 JSON]
    EXE --> L3[按需加载 references/]
    L3 --> WRITE[4.撰写 Keep-a-Changelog 草稿]
    WRITE --> OUT[返回草稿 + 未分类提交]
    ASK --> PLAN

    subgraph 跨平台复用
      P1[Claude Code<br/>.claude/skills/]
      P2[Codex<br/>兼容 SKILL.md]
      P3[OpenClaw<br/>ClawHub]
    end
    SKILL[同一份 SKILL.md 目录] --> P1
    SKILL --> P2
    SKILL --> P3