# Changelog Forge

> Generate CHANGELOG.md entries from git history using a deterministic script, then rewrite them into human release notes. Use when preparing a release, writing release notes, updating a changelog, or when the user mentions changelog, release notes, or "what's in the next version".

- Skill: `paladini/changelog-forge` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add paladini/changelog-forge`
- Raw SKILL.md: https://api.skillmd.com/api/skills/paladini/changelog-forge/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: paladini (https://skillmd.com/u/paladini)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/paladini/changelog-forge

---


# Changelog Forge

Generate a Keep a Changelog entry from git history. The script guarantees
completeness (every commit since the last tag is categorized); you guarantee
readability (human prose, not commit spam).

## Workflow

1. Generate the mechanical draft and show it:
   `python scripts/generate_changelog.py --stdout`
   It defaults to commits since the last `v*.*.*` tag. Use
   `--since <ref>` to override, and `--version vX.Y.Z` when the user named
   the version. The script prints the rendered markdown block to stdout;
   status messages go to stderr.
2. Rewrite every bullet for humans:
   - Merge duplicate/near-duplicate entries into one.
   - Drop noise: `chore`, release bumps, CI-only churn — unless the user
     asked to include them.
   - Describe user-facing impact, not mechanics ("fix: typo in header" →
     omit or fold into a related entry).
   - Keep `Breaking` entries first and explicit about migration.
3. Render the final entry into the exact structure of
   [assets/changelog_template.md](assets/changelog_template.md) — same
   section order, same headings. Omit empty sections.
4. Verify no placeholder survived: `grep -n "{{" CHANGELOG.md` must return
   nothing.
5. Write (or prepend) the entry with the script's `--write` mode, or by
   editing CHANGELOG.md directly if the user prefers:
   `python scripts/generate_changelog.py --version v1.4.0 --write CHANGELOG.md`
6. Show the final entry to the user. Never push, tag, or bump versions
   unless explicitly asked.

## Script reference

- `--since <ref>` — commits after `<ref>` (default: last semver tag).
- `--version <v>` — version header (default: `Unreleased`).
- `--date YYYY-MM-DD` — entry date (default: HEAD commit date, so drafts
  are reproducible).
- `--write <file>` — prepend the entry to an existing changelog, creating
  one with the Keep a Changelog preamble if missing. Requires an explicit
  `--version`. Refuses duplicate versions (exit 4).
- Exit codes: `0` ok · `2` bad arguments · `3` git error or no commits
  found · `4` version already present.