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

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

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:
   Copy

   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:

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

Workflow

1. Check for existing CHANGELOG.md

   bashCopy

   cat CHANGELOG.md | head -20
   

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

2. Determine version range

   bashCopy

   # Find last tag
   git describe --tags --abbrev=0
   
   # List recent tags
   git tag --sort=-version:refname | head -5
   

3. Get commits since last release

   bashCopy

   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 Optimization

• Use git log --oneline for initial scan
• Only fetch full body if BREAKING CHANGE suspected
• Reuse existing link definitions from file
• Don't re-read entire changelog - just prepend new section

Example: Full Workflow

Input: User says "generate changelog for next release"

Step 1: Check existing format

head -30 CHANGELOG.md

→ Detects pf4j style (h3 versions, Fixed first)

Step 2: Find version range

git describe --tags --abbrev=0

→ release-3.15.0

Step 3: Get commits

git log release-3.15.0..HEAD --oneline

→ 5 commits found

Step 4: Generate entry

### [Unreleased][unreleased]

#### Fixed
- [#650]: Fix memory leak in extension factory

#### Changed
- [#651]: Rename `LegacyExtension*` to `IndexedExtension*`

#### Added
- [#652]: Add support for plugin priority ordering

Step 5: Generate link definitions

[#652]: https://github.com/pf4j/pf4j/pull/652
[#651]: https://github.com/pf4j/pf4j/pull/651
[#650]: https://github.com/pf4j/pf4j/issues/650

Step 6: Update version comparison links

[unreleased]: https://github.com/pf4j/pf4j/compare/release-3.15.0...HEAD

Step 7: Suggest version

Suggested: 3.16.0 (minor - has new feature)

Handling Edge Cases

No conventional commits

List under "Changed" with original message:

#### Changed
- Updated plugin loading mechanism
- Refactored test utilities

Security fix

#### Security
- [#618], [#623]: Fix path traversal vulnerabilities in ZIP extraction

Breaking change

#### Changed
- **BREAKING**: [#645] Renamed `LegacyExtension*` classes to `IndexedExtension*`

Multiple issues for same fix

- [#630], [#631]: Set `failedException` when plugin validation fails

Integration with Existing CHANGELOG.md

1. Read existing file to detect:

   • Heading level (## or ### for versions)
   • Section order
   • Link style (reference or inline)
   • Existing link definitions

2. Insert new version after [Unreleased] section

3. Merge link definitions - add new ones, keep existing

4. Update [unreleased] comparison link to point to new version

Quick Reference