Release Changelog
根据仓库中的 Conventional Commits 自动生成或更新 CHANGELOG.md，适用于发布前整理变更、打 tag 前统一记录版本历史。本 skill 包含一个 Node 脚本，可在任意 Git 仓库根目录执行。
何时使用
- 用户说「准备发版」「更新 CHANGELOG」「根据 commit 生成 changelog」「release 前整理变更」
- 需要把最近一批 commit 按类型整理成 Keep a Changelog 格式
- 打新 tag / 发新版本前要写一段版本说明
- 团队约定使用 Conventional Commits（
feat:,fix:,docs:等），希望自动汇总
前置条件
- 当前目录是 Git 仓库根目录（或通过
--repo指定） - 已安装 Node.js（脚本为 ESM，无额外依赖）
- Commit 消息尽量符合 Conventional Commits（不强制，不符合的会归入「Other」）
使用方式
1. 确定脚本路径
若通过 npx skills add 安装本 skill，脚本位于 skill 目录下的 scripts/update-changelog.mjs。例如全局安装后可能在：
- macOS/Linux:
~/.agents/skills/<provider>/coding-skills/release-changelog/scripts/update-changelog.mjs - 或 Cursor/Codex 的 skills 目录中的对应路径
在要生成 CHANGELOG 的仓库根目录执行：
node /path/to/release-changelog/scripts/update-changelog.mjs [选项]
若把本仓库 clone 到本地，可直接在项目根目录执行：
node /path/to/coding-skills/skills/release-changelog/scripts/update-changelog.mjs
2. 常用命令
# 自上次 tag 以来的 commit 生成「Unreleased」段落，只打印不写文件
node scripts/update-changelog.mjs --dry-run
# 同上，并写入 CHANGELOG.md（无则创建）
node scripts/update-changelog.mjs
# 生成并写入，且新段落版本号为 1.2.0，带日期
node scripts/update-changelog.mjs --version 1.2.0
# 从指定 ref 开始（默认是上一个 tag），例如从 main 分支
node scripts/update-changelog.mjs --since main
# 指定仓库路径（默认为当前目录）
node scripts/update-changelog.mjs --repo /path/to/your/repo
3. 选项说明
| 选项 | 说明 | 默认 |
|---|---|---|
--dry-run | 只输出将要写入的内容，不修改文件 | - |
--version <ver> | 新段落版本号（如 1.2.0），不写则用 Unreleased | Unreleased |
--since <ref> | 从该 ref 之后的 commit 统计（tag 或分支名） | 上一个 tag |
--repo <path> | 目标 Git 仓库根目录 | process.cwd() |
--changelog <path> | CHANGELOG 文件路径 | CHANGELOG.md |
Conventional Commits 映射
脚本将 commit type 映射到 Keep a Changelog 的段落：
| Type | Changelog 段落 |
|---|---|
feat | Added |
fix | Fixed |
docs | 归入 Changed（可再细化为 Docs） |
style, refactor, perf, test, chore | Changed |
BREAKING CHANGE 或 ! in scope | Breaking（单独一段或高亮） |
| 其他 | Other |
Commit 格式建议：type(scope): description，例如：
feat(auth): add SSO loginfix(api): correct pagination totaldocs: update README install steps
输出示例
执行后会在 CHANGELOG.md 顶部插入新段落，例如：
## [Unreleased] - 2025-02-03
### Added
- feat(auth): add SSO login (#42)
- feat(api): support filter by date range
### Fixed
- fix(api): correct pagination total (#38)
### Changed
- docs: update README install steps
- refactor(store): simplify state shape
若使用 --version 1.2.0，则标题为 ## [1.2.0] - 2025-02-03。
与 Agent 协作
当用户要求「准备发版」「更新 CHANGELOG」时：
- 确认当前对话所在目录是目标仓库根目录，或让用户提供仓库路径。
- 先执行一次
--dry-run，把输出贴给用户确认。 - 用户确认后再执行无
--dry-run的命令，写入CHANGELOG.md。 - 若用户要打 tag，可建议：
git tag -a v1.2.0 -m "Release 1.2.0"，并提醒 push tags。
注意事项
- 脚本只追加/插入新段落，不会重写已有版本历史；若需调整旧内容请手动编辑。
--since未指定时使用「上一个 tag」；若仓库尚无 tag，则从全部历史取 commit（可能很多），建议首次使用--since HEAD~50或指定分支做试验。- 若 CHANGELOG 已存在
## [Unreleased]，脚本会在其下合并本次生成的条目，避免重复插入同一版本块。
脚本位置小结
- 本 skill 目录：
skills/release-changelog/ - 可执行脚本：
skills/release-changelog/scripts/update-changelog.mjs - 无
package.json依赖，仅需 Node 运行 ESM（Node 14+）。