7up-ai/release-changelog

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 login
• fix(api): correct pagination total
• docs: 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」时：

1. 确认当前对话所在目录是目标仓库根目录，或让用户提供仓库路径。
2. 先执行一次 --dry-run，把输出贴给用户确认。
3. 用户确认后再执行无 --dry-run 的命令，写入 CHANGELOG.md。
4. 若用户要打 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+）。