/changelog-generator

name: changelog-generator
description: Use when preparing release notes or a changelog entry from commits, PRs, or diffs, summarizing a sprint or version range, or scanning a range for breaking changes before publishing.

Changelog Generator

When to Use

• Preparing release notes for a GitHub Release or CHANGELOG.md entry
• Summarizing changes across a sprint, milestone, or version range
• Checking whether any commits contain breaking changes before publishing
• Producing a technical diff summary for internal reviewers

Inputs

• Compare range: `<from-tag>..HEAD`, `main..HEAD`, or a PR list with merge dates
• Target audience and output mode (see below)
• Existing CHANGELOG.md (if present, match its format)

Workflow

1. Collect raw material

git log <from>..<to> --oneline --no-merges
git log <from>..<to> --format="%h %s (%an)" --no-merges

Or from GitHub PRs:

gh pr list --state merged --base main --json number,title,labels,author

Check CHANGELOG.md for format precedent before writing.

2. Classify commits

| Commit signal | User-facing label | |---|---| | `feat` / new capability | Added | | `fix` / bug fix | Fixed | | `perf` / performance | Improved | | `deprecate` | Deprecated | | `BREAKING CHANGE:` footer or `!` suffix | **Breaking** | | `chore`, `refactor`, `ci`, `build` | (internal — omit from user notes) | | `docs` | Include only if docs are a shipped artifact |

When Conventional Commits are not used, infer from the commit subject.

3. Scan for breaking changes

Flag any commit or PR that:

• Contains `BREAKING CHANGE:` in the message body
• Has a `!` suffix on the type (e.g., `feat!: rename --output-dir`)
• Removes or renames a public export, CLI flag, API endpoint, or config key
• Changes a default value or behavior

4. Write the output

**User-facing release notes** (GitHub Release body):

## What's Changed

### Added
- Description of new capability ([#123](link))

### Fixed
- Description of bug fix ([#124](link))

### Breaking Changes
- `--old-flag` has been renamed to `--new-flag` — update your scripts

### Deprecated
- `legacyMethod()` is deprecated; use `newMethod()` instead

**Internal changelog entry** (CHANGELOG.md format):

## [X.Y.Z] - YYYY-MM-DD

### Added
### Fixed
### Changed
### Breaking
### Deprecated
### Chores

**Breaking-change scan only:**

BREAKING CHANGES FOUND:
  abc1234 feat!: rename --output-dir to --out
  def5678 fix: remove deprecated --legacy flag

NONE if clean.

**Technical diff summary** (for internal reviewers):

CHANGED FILES: N
MODULES AFFECTED: [list]
SUMMARY: [what changed at the file/module level, no prose]

Output

Deliver the formatted block plus:

• Compare range used
• Total commit count in range
• Any commits skipped (merge commits, reverts, etc.)

Verification

• Every user-visible commit in the range is covered
• Breaking changes are explicitly labeled in user-facing output
• No internal chore commits appear in user-facing release notes

Failure Modes

• Empty compare range — run `git log <from>..<to>` to confirm the range resolves correctly
• Conventional Commits not used — fall back to inferred classification from the subject line
• Squash-merge strategy with uninformative subjects — use PR titles and labels instead

Sources / Inspiration

Inspired by `ComposioHQ/awesome-codex-skills` `changelog-generator/SKILL.md`. Rewritten in Agent Powerups style.