# Changelog Generator

> Generate a clean, user-facing changelog or release notes from raw git commit history, merged PR titles, or a diff between two versions/tags. Use whenever the user asks to "write release notes", "generate a changelog", "summarize what changed since v1.2", pastes a list of commit messages or PR titles, or is preparing a release and needs commits translated from developer-speak into something users/stakeholders can read. Also trigger when a user shares `git log` output directly.

- Skill: `zeiynz/changelog-generator` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add zeiynz/changelog-generator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zeiynz/changelog-generator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: zeiynz (https://skillmd.com/u/zeiynz)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zeiynz/changelog-generator

---


# Changelog Generator

Translates raw commit history (often terse, inconsistent, developer-facing: "fix bug", "wip", "refactor auth") into a changelog a user or stakeholder would actually want to read — organized by impact, not by commit order.

## Why raw commit history isn't a changelog

Commit logs are chronological and developer-oriented. A changelog is impact-oriented and reader-oriented. The same set of commits should read differently depending on whether the audience is end-users, other engineers, or leadership — this skill's main job is that translation, not just reformatting.

## Workflow

### Step 1: Categorize every commit/PR before writing prose
Sort into standard categories (skip empty ones):
- **Breaking changes** — always first, always most detailed, since these require reader action
- **New features**
- **Improvements** (perf, UX polish, non-breaking behavior changes)
- **Bug fixes**
- **Deprecations** — things that still work but won't in a future version
- **Internal/maintenance** — dependency bumps, refactors, test additions — usually excluded from user-facing notes, kept in a "Chores" section only for a developer-audience changelog

### Step 2: Rewrite each entry for the target audience
- Raw: `fix: null pointer in checkout when cart empty (#412)`
- User-facing: "Fixed an issue where the checkout page could crash if your cart was empty"
- Developer-facing (e.g. library changelog): "Fixed a null reference in `Checkout.render()` when `cart.items` is empty (#412)"

Never invent detail beyond what the commit/PR title and any linked description support — if a commit message is too vague to translate confidently ("fix stuff"), either flag it for the user to clarify or use the vaguest accurate paraphrase ("various stability fixes") rather than fabricating a specific cause.

### Step 3: Follow semantic versioning conventions if the project uses them
If tags follow `MAJOR.MINOR.PATCH`, breaking changes should correspond to a MAJOR bump, new features to MINOR, fixes to PATCH — flag a mismatch (e.g., a breaking change found in what's tagged as a patch release) rather than silently ignoring it, since that's a real risk for downstream consumers.

### Step 4: Format per common convention
Default to [Keep a Changelog](https://keepachangelog.com) format unless the repo already uses a different one (check `CHANGELOG.md` for existing style and match it):

```markdown
## [1.4.0] - 2026-07-23
### Added
- ...
### Changed
- ...
### Fixed
- ...
### Deprecated
- ...
```

### Step 5: Highlight what needs migration action
For breaking changes, add a one-line "what you need to do" note, not just a description of what changed — this is the single highest-value addition a changelog can make over a raw diff.

## Anti-patterns
- Listing every commit 1:1 (squash trivial/related commits into one entry)
- Using the exact commit message verbatim when it's written in developer shorthand a non-engineer reader wouldn't parse
- Omitting breaking changes or burying them at the bottom
- Fabricating a "why" behind a change that the commit history doesn't actually explain

## Reference
- `references/keepachangelog-format.md` — full format spec and category definitions