changelog-generator

changelog-generator skill 概览

changelog-generator 能做什么

changelog-generator 是一个面向工程发布管理的 skill，用于把 Conventional Commit 历史转换为结构一致、可审计的发布说明。这个 changelog-generator skill 可以帮助 AI agent 解析 commit subject、推断语义化版本升级、生成 Keep a Changelog 风格的分组内容，并把结果接入 CI 或 hotfix 流程，而不是只依赖通用 prompt 生成一段松散的文字。

适合的用户与发布场景

这个 changelog-generator skill 适合需要基于真实 git 历史反复生成 CHANGELOG.md 条目的维护者、release engineer、DevOps 团队和技术写作者。它适用于正式 release cut、PR commit 检查、语义化版本规划、monorepo 包发布，以及需要可追溯证据的紧急 hotfix 说明。

当技术写作者需要把开发者 commit message 转成面向用户的发布说明，同时保留证据链时，它尤其适合作为 Technical Writing 场景下的 changelog-generator：包括 commit range、version、breaking changes、security fixes 和 migration notes。

它与普通 prompt 的区别

普通的“write release notes” prompt 很容易丢失结构，或者凭空推断影响范围。这个 skill 提供了专门的脚本和参考资料：scripts/generate_changelog.py、scripts/commit_linter.py、scripts/version_bumper.py，并包含 changelog 格式、CI 集成、monorepo 和 hotfix 流程方面的指导。因此，它更适合自动化或半自动化的发布工作流。

采用前需要先确认的限制

这个 skill 默认 commit 基本符合 Conventional Commits，例如 feat(auth): add OAuth2 integration 或 fix(api): resolve race condition。如果你的仓库大量使用 updates、misc fixes 这类模糊信息，或者 squash commit 后 subject 缺少有效内容，除非你额外提供上下文，否则输出质量会明显下降。对于不使用 semver 发布策略的团队，版本升级推断结果应作为建议，而不是最终决定。

如何使用 changelog-generator skill

changelog-generator 安装与仓库设置

对于 Claude 风格的本地 skills，把 skill 文件夹复制到你的 skill 目录即可。仓库 README 中给出了类似示例：

cp -R engineering/changelog-generator ~/.claude/skills/changelog-generator

请根据你实际 clone 的仓库位置调整 source path。在生产环境依赖这个 skill 之前，也建议先检查这些文件：

• SKILL.md：agent 面向的工作流说明
• README.md：quick-start 命令
• references/changelog-formatting-guide.md：输出规则
• references/ci-integration.md：CI 示例
• references/monorepo-strategy.md：如果你按包独立发布，需要阅读它
• references/hotfix-procedures.md：紧急发布分类规则

稳定输出所需的输入信息

要让 changelog-generator 得到可靠结果，应提供明确的发布边界和足够的策略上下文。常用输入包括：

• previous tag 和 target tag，例如 v1.2.0..v1.3.0
• target version，或在需要 skill 计算升级幅度时提供 current version
• 如果 agent 无法访问 git，提供来自 git log --oneline 的原始 commit subject
• breaking changes 是否需要 migration notes
• monorepo 的 package scope，例如 payments 或 auth
• 期望输出形式：用于 CHANGELOG.md 的 markdown、用于 CI 的 JSON，或 release announcement draft

较弱的 prompt：“Generate a changelog.”

更好的 prompt：“Use changelog-generator to create a Keep a Changelog entry for v1.4.0 from commits between v1.3.0 and HEAD. Group by Security, Added, Changed, Deprecated, Removed, Fixed. Flag breaking changes, infer the semver bump, and produce a concise markdown entry suitable for CHANGELOG.md.”

实用命令模式

内置工具既可以直接使用，也可以在发布工作流中由 agent 引用。

从 tag range 生成 markdown：

python3 scripts/generate_changelog.py \
  --from-tag v1.2.0 \
  --to-tag v1.3.0 \
  --next-version v1.3.0 \
  --format markdown

在 merge 前 lint commit subject：

python3 scripts/commit_linter.py \
  --from-ref origin/main \
  --to-ref HEAD \
  --strict \
  --format text

当 CI 需要机器可读结果时使用 JSON 输出；当需要人工审阅或追加到 CHANGELOG.md 时使用 markdown。

生成更好发布说明的工作流

建议先 lint commits，再推断版本升级，然后生成 changelog 条目，最后按用户影响进行编辑。最关键的编辑步骤，是把偏实现细节的 message 转成用户能理解的变化，同时不要掩盖重要技术风险。

例如，fix(db): resolve deadlock issues in concurrent transactions 应改写成面向用户的说明，比如“修复了并发账户更新时可能中断操作的数据库死锁问题”，而不是“调整了 transaction locking logic”。

changelog-generator skill FAQ

changelog-generator 只能用于全自动发布吗？

不是。这个 skill 同时适合自动化和编辑型工作流。CI 可以强制 commit 格式或生成 draft notes，而人工可以进一步优化措辞、补充 migration details，并批准最终发布条目。

新手能使用这份 changelog-generator 指南吗？

可以，前提是仓库已经使用 tags，并且 commit 结构相对清晰。新手可以从 assets/sample_git_log.txt 开始，在本地运行脚本，然后把输出与 references/changelog-formatting-guide.md 对照。通常最难的不是工具本身，而是学会写出包含足够 scope 和 intent 的 commit message。

什么时候不适合使用这个 skill？

当 commits 具有误导性、被大量 squash、或者与实际发布行为脱节时，不应把它作为唯一事实来源。它也不适合直接生成需要定位话术、截图、客户引语或 campaign messaging 的营销发布说明。在这些情况下，可以用这个 skill 整理事实层面的发布清单，然后另写一份公告。

它如何处理 monorepos 和 scoped commits？

monorepo 指南倾向于使用带 scope 的 Conventional Commits，例如 feat(payments): add Stripe webhook handler。这样可以支持 package 级过滤和归属判断。如果你的 scope 与 package 或目录名不匹配，package changelog 可能不完整或噪声较多，因此在依赖自动化之前，应先对齐 commit scopes。

如何改进 changelog-generator skill

先改进 changelog-generator 输入，再生成内容

提升 changelog-generator 结果最快的方法，是先提升 commit stream 的质量。使用清晰的 type、有意义的 scope，以及与用户相关的 subject：

• Good: fix(security): patch SQL injection vulnerability in reports
• Good: feat(admin)!: redesign admin panel with role-based permissions
• Weak: fix stuff
• Weak: updates after review

对于 breaking changes，请在 commit subject 中包含 !；如果 commit body 里没有迁移上下文，则应在 prompt 中补充 migration context。

避免常见失败模式

常见问题包括遗漏 security items、过度报告内部 chores、semver bump 判断错误，以及 changelog bullet 描述的是代码改动而不是产品影响。可以通过要求 agent 做这些事来降低风险：

• 排除纯 chore、style 或 test commits，除非它们会影响用户
• 明确标出 security、deprecated、remove 和 breaking commits
• 区分“recommended version bump”和“release manager decision”
• 为 breaking changes 添加 migration notes

第一版输出后继续迭代

把第一版 changelog 当成结构化草稿。可以继续追问：

• “Which bullets are not user-visible and should be removed?”
• “Which breaking changes need migration notes?”
• “Rewrite the Fixed section for customer-facing clarity.”
• “Return JSON with commit hash, category, scope, and final bullet for audit review.”

这样既能保留可追溯性，也能提高可读性。

按你的发布策略扩展这个 skill

团队可以通过加入组织自己的发布规则来改进这个 skill：允许的 commit types、必填 scopes、severity labels、package ownership 或 changelog templates。如果你通过 CI 发布，请用实际的 GitHub Actions 或 GitLab CI job 扩展 references/ci-integration.md。如果 hotfix 很频繁，请根据你的审批路径、rollback triggers 和 SLA language 自定义 references/hotfix-procedures.md。