Home

Skill

Code Review

changelog

sakuro/dotfiles

Generates changelog entries from commits since the last release. Use when the user wants to update CHANGELOG.md, add changelog entries, or document changes.

...Expand all

Updated time June 29, 2026

# bash # documentation # code-review # git # changelog # release-management # Code ReviewGit & Version ControlDocumentation

About changelog

The changelog skill automates the process of generating changelog entries from git commits since the last release. It is designed to help development teams maintain a consistent and user-focused record of changes in their projects. By analyzing commit messages and distinguishing between user-facing and internal changes, this skill ensures that CHANGELOG.md reflects meaningful updates that are relevant to end users. This reduces manual effort, avoids overlooked changes, and ensures release documentation remains accurate and up to date.

The skill provides a structured workflow for extracting commit information, categorizing changes, and formatting entries in a standardized style. Key features include identifying user-facing changes such as new features, bug fixes, performance improvements, deprecations, and security updates, while excluding purely internal changes like refactoring, tests, or CI/CD modifications. It automatically extracts issue references from commit messages and organizes entries into predefined categories (Added, Changed, Fixed, Removed, Deprecated, Security). Additionally, it determines the appropriate section of the changelog based on the current branch, supporting both versioned releases and an 'Unreleased' section. The skill leverages Bash commands and the Edit tool to read and update the changelog seamlessly.

This skill is ideal for developers, release managers, and teams maintaining open-source or internal software projects who want to streamline changelog maintenance. It is especially useful for projects with frequent commits or multiple contributors, as it ensures all relevant user-facing changes are documented consistently. Users benefit from time savings, reduced errors, and a professional, structured changelog that communicates updates clearly to end users, stakeholders, and contributors.

FAQ

How do I use the changelog skill?

Start by running the skill on your project repository. It will automatically detect commits since the last release, categorize user-facing changes, extract issue references, and update CHANGELOG.md under the appropriate section (Unreleased or versioned release).

Which types of changes are included in the changelog?

The skill includes user-facing changes such as new features, bug fixes, performance improvements, breaking changes, deprecations, and security fixes. Internal changes like refactoring, tests, CI/CD, or code style updates are excluded unless they affect user-facing behavior.

Can it handle repositories without previous release tags?

Yes, if no previous release tag exists, the skill analyzes the most recent commits (up to 50) to generate changelog entries and places them in the 'Unreleased' section.

Does it automatically merge new entries with existing changelog content?

Yes, the skill reads the current CHANGELOG.md, creates the target section if it doesn’t exist, and merges new entries while avoiding duplicates.

Are issue references required in commit messages?

No, issue references are optional. When present, they are included in the entry formatted as '(#123)'. Multiple references are merged as '(#123, #124)'.

View on GitHub

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 tagLAST_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 existsgit log --format="%H %s" "$LAST_TAG"..HEAD# If no tag, get recent commitsgit 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 branchBRANCH=$(git branch --show-current)# Determine target sectionif [[ "$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

If target section doesn't exist, create it
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

Get last release tag
List commits since that tag
For each commit:
- Read commit message
- Determine if user-facing
- Extract issue references
- Categorize (Added/Changed/Fixed/etc.)
Determine target section:
- On release-vX.Y.Z branch → [X.Y.Z]
- Otherwise → [Unreleased]
Read current CHANGELOG.md
Create target section if it doesn't exist
Merge new entries with existing content in target section
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)