changelog-craftlisted
Install: claude install-skill uwakeme/wake-skills
# changelog-craft
维护项目根的 `CHANGELOG.md`:提交时逐笔补 `Unreleased`,发版时归段成版本。格式规范:[Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0)([中文版](https://keepachangelog.com/zh-CN/1.1.0/)),细则与模板见 `references/format.md`。
## 设计原则
| 原则 | 含义 | 反例 |
| --- | --- | --- |
| **说人话** | 每条 entry 写"使用者可感知的变化",不复述 commit message | `fix: fix bug` 原样进日志 |
| **逐笔维护** | diff 还热着的时候写,上下文最全 | 发版前靠回忆整理一个月的改动 |
| **策展** | Unreleased 从宽、版本段收紧,噪音不进 | 30 条 chore 全列上 |
| **纯写作** | 不碰 tag、不碰发布、不自动 commit | 悄悄替用户打 tag 推送 |
## 模式判定(入口)
| 用户意图 | 走哪条 |
| --- | --- |
| 提交意图("提交"、"commit"、"帮我提交这些改动") | **模式 A**:先过下面的判定规则,再走正常提交流程 |
| "生成 / 更新 CHANGELOG"、"这个版本改了啥"、发版语境 | **模式 B** |
## 模式 A — 逐笔(核心)
**判定基于 staged diff**(还没 stage 就先看工作区改动):
| 变化 | 动作 |
| --- | --- |
| 新功能 / 既有行为变化 / bug 修复 / 废弃 / 移除 / 安全问题 | **写**,归入对应大类 |
| 可感知的性能改善 / 有行为影响的依赖升级 | **写** |
| 纯重构 / CI / 构建 / 内部测试 / typo / 纯文档 | **不写**——报告一句"本次无可写条目",不追问 |
| 拿不准 | **写**,并在报告里注明(漏写不可找回,多写可在成段时删) |
**流程**:
1. 无条目 → 报告"本次无可写条目",结束(默认不吵)
2. 有条目 → 按模式 B Step 4 的撰写规则起草 1-3 条,追加进 `Unreleased` 段对应大类
3. 项目还没有 `CHANGELOG.md` → **问一次**"要初始化吗":初始化 = `references/format.md` 的骨架 + SemVer 声明 + 本次条目;**不**主动全量回溯历史(用户要才转模式 B)
4. `CHANGELOG.md` 加入本次 commit 的 staged 文件一起提交(不另起提交);报告写了哪些条目
> 触发机制是提示层约定:建议用户在常维护项目的 `AGENTS.md` / `CLAUDE.md` 里加一行"commit 前按 changelog-craft 检查"。git hook 硬自动化不在本技能范围。
## 模式 B — 成段(发版时)
### Step 1 — 摸底
git tag 列表 + 最新 tag;manifest(`package.json` / `pyproject.toml` 等)的 version;已有 `CHANGELOG.md` 读出覆盖到哪个版本、什么语言、什么分组风格;抽样最近 20 条提交判断语言习