Changelog Skill

You are an expert at writing clear, user-facing changelogs. When this skill is invoked, generate a changelog from recent git history.

What This Skill Does

Reads the git commit history and generates a well-organized, human-readable changelog grouped by category.

Step-by-Step Instructions

1. Determine the range. Figure out which commits to include:

   • If the user specifies a range (e.g., v1.2.0..HEAD), use that
   • If the user specifies a tag or version, use commits since that tag
   • If no range is specified, find the most recent tag and use commits since then
   • If there are no tags, use the last 50 commits or ask the user

2. Read the commit history. Run:

   • git log --oneline --no-merges <range> for commit messages
   • git log --stat <range> for a sense of the scope of changes
   • Check for any associated PRs if using GitHub

3. Categorize the changes. Group commits into these categories:

   • New Features - New functionality added (feat: commits)
   • Bug Fixes - Issues resolved (fix: commits)
   • Improvements - Enhancements to existing features (refactor:, perf: commits)
   • Documentation - Documentation changes (docs: commits)
   • Breaking Changes - Changes that require user action

4. Write human-readable descriptions. For each commit:

   • Rewrite the commit message into a user-facing description
   • Remove technical jargon. Users care about what changed for them, not how.
   • Combine related commits into a single entry
   • Skip purely internal changes (CI config, dev dependencies) unless relevant

5. Format the changelog entry:

## [Version] - YYYY-MM-DD

### New Features
- Description of new feature

### Bug Fixes
- Description of bug that was fixed

### Improvements
- Description of improvement

### Breaking Changes
- What changed and what users need to do

6. Add the entry to the changelog file. If a CHANGELOG.md exists, prepend the new entry at the top (below any header). If no changelog exists, ask the user if they want one created.

Guidelines

• Write for end users, not developers. “Fixed login failing on Safari” not “fix: handle webkit cookie SameSite attribute”.
• Do not include every single commit. Combine related changes into single entries.
• Always note breaking changes prominently with migration instructions.
• Use past tense: “Added”, “Fixed”, “Improved”, “Removed”.
• If using conventional commits, leverage the type prefixes for categorization.
• Include credit to contributors if this is an open-source project.
• Keep entries concise. One line per change unless migration instructions are needed.
• Follow the Keep a Changelog format (https://keepachangelog.com) unless the project uses a different convention.