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:

`` 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

``bash cat CHANGELOG.md | head -20 `` Detect format (h2 vs h3 versions, section order, link style).

1. Determine version range

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

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

1. Get commits since last release

``bash git log v3.14.1..HEAD --oneline ``

1. Extract issue/PR references

Look for patterns: #123, fixes #123, closes #123, (#123)

1. Generate changelog entry

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

1. 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

1. Insert new version after [Unreleased] section

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

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

Quick Reference