changelog

Changelog Skill

Generate CHANGELOG.md entries from git history using Keep a Changelog format.

Capabilities

• Read existing CHANGELOG.md and detect where to insert new entries
• Analyze git history since last recorded commit
• Filter out noise commits (changelog-only, config-only changes)
• Review actual diffs to write accurate, user-facing descriptions
• Group changes into standard sections: Added, Changed, Fixed, Removed

Usage

This skill activates when:

• User asks to "update the changelog"
• User asks to "generate changelog entries"
• User wants to "add recent changes to CHANGELOG.md"
• User mentions "changelog" in context of git history

Approach

Step 1: Read Current State

Read CHANGELOG.md in the project root. Extract the last recorded commit hash from the first ## ... \hash`` header line.

• If CHANGELOG.md does not exist, create one with a title and description header
• If no hash is found in any header, fall back to the repository's initial commit

Step 2: Get New Commits

Run:

git log <LAST_HASH>..HEAD --format="%h %s" --reverse

If there are no new commits, inform the user and stop.

Step 3: Filter Noise Commits

Skip commits that ONLY touch:

• CHANGELOG.md
• CLAUDE.md or .claude/ files
• .gitignore
• Dev config files (editor settings, linter configs) with no functional code changes

Step 4: Review Diffs

For each remaining commit, review the actual diff:

git diff <HASH>^..<HASH>

Diffs are the source of truth — do not rely solely on commit messages.

Step 5: Group and Write Entries

Group changes into sections (omit empty ones):

• Added — New features or capabilities
• Changed — Modifications to existing functionality
• Fixed — Bug fixes
• Removed — Removed features or capabilities

Merge related commits into single bullets. Write concise, user-facing descriptions. Reference the git hash each entry covers through.

Step 6: Format Header

Use the author date of HEAD:

git log -1 HEAD --format="%h %ai"

Header format:

## YYYY-MM-DD HH:mm:ss `SHORT_HASH`

Step 7: Insert Entry

Insert the new entry after the CHANGELOG.md header block (title + description paragraph), before the first existing ## entry.

Step 8: Report

Tell the user what was added. Do NOT commit the changes — leave that to the user.

Output Format

The generated CHANGELOG.md entry follows this structure:

## 2026-03-16 14:30:00 `abc1234`

### Added
- New feature description (`def5678`)

### Changed
- Modified behavior description (`abc1234`)

### Fixed
- Bug fix description (`789abcd`)

Notes

• Each entry references the git hash it covers through
• Description paragraph in CHANGELOG.md: "Maintained with the help of AI tooling. Each entry references the git hash it covers through."
• Keep bullets concise and user-facing — avoid implementation details
• When multiple commits relate to the same feature, merge them into one bullet