From grimoire
Automates changelog generation and semantic version bumping from Conventional Commit history. Use when a project enforces Conventional Commits and wants automated releases without manual writing.
How this skill is triggered — by the user, by Claude, or both
Slash command
/grimoire:run-changelog-automationThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Automate changelog generation and version bumping from Conventional Commit history so release preparation requires zero manual writing.
Automate changelog generation and version bumping from Conventional Commit history so release preparation requires zero manual writing.
Adopted by: Angular, Vue, Electron, AWS CDK, and Nx use automated changelog generation as part of their release pipelines; semantic-release is used by 500k+ GitHub repositories and downloaded over 2 million times per week on npm; release-please is Google's internal release automation tool, open-sourced and used across Google's OSS portfolio including googleapis and gRPC
Impact: Angular adopted semantic-release for their monorepo and reduced release preparation time from several hours of manual work to a fully automated CI step; automated generation eliminates the two most common release errors — forgotten changelog entries and version/git tag mismatches — because all three are derived from the same commit history atomically
Why best: Manual changelog writing depends on a developer remembering every commit since the last release; this fails under time pressure, produces inconsistent entry quality, and decouples the changelog from the version bump (a common source of mismatch); raw commit log surfacing (git log) is the alternative but produces developer-facing messages unfit for users; automated tools parse Conventional Commits, filter to user-relevant types, and produce structured markdown — deterministically, on every release
Sources: Angular blog "So You Think You Know Semantic Versioning" (2022); semantic-release documentation (semantic-release.gitbook.io); release-please GitHub repository (github.com/googleapis/release-please); changelogen documentation (github.com/unjs/changelogen)
Automated tools parse commit types (feat:, fix:, docs:) to determine version bump and entry inclusion. Non-conforming commits produce no changelog entry — silent omissions.
Enforce before setting up automation:
# Install commitlint + husky
npm install --save-dev @commitlint/cli @commitlint/config-conventional husky
# Init husky
npx husky init
# Add commit-msg hook
echo 'npx --no -- commitlint --edit $1' > .husky/commit-msg
chmod +x .husky/commit-msg
# Create commitlint config
echo "export default { extends: ['@commitlint/config-conventional'] };" > commitlint.config.mjs
Or enforce in CI instead of locally (lower friction for contributors):
# GitHub Actions: .github/workflows/commitlint.yml
- uses: wagoid/commitlint-github-action@v6
| Tool | Best for | Automation level | Non-npm support |
|---|---|---|---|
| semantic-release | Full CI automation, npm publish | Fully automatic — no human trigger | Via plugins |
| release-please | Teams wanting PR review before release | Semi-automatic — creates a Release PR | Yes (Go, Java, Python, etc.) |
| changelogen | Changelog-only (no publish step) | Manual trigger, markdown output | Yes |
Use semantic-release when: CI should release automatically on every merge to main, project publishes to npm, team trusts the commit discipline.
Use release-please when: team wants to review and approve the next release before it ships (Release PR accumulates changes, human merges to trigger release).
Use changelogen when: project is not an npm package, or you only want changelog generation without automated publish.
npm install --save-dev semantic-release @semantic-release/changelog @semantic-release/git
.releaserc (project root):
{
"branches": ["main"],
"plugins": [
"@semantic-release/commit-analyzer",
"@semantic-release/release-notes-generator",
["@semantic-release/changelog", {
"changelogFile": "CHANGELOG.md"
}],
"@semantic-release/npm",
["@semantic-release/git", {
"assets": ["CHANGELOG.md", "package.json"],
"message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
}],
"@semantic-release/github"
]
}
Default version bump rules (from @semantic-release/commit-analyzer):
| Commit type | Version bump |
|---|---|
fix: | patch |
feat: | minor |
feat!: or BREAKING CHANGE: footer | major |
chore:, docs:, style:, refactor:, test: | none |
npm install --save-dev release-please
release-please-config.json (project root):
{
"packages": {
".": {
"release-type": "node",
"changelog-path": "CHANGELOG.md"
}
}
}
.release-please-manifest.json:
{
".": "1.0.0"
}
GitHub Action (.github/workflows/release-please.yml):
on:
push:
branches: [main]
jobs:
release-please:
runs-on: ubuntu-latest
steps:
- uses: googleapis/release-please-action@v4
with:
token: ${{ secrets.GITHUB_TOKEN }}
This creates a "Release PR" that accumulates feat: and fix: commits into a changelog draft. When the PR is merged, release-please creates the GitHub release and tag.
npm install --save-dev changelogen
Add to package.json:
{
"scripts": {
"changelog": "changelogen --release"
}
}
Run before tagging:
npm run changelog # updates CHANGELOG.md
git add CHANGELOG.md
git commit -m "chore: update changelog for v1.2.0"
git tag v1.2.0
# .github/workflows/release.yml
name: Release
on:
push:
branches: [main]
jobs:
release:
runs-on: ubuntu-latest
permissions:
contents: write
issues: write
pull-requests: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # semantic-release needs full history
persist-credentials: false
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- run: npx semantic-release
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
fetch-depth: 0 is required — semantic-release reads all tags to determine the last release.
Before enabling on main, verify the generated output:
# semantic-release dry run (no tags, no publish, no changelog write)
npx semantic-release --dry-run
# changelogen preview
npx changelogen --from v1.0.0 --to HEAD
Check that:
feat!: prefix or include BREAKING CHANGE: <description> in the commit footer — tools detect these token patterns to trigger major bumps[skip ci] in the release commit message is required when using semantic-release with @semantic-release/git — prevents infinite CI loops when the release commit pushes to mainNPM_TOKEN secret must have publish permissions to the package's npm scope; automation fails silently on auth errors without thisfetch-depth: 0 — actions/checkout defaults to a shallow clone (depth 1); semantic-release cannot find prior tags and either fails or bumps to 1.0.0 on every run.main (or master) in .releaserc branches field.! or BREAKING CHANGE: footer gets detected as a patch bump; downstream users get a breaking change in a patch release.propose-conventional-commit first.write-changelog (manual) is more reliable in this case.npx claudepluginhub jeffreytse/grimoire --plugin grimoireAutomates changelog generation from Git commits, PRs, and releases in Keep a Changelog format using Conventional Commits and Semantic Versioning for release workflows.
Generates and manages changelogs/release notes from git history and Conventional Commits. Supports Keep a Changelog format, breaking change docs, migration guides, audience-specific notes.
Automates changelog generation from commits, PRs, and releases following Keep a Changelog format. Use when setting up release workflows, generating release notes, or standardizing commit conventions.