changelog-generator

changelog-generator skill 概覽

changelog-generator 的用途

changelog-generator 是一項面向工程發布管理的 skill，可將 Conventional Commit 歷史轉換成一致、可稽核的 release notes。它能協助 AI agent 解析 commit subject、推斷 semantic version bump、產生 Keep a Changelog 風格的段落，並把結果銜接到 CI 或 hotfix 工作流程，而不是只靠一般 prompt 產出鬆散的文字。

最適合的使用者與發布情境

這項 changelog-generator skill 最適合需要根據真實 git 歷史，反覆產出可靠 CHANGELOG.md 條目的維護者、release engineers、DevOps 團隊與 technical writers。它適用於 release cut、PR commit 檢查、semantic version 規劃、monorepo package 發布，以及重視可追溯性的緊急 hotfix notes。

當 technical writers 需要把開發者的 commit messages 轉成面向使用者的 release notes，同時保留依據時，這個 changelog-generator 特別有用：例如 commit range、version、breaking changes、security fixes 與 migration notes。

它和一般 prompt 有什麼不同

一般的「write release notes」prompt 容易失去結構，或自行推測影響範圍。這項 skill 則包含專門的 scripts 與參考文件：scripts/generate_changelog.py、scripts/commit_linter.py、scripts/version_bumper.py，並提供 changelog 格式、CI 整合、monorepos 與 hotfix 程序的指引。因此，它更適合自動化或半自動化的發布工作流程。

採用前應先確認的限制

這項 skill 假設 commits 大致符合 Conventional Commits，例如 feat(auth): add OAuth2 integration 或 fix(api): resolve race condition。如果你的 repository 常使用 updates、misc fixes 這類模糊訊息，或 squash commits 沒有有用的 subject，除非你提供額外脈絡，否則輸出品質會下降。採用非 semver release policy 的團隊，應將 version-bump 輸出視為建議，而不是最終決策。

如何使用 changelog-generator skill

changelog-generator 安裝與 repository 設定

若使用 Claude 風格的本機 skills，請將 skill folder 複製到你的 skill directory。repository README 提供了以下範例：

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

請依照實際 cloned repository 位置調整來源路徑。在正式環境依賴這項 skill 前，也建議先檢閱以下檔案：

• SKILL.md：agent-facing workflow
• README.md：quick-start commands
• references/changelog-formatting-guide.md：output rules
• references/ci-integration.md：CI examples
• references/monorepo-strategy.md：若你會獨立發布各 package，請閱讀此檔
• references/hotfix-procedures.md：urgent release classification

可靠輸出所需的輸入

若要讓 changelog-generator 發揮良好效果，請提供明確的 release boundary 與足夠的 policy context。實用輸入包括：

• previous tag 與 target tag，例如 v1.2.0..v1.3.0
• target version，或讓 skill 計算 bump 時所需的 current version
• 若 agent 無法存取 git，請提供來自 git log --oneline 的 raw commit subjects
• breaking changes 是否需要 migration notes
• monorepos 的 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。」

實用 command 模式

內建工具可直接使用，也可在發布流程中由 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 subjects：

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

當 CI 需要 machine-readable results 時，使用 JSON 輸出；當需要人工審閱或 prepend 到 CHANGELOG.md 時，使用 markdown。

產出更好 release notes 的工作流程

先 lint commits，再推斷 version bump，接著產生 changelog entry，最後編輯成使用者能理解的影響說明。最重要的編輯步驟，是將偏向實作細節的訊息改寫成使用者可感知的變更，同時不隱藏重要技術風險。

例如，fix(db): resolve deadlock issues in concurrent transactions 應改寫成面向使用者的說明，例如「Fixed database deadlocks that could interrupt concurrent account updates」，而不是「Changed transaction locking logic」。

changelog-generator skill 常見問題

changelog-generator 只適合全自動發布嗎？

不是。這項 skill 同時適合自動化與編輯導向的工作流程。CI 可以強制 commit format 或產生 draft notes；人工則可修飾措辭、補上 migration details，並核准最終的 release entry。

初學者可以使用這份 changelog-generator 指南嗎？

可以，前提是 repository 已經使用 tags，且 commits 有基本結構。初學者可先從 assets/sample_git_log.txt 開始，在本機執行 scripts，並將輸出與 references/changelog-formatting-guide.md 比對。最困難的通常不是工具本身，而是學會寫出包含足夠 scope 與 intent 的 commit messages。

什麼時候不該使用這項 skill？

當 commits 具誤導性、過度 squash，或與實際 shipped behavior 脫節時，不應把它作為主要事實來源。它也不適合直接用來撰寫需要 positioning、screenshots、customer quotes 或 campaign messaging 的 marketing launch notes。這些情況下，可先用這項 skill 整理事實性的 release inventory，再另行撰寫 announcement。

它如何處理 monorepos 與 scoped commits？

monorepo 指引偏好 scoped Conventional Commits，例如 feat(payments): add Stripe webhook handler。這能支援 package-level filtering 與 ownership。若你的 scopes 和 package 或 directory names 不一致，package changelogs 可能不完整或混入雜訊，因此在依賴自動化前，應先對齊 commit scopes。

如何改進 changelog-generator skill

先改善 changelog-generator 輸入再產生內容

改善 changelog-generator 結果最快的方法，是先改善 commit stream。請使用清楚的 types、有意義的 scopes，以及與使用者相關的 subjects：

• 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 沒有 migration context，請在 prompt 中補充。

避免常見失敗模式

常見問題包括遺漏 security items、過度報告內部 chores、semver bump 判斷錯誤，以及 changelog bullets 描述的是程式碼變更而非產品影響。可以請 agent 執行以下做法來降低風險：

• 排除純粹的 chore、style 或 test commits，除非它們會影響使用者
• 明確標出 security、deprecated、remove 與 breaking commits
• 將「recommended version bump」和「release manager decision」分開
• 為 breaking changes 加上 migration notes

在第一版輸出後反覆修訂

請把第一版 changelog 視為結構化 draft。可以接著追問：

• 「哪些 bullets 不是 user-visible，應該移除？」
• 「哪些 breaking changes 需要 migration notes？」
• 「Rewrite the Fixed section for customer-facing clarity。」
• 「Return JSON with commit hash, category, scope, and final bullet for audit review。」

這樣能在改善可讀性的同時保留可追溯性。

依照你的 release policy 擴充 skill

團隊可透過加入組織專屬的 release rules 來改進這項 skill：例如 allowed commit types、required scopes、severity labels、package ownership，或 changelog templates。若你透過 CI 發布，請將實際使用的 GitHub Actions 或 GitLab CI job 補入 references/ci-integration.md。若 hotfix 很頻繁，請依照你的 approval path、rollback triggers 與 SLA language 自訂 references/hotfix-procedures.md。