Changelog

Changelog

Draft or update a CHANGELOG.md following Keep a Changelog conventions.

Invocation Notice

Inform the user when this skill is being invoked by name: changelog.

When to Use

• Writing or updating CHANGELOG.md for an upcoming or recent release
• Drafting or appending to an [Unreleased] section from recent merged work
• Generating a changelog from git history, a commit range, or a diff
• Editing or cleaning up an auto-generated changelog draft

When Not to Use

• Writing a git commit message — use commit-message skill
• Writing internal release notes or deployment runbooks (audience is operators, not users)
• Full code review — use code-review skill

Workflow

1. Determine scope

Infer target version, release date, and commit range from context. Ask only if neither the version nor the range can be determined.

• Default range: git log <previous-tag>..HEAD --oneline --no-merges
• If no prior tag exists: git log --oneline --no-merges
• If updating [Unreleased] only: use commits since last tagged release

Check for an existing [Unreleased] section in CHANGELOG.md — do not duplicate entries already there.

2. Collect commits

git log <range> --oneline --no-merges

Also read the existing CHANGELOG.md to understand document structure and last version.

3. Filter noise

Exclude commits with no user-visible effect. Retain only what matters to users. See references/entry-guidelines.md for the full include/exclude list.

Quick exclusion rule: if a user reading the changelog would not care, cut it.

4. Categorize

Map surviving entries to Keep a Changelog categories (in display order):

Category	When to use
Breaking Changes	Any change requiring user action — config, API, CLI, behavior
Added	New features, commands, endpoints, options
Changed	Modified behavior, performance improvements, visible refactors
Deprecated	Things that still work but will be removed
Removed	Deleted features, commands, options
Fixed	Bug fixes
Security	Vulnerability patches

Breaking changes get their own subsection at the top of the version block. See references/entry-guidelines.md for the Conventional Commits → category mapping.

5. Write entries

• One entry per logical user-visible outcome — consolidate multi-commit features into one line
• Imperative present tense: Add X, Fix Y, Remove Z
• For breaking changes: state what broke AND the migration path (e.g., Remove X — replace with Y; see docs/migration.md)
• One reference link per entry; prefer PR over commit hash over issue number
• Do not include implementation details, commit hashes in entry text, or "WIP" notes

6. Insert into CHANGELOG.md

See references/changelog-format.md for the exact block structure and version comparison link format.

New release (no [Unreleased] section): insert ## [x.y.z] - YYYY-MM-DD block at the top of the file.

New release (existing [Unreleased] section):

• If [Unreleased] IS the release being cut: replace ## [Unreleased] with ## [x.y.z] - YYYY-MM-DD; add a fresh empty ## [Unreleased] above it.
• If [Unreleased] contains unrelated upcoming work: insert the new versioned block between [Unreleased] and the previous version.

Updating [Unreleased] only: append entries under the matching category subsection; create the subsection if absent.

Add or update the version comparison link at the bottom of the file.

7. Verify before delivering

• Version bump is semantically correct: breaking → major, new feature → minor, fix → patch
• No CI/CD, formatting, test-only, or dev-tooling entries present
• Breaking changes include a migration path
• Date is ISO 8601 (YYYY-MM-DD)
• No duplicate entries from the existing [Unreleased] section

Output

An updated CHANGELOG.md with the new version block inserted (or [Unreleased] section updated), ready for user review before commit.

References

• references/entry-guidelines.md — include/exclude heuristics and Conventional Commits mapping
• references/changelog-format.md — full Keep a Changelog format rules and examples