Changelog Generation Skill

Changelog Generation Skill

Analyzes commits since the last release and adds user-facing changes to CHANGELOG.md.

Instructions

IMPORTANT: When using this skill, announce to the user: "Using changelog skill to generate changelog entries."

1. Get Last Release Tag

# Get the most recent release tag
LAST_TAG=$(git describe --tags --abbrev=0 2>/​dev/​null || echo "")

if [ -z "$LAST_TAG" ]; then
  echo "No previous release tag found. Will analyze all commits."
fi

2. Get Commits Since Last Release

# If tag exists
git log --format="%H %s" "$LAST_TAG"..HEAD

# If no tag, get recent commits
git log --format="%H %s" -50

3. Analyze Each Commit

For each commit, determine if it has user-facing impact:

Include (user-facing):

• New features (:sparkles:)
• Bug fixes (:bug:)
• Performance improvements (:zap:)
• Breaking changes (:boom:)
• Deprecations
• Security fixes (:lock:)

Exclude (internal):

• Refactoring (:recycle:) - unless it changes behavior
• Tests (:white_check_mark:)
• CI/​CD changes (:construction_worker:)
• Documentation (:memo:) - unless user-facing docs
• Code style (:art:)
• Merge commits

4. Extract Issue References

Look for issue references in commit messages:

• #123
• Fixes #123
• Closes #123
• Related to #123

5. Categorize Changes

Group entries by category:

### Added
- New features

### Changed
- Changes to existing functionality

### Fixed
- Bug fixes

### Removed
- Removed features

### Deprecated
- Soon-to-be removed features

### Security
- Security fixes

6. Format Entries

Each entry should:

• Start with imperative verb (Add, Fix, Change, Remove)
• Be concise (one line)
• Include issue reference at end if available

Examples:

- Add list formatting support (#42)
- Fix memory leak in data provider (#88)
- Change default locale to en-US

7. Determine Target Section

# Get current branch
BRANCH=$(git branch --show-current)

# Determine target section
if [[ "$BRANCH" =~ ^release-v([0-9]+\.[0-9]+\.[0-9]+)$ ]]; then
  # On release branch → target is that version
  TARGET_SECTION="[${BASH_REMATCH[1]}]"
else
  # Not on release branch → target is Unreleased
  TARGET_SECTION="[Unreleased]"
fi

8. Update CHANGELOG.md

1. If target section doesn't exist, create it
2. Add/​merge entries under the target section

Creating new section if needed:

• For [Unreleased]: Add after the header, before first version section
• For version [X.Y.Z]: Add after [Unreleased], before previous versions

Example structure:

## [Unreleased]

## [0.7.0] - 2024-01-15

### Added
- New feature description (#123)

## [0.6.0] - 2024-01-01
...

Use the Edit tool to update CHANGELOG.md.

Workflow

1. Get last release tag
2. List commits since that tag
3. For each commit:
   • Read commit message
   • Determine if user-facing
   • Extract issue references
   • Categorize (Added/​Changed/​Fixed/​etc.)
4. Determine target section:
   • On release-vX.Y.Z branch → [X.Y.Z]
   • Otherwise → [Unreleased]
5. Read current CHANGELOG.md
6. Create target section if it doesn't exist
7. Merge new entries with existing content in target section
8. Update CHANGELOG.md using Edit tool

Guidelines

Entry Writing

• Use imperative mood: "Add" not "Added" or "Adds"
• Be specific but concise
• Focus on user impact, not implementation details
• One logical change per entry

Issue References

• Always include if available
• Format: (#123) at end of line
• Multiple issues: (#123, #124)

Avoiding Duplicates

• Check existing [Unreleased] entries before adding
• Merge or update if similar entry exists

Example Output

## [Unreleased]

### Added
- Implement DecimalFormatter for number formatting (#42)
- Add locale fallback support

### Changed
- Update default collation strength to tertiary

### Fixed
- Fix crash when parsing invalid locale string (#55)
- Resolve memory leak in DataProvider (#58)

Arguments

This skill takes no arguments. It always analyzes commits from the last release tag to HEAD.