Skip to main content
skill CX Codex

changelog-generator · decebals — Claude Code skill

changelog-generator builds changelogs from conventional commits and helps prepare a release entry. It is aimed at Java projects with a git history.

MIT 265 installs ★ 778 updated 2026-09-06

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add decebals/claude-code-java --skill changelog-generator -a claude-code
Open on GitHub

What changelog-generator does

The skill reads conventional commits and turns them into changelog sections such as Added, Changed, Fixed, Deprecated, Removed, and Security. It finds the range after the latest tag, extracts issue and pull request references, then suggests a version bump for the next release.

It checks an existing CHANGELOG.md for heading levels, section order, and link style. Versioning is looked up first in CLAUDE.md, then inferred from git tags and older changelog entries. The generated entry can use reference links and a version comparison link.

This skill is built around Java projects, so its commit grouping rules may be too narrow for a different stack.

What it helps with

  • build a changelog from conventional commits
  • list changes since the last release
  • group commits into Added and Fixed sections
  • extract issue and pull request references
  • suggest the next version bump

Example prompts for the agent

  • Generate a changelog for the next release.
  • Show what changed since the last tag and suggest a version bump.
  • Update CHANGELOG.md while keeping its format and section order.

How to install changelog-generator

1Skills CLI (Vercel)

npx skills add decebals/claude-code-java --skill changelog-generator -a claude-code

2Manually: put the files in place

~/.claude/skills/changelog-generator/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/changelog-generator/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about changelog-generator

How do I install changelog-generator in Claude Code?

Run npx skills add decebals/claude-code-java --skill changelog-generator -a claude-code. The skill file will be placed at ~/.claude/skills/changelog-generator/SKILL.md.

What does changelog-generator do?

It parses conventional commits, groups changes into changelog sections, adds issue and pull request references, and suggests the next release version.

How does the skill detect the version format?

It checks the Versioning section in CLAUDE.md first, then examines git tags and existing CHANGELOG.md entries. It supports SemVer, two-component versions, and CalVer.

Source text

SKILL.md · MIT
---
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.
license: MIT
---

# 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)
```bash
grep -A5 "## Versioning" CLAUDE.md 2>/dev/null
```

Look for explicit convention:
```markdown
## Versioning
This project uses Semantic Versioning (x.y.z).
Tag format: `release-x.y.z`
```

### 2. Fallback: Detect from git tags
```bash
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
```bash
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)
```markdown
# 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)
```markdown
## 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:

```markdown
#### 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:

```markdown
[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**
   ```bash
   cat CHANGELOG.md | head -20
   ```
   Detect format (h2 vs h3 versions, section order, link style).

2. **Determine version range**
   ```bash
   # Find last tag
   git describe --tags --abbrev=0

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

3. **Get commits since last release**
   ```bash
   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
```bash
head -30 CHANGELOG.md
```
→ Detects pf4j style (h3 versions, Fixed first)

**Step 2:** Find version range
```bash
git describe --tags --abbrev=0
```
→ `release-3.15.0`

**Step 3:** Get commits
```bash
git log release-3.15.0..HEAD --oneline
```
→ 5 commits found

**Step 4:** Generate entry
```markdown
### [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
```markdown
[#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
```markdown
[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:
```markdown
#### Changed
- Updated plugin loading mechanism
- Refactored test utilities
```

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

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

### Multiple issues for same fix
```markdown
- [#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

| User says | Action |
|-----------|--------|
| "generate changelog" | Full changelog since last tag |
| "changelog since v3.14" | From specific version |
| "what's unreleased" | Preview unreleased changes |
| "update changelog for 3.16" | Generate and insert for version |
| "add changelog entry for #123" | Single issue entry |

© decebals · MIT · decebals/claude-code-java

Similar skills

All skills for Writing and docs →

changelog-generator by other authors comes first.

changelog-generator Alireza Rezvani changelog-generator is a Claude Code skill that builds release notes from Conventional Commits and recommends a SemVer bump. It runs for release prep, commit checks, and hotfix planning. CX Codex +1 618installs changelog-automation Seth Hobson The changelog-automation skill helps generate changelogs and release notes from commits, PRs, and releases. Use it when setting up release workflows or shared commit rules. CX Codex +1 13,733installs changelog-writer patricio0312rev changelog-writer turns git commits, PR titles and issue references into a CHANGELOG and release notes. Useful right before a release, when changes need sorting and a version number. CX Codex +1 631installs devkit.generate-changelog Giuseppe Trisciuoglio devkit.generate-changelog turns your Git history into a Keep a Changelog file, so a release entry is one command instead of a manual rewrite. CX Codex +1 ★ 372repo stars add-changelog davila7 The add-changelog command for Claude Code generates and maintains CHANGELOG.md using Keep a Changelog, reading recent commits and git tags to structure release notes. CX Codex +1 2,025installs generating-changelog joaquimscosta generating-changelog turns a git log into a changelog: commits sorted by type, a version bump suggested, and the file written in Keep a Changelog, Conventional or GitHub style. CX Codex +1 1installs skillshare-changelog runkids skillshare-changelog turns the commits between two tags into a CHANGELOG.md entry and copies it to the project's website changelog page. CX Codex +1 ★ 3,269repo stars

From the same set18

The whole set →
performance-smell-detection performance-smell-detection flags code-level performance smells in Java, covering streams, collections, boxing, and regex compiled inside loops. Helps during code reviews of performance-critical paths. CX Codex +1 361installs test-quality test-quality — a skill that writes high-quality Java unit tests using JUnit 5 and AssertJ. Enable it to add tests to your code or improve test coverage. CX Codex +1 356installs api-contract-review api-contract-review is a Claude Code skill that checks REST API contracts for HTTP semantics, versioning, and compatibility. Run it on a request to review an API or before releasing API changes. CX Codex +1 329installs maven-dependency-audit maven-dependency-audit is a skill that checks Maven dependencies for outdated versions, conflicts and known CVEs. Run it before a release or after a security advisory lands. CX Codex +1 322installs jpa-patterns jpa-patterns teaches coding agents to fix N+1 queries, resolve LazyInitializationException, and manage Spring JPA transactions cleanly. CX Codex +1 313installs logging-patterns The logging-patterns skill shapes Java logging with SLF4J, JSON records, and MDC context. Use it when an agent must trace requests or inspect application logs. CX Codex +1 313installs git-commit git-commit generates Conventional Commits messages for Java codebases based on staged changes inspected with git diff. CX Codex +1 264installs issue-triage Automate GitHub issue triage: sort incoming tasks by type (bugs, features, questions), assign priority labels, and flag duplicates. Use during backlog cleanup, weekly reviews, or after returning from time off. CX Codex +1 254installs

Project sponsors

Companies that keep this analytics open