peterfei/ai-agent-team / .claude/skills/changelog-generator
changelog-generator
Verified智能变更日志生成器 - 自动分析Git提交历史,生成符合规范的CHANGELOG.md。支持语义化版本管理、多种输出格式、增量更新和GitHub/GitLab集成。
changelog-generator - 智能变更日志生成器
概述
当用户需要生成或更新 CHANGELOG 时,此 skill 会自动完成以下流程:
- 分析 Git 提交历史
- 根据 Conventional Commits 规范解析提交
- 智能分类和组织变更
- 生成符合 Keep a Changelog 标准的 CHANGELOG.md
- 支持版本发布和增量更新
支持的触发指令
用户可以通过以下方式触发此 skill:
- "changelog" - 简易触发词
- "变更日志" - 简易触发词
- "帮我生成 CHANGELOG" - 生成完整的 CHANGELOG
- "更新 CHANGELOG" - 增量更新 CHANGELOG
- "发布新版本" - 发布正式版本
- "初始化 changelog 配置" - 创建配置文件
工作流程
步骤 1: 初始化配置(首次使用)
命令:
cd ~/.claude/skills/changelog-generator
npm install
# 在项目目录中初始化配置
cd /path/to/your/project
changelog-generate init
配置文件: .changelogrc.json
交互式配置会询问:
- 当前版本号
- 语言选择(中文/英文)
- 是否使用 emoji
- 是否显示作者信息
步骤 2: 生成 CHANGELOG
场景 A: 首次生成完整 CHANGELOG
# 生成所有历史提交的 CHANGELOG
changelog-generate generate --all
# 生成指定范围的 CHANGELOG
changelog-generate generate --from v1.0.0 --to v2.0.0
场景 B: 增量更新 CHANGELOG
# 更新 [Unreleased] 区域
changelog-generate update
# 从指定标签开始更新
changelog-generate update --from v2.0.0
场景 C: 发布新版本
# 自动确定版本号(交互式)
changelog-generate release
# 手动指定版本号
changelog-generate release --version 2.1.0
# 指定日期
changelog-generate release --version 2.1.0 --date 2023-11-10
步骤 3: 输出文件
默认输出路径: ./CHANGELOG.md
生成的 CHANGELOG 示例:
# Changelog
All notable changes to this project will be documented in this file.
## [Unreleased]
## [2.0.0] - 2023-11-10
### 💥 BREAKING CHANGES
- **api:** Remove deprecated v1 endpoints (#123)
### ✨ Features
- **auth:** Add JWT authentication (#120)
- **api:** Add user profile endpoint (#121)
### 🐛 Bug Fixes
- **ui:** Fix button alignment issue (#122)
### 📝 Documentation
- Update API documentation
## [1.0.0] - 2023-10-01
...
核心功能
1. 智能提交解析
支持 Conventional Commits 规范:
feat(auth): add login functionality
^ ^ ^
type scope subject
BREAKING CHANGE: Remove old auth API
支持的提交类型:
feat: ✨ Featuresfix: 🐛 Bug Fixesdocs: 📝 Documentationstyle: 💄 Styles (可隐藏)refactor: ♻️ Code Refactoringperf: ⚡ Performancetest: ✅ Testsbuild: 📦 Build Systemci: 👷 CI/CDchore: 🔧 Chores (可隐藏)
2. 自动版本管理
根据提交类型自动确定版本号:
| 提交类型 | 版本影响 | 示例 |
|---|---|---|
| BREAKING CHANGE | Major | 1.0.0 → 2.0.0 |
| feat | Minor | 1.0.0 → 1.1.0 |
| fix | Patch | 1.0.0 → 1.0.1 |
3. PR 和 Issue 引用
自动识别和链接:
feat: add new feature (#123)
fix: resolve bug (fixes #456)
生成链接:
- **feat:** add new feature ([#123](https://github.com/user/repo/pull/123))
4. 破坏性变更检测
两种检测方式:
方式 1: 使用 BREAKING CHANGE footer
feat: add new API
BREAKING CHANGE: Old API is removed
方式 2: 使用 "!" (感叹号) 标记
feat!: remove deprecated method
配置选项
完整配置示例
{
"version": "1.0.0",
"format": "keepachangelog",
"language": "zh-CN",
"display": {
"emoji": true,
"groupByType": true,
"showAuthor": true,
"showPR": true,
"showIssue": true
},
"types": [
{ "type": "feat", "section": "Features", "emoji": "✨" },
{ "type": "fix", "section": "Bug Fixes", "emoji": "🐛" },
{ "type": "chore", "hidden": true }
],
"exclude": {
"types": ["style", "chore"],
"scopes": ["deps"]
}
}
使用场景
场景 1: 新项目首次生成
# 1. 初始化配置
changelog-generate init
# 2. 生成 CHANGELOG
changelog-generate generate --all
# 输出: CHANGELOG.md 包含所有历史提交
场景 2: 日常开发增量更新
# 在每次 PR 合并后或定期更新
git pull
changelog-generate update
# 查看 [Unreleased] 的内容
changelog-generate preview
场景 3: 发布新版本
# 1. 更新 CHANGELOG
changelog-generate update
# 2. 预览将要发布的内容
changelog-generate preview
# 3. 发布版本
changelog-generate release
# 4. 提交和推送
git add CHANGELOG.md
git commit -m "chore(release): 2.0.0"
git tag v2.0.0
git push && git push --tags
场景 4: CI/CD 自动化
GitHub Actions:
name: Update Changelog
on:
push:
branches: [main]
jobs:
changelog:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
with:
fetch-depth: 0
- name: Update Changelog
run: |
npm install -g changelog-generate
changelog-generate update
- name: Commit
run: |
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
git add CHANGELOG.md
git commit -m "docs: update changelog" || true
git push
CLI 命令参考
init - 初始化配置
changelog-generate init
交互式创建 .changelogrc.json 配置文件。
generate - 生成 CHANGELOG
changelog-generate generate [options]
Options:
-f, --from <tag> 起始标签
-t, --to <tag> 结束标签 (默认: HEAD)
-o, --output <file> 输出文件 (默认: CHANGELOG.md)
--all 包含所有历史提交
update - 增量更新
changelog-generate update [options]
Options:
-f, --from <tag> 起始标签(默认为最新标签)
-o, --output <file> CHANGELOG 文件 (默认: CHANGELOG.md)
release - 发布版本
changelog-generate release [options]
Options:
-v, --version <version> 版本号
-d, --date <date> 发布日期
-o, --output <file> CHANGELOG 文件
preview - 预览 Unreleased
changelog-generate preview
显示 [Unreleased] 区域的内容。
最佳实践
1. 规范的 Commit Message
使用 Conventional Commits 规范:
# 好的示例
git commit -m "feat(auth): add OAuth2 support"
git commit -m "fix(ui): resolve button alignment issue"
git commit -m "docs: update installation guide"
# 避免的示例
git commit -m "update code"
git commit -m "fix bug"
git commit -m "wip"
2. 使用 Commitlint
安装 commitlint 检查提交消息:
npm install --save-dev @commitlint/cli @commitlint/config-conventional
配置 .commitlintrc.json:
{
"extends": ["@commitlint/config-conventional"]
}
3. Git Hooks 自动化
使用 husky 在提交时检查:
npm install --save-dev husky
# .husky/commit-msg
npx commitlint --edit $1
4. 定期更新
建议在以下时机更新 CHANGELOG:
- 每次 PR 合并后
- 每周定期更新
- 发布前必须更新
5. 版本发布流程
# 1. 确保所有变更已提交
git status
# 2. 更新 CHANGELOG
changelog-generate update
# 3. 预览内容
changelog-generate preview
# 4. 发布版本
changelog-generate release
# 5. 审查 CHANGELOG.md
git diff CHANGELOG.md
# 6. 提交和标签
git add CHANGELOG.md
git commit -m "chore(release): 2.0.0"
git tag v2.0.0
# 7. 推送
git push && git push --tags
依赖安装
# 使用 nvm 管理 Node.js 版本
nvm use 18
# 安装依赖
cd ~/.claude/skills/changelog-generator
npm install
技术栈
- simple-git: Git 操作
- conventional-commits-parser: 提交解析
- semver: 版本管理
- handlebars: 模板引擎
- commander: CLI 框架
- inquirer: 交互式命令行
- chalk: 终端颜色
- ora: 加载动画
故障排除
问题 1: 找不到 Git 仓库
错误: Not a git repository
解决:
# 确保在 Git 仓库目录中
git status
# 或初始化 Git 仓库
git init
问题 2: 无法解析提交
原因: 提交消息不符合 Conventional Commits 规范
解决: 修改配置,将不符合规范的提交归类到 "Other" 类型。
问题 3: 生成的 CHANGELOG 为空
检查:
# 查看提交历史
git log --oneline
# 检查配置中的排除规则
cat .changelogrc.json | grep exclude
扩展和自定义
自定义模板
创建自定义模板 custom-template.hbs:
# 变更日志
{{#each versions}}
## 版本 {{version}} ({{date}})
{{#each changes}}
**{{section}}**
{{#each commits}}
- {{subject}}
{{/each}}
{{/each}}
{{/each}}
配置使用:
{
"template": {
"path": "./custom-template.hbs"
}
}
添加新的提交类型
在 .changelogrc.json 中添加:
{
"types": [
{
"type": "security",
"section": "Security",
"emoji": "🔒",
"priority": 2
}
]
}
与其他工具集成
与 semantic-release 集成
{
"plugins": [
"@semantic-release/commit-analyzer",
"@semantic-release/changelog",
"@semantic-release/npm",
"@semantic-release/git"
]
}
与 Renovate 集成
.renovate.json:
{
"automerge": true,
"prCreation": "immediate",
"commitMessagePrefix": "chore(deps):"
}
版本: 1.0.0 作者: Peter Fei 许可: MIT
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 197k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |