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.