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

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.