/changelog-generator

name: changelog-generator
description: Generate changelogs from git commits. Use when user says "generate changelog", "update changelog", "what changed since last release", or before preparing a new release.

Changelog Generator Skill

Generate changelogs from conventional commits for Java projects.

When to Use

• Before a release
• User says "generate changelog" / "update changelog" / "what changed since last release"
• After completing a milestone

Versioning Convention Detection

Detect versioning style using this priority order:

1. Check CLAUDE.md (if exists)

grep -A5 "## Versioning" CLAUDE.md 2>/dev/null

Look for explicit convention:

## Versioning
This project uses Semantic Versioning (x.y.z).
Tag format: `release-x.y.z`

2. Fallback: Detect from git tags

git tag --sort=-version:refname | head -10

| Pattern detected | Versioning style | |------------------|------------------| | `v3.15.0`, `3.15.0` | SemVer (x.y.z) | | `release-3.15.0` | SemVer with prefix | | `v2.1`, `2.1` | Two-component (x.y) | | `2026.01`, `26.1` | CalVer | | No pattern | Ask user |

3. Fallback: Detect from CHANGELOG.md

grep -E "^\#+ \[.*\]" CHANGELOG.md | head -5

Extract version format from existing entries.

4. Last resort: Ask user

No versioning convention detected. Which format does this project use?
- Semantic Versioning (x.y.z) - e.g., 3.15.0
- Two-component (x.y) - e.g., 2.1
- Calendar Versioning - e.g., 2026.01

Supported Versioning Styles

| Style | Format | Tag examples | Version bump | |-------|--------|--------------|--------------| | SemVer | x.y.z | `v3.15.0`, `release-3.15.0` | major.minor.patch | | Two-component | x.y | `v2.1`, `2.1` | major.minor | | CalVer | YYYY.MM[.patch] | `2026.01`, `2026.01.1` | year.month[.patch] |

Legacy Projects (CLAUDE.md without versioning section)

If CLAUDE.md exists but has no versioning info: 1. Don't assume - detect from tags/changelog 2. If detected, optionally suggest adding to CLAUDE.md:

   Detected versioning: SemVer (x.y.z) with tag prefix 'release-'
   Want me to add this to CLAUDE.md for future reference?

Output Format

Supports two formats - detect from existing CHANGELOG.md or ask user preference.

Format A: Keep a Changelog (h2 versions)

# Changelog

## [Unreleased]

## [1.2.0] - 2026-01-29

### Added
- [#123]: New feature for plugin dependencies

### Changed
- [#456]: Improved performance of plugin loading

### Fixed
- [#234]: Resolved NPE when directory missing

Format B: pf4j style (h3 versions)

## Change Log

### [Unreleased][unreleased]

### [3.15.0] - 2026-01-29

#### Added
- [#123]: New feature for plugin dependencies

#### Changed
- [#456]: Improved performance of plugin loading

#### Fixed
- [#234]: Resolved NPE when directory missing

Reference-Style Links (Recommended)

Use reference-style links for cleaner, more readable entries:

#### Fixed
- [#648]: Restore missing `module-info.class` in multi-release JAR
- [#625]: Fix exception handling inconsistency in `startPlugin()`

#### Added
- [#629]: Validate dependency state on plugin start
- [#633]: Allow customization of `PluginClassLoader` parent delegation

<!-- At the bottom of the file -->
[#648]: https://github.com/user/repo/issues/648
[#633]: https://github.com/user/repo/pull/633
[#629]: https://github.com/user/repo/pull/629
[#625]: https://github.com/user/repo/pull/625

**Benefits:**

• Cleaner to read (no long URLs inline)
• Links defined once, reusable
• Easier to write and maintain

Version Comparison Links

Add comparison links at the bottom for easy diff viewing:

[unreleased]: https://github.com/user/repo/compare/release-3.15.0...HEAD
[3.15.0]: https://github.com/user/repo/compare/release-3.14.1...release-3.15.0
[3.14.1]: https://github.com/user/repo/compare/release-3.14.0...release-3.14.1

**Pattern:** `[version]: https://github.com/{owner}/{repo}/compare/{previous-tag}...{current-tag}`

Section Order

Adapt to existing file, or use this default order:

| Section | When to use | |---------|-------------| | Fixed | Bug fixes | | Changed | Changes to existing functionality | | Added | New features | | Deprecated | Soon-to-be removed features | | Removed | Removed features | | Security | Vulnerability fixes (CVEs) |

Note: pf4j uses Fixed → Changed → Added → Removed. Keep a Changelog uses Added → Changed → Deprecated → Removed → Fixed → Security.

**Rule: Follow existing file's order if present.**

Mapping Conventional Commits to Changelog

| Commit Type | Changelog Section | |-------------|-------------------| | feat | Added | | fix | Fixed | | perf | Changed | | refactor | Changed | | build(deps) | Changed or Security (if CVE) | | BREAKING CHANGE | Changed (with bold note) | | deprecate | Deprecated |

Workflow

1. **Check for existing CHANGELOG.md**

   cat CHANGELOG.md | head -20

Detect format (h2 vs h3 versions, section order, link style).

2. **Determine version range**

   # Find last tag
   git describe --tags --abbrev=0

   # List recent tags
   git tag --sort=-version:refname | head -5

3. **Get commits since last release**

   git log v3.14.1..HEAD --oneline

4. **Extract issue/PR references** Look for patterns: `#123`, `fixes #123`, `closes #123`, `(#123)`

5. **Generate changelog entry**

• Group by section
• Use reference-style links
• Add version comparison link

6. **Suggest version bump** (based on detected versioning style)

**SemVer (x.y.z):**

• BREAKING CHANGE → Major (3.0.0 → 4.0.0)
• feat → Minor (3.14.0 → 3.15.0)
• fix only → Patch (3.14.0 → 3.14.1)

**Two-component (x.y):**

• BREAKING CHANGE → Major (2.0 → 3.0)
• feat/fix → Minor (2.1 → 2.2)

**CalVer (YYYY.MM):**

• New month → 2026.01 → 2026.02
• Same month, new release → 2026.01 → 2026.01.1

Token Optimizati