Make Changelog
Generate structured, user-facing changelog entries and release notes from Git commit ranges, GitHub Pull Requests, or staged diffs. Use the bundled Python CLI to inspect repository state deterministically and patch target CHANGELOG.md files idempotently.
Public entrypoints
The primary entrypoint for mk-changelog is the Python CLI at scripts/cli.py.
uv run --script <skill-dir>/scripts/cli.py <command> [options]
Required follow-up reads
| Need |
Read |
When |
| Keep a Changelog standards & categories |
references/conventions.md |
Before drafting or categorizing entries |
| Semantic synthesis prompt templates |
references/prompts.md |
When generating changelog bullets from prepared context |
Workflow
Resolve <skill-dir> to this skill directory.
Extract deterministic commit, PR, diff, and monorepo changelog boundary context:
# 1. From a local commit range (e.g. branch to main, or tag to HEAD)
uv run --script <skill-dir>/scripts/cli.py prepare --range main..HEAD [--repo PATH]
# 2. From a GitHub Pull Request URL or number
uv run --script <skill-dir>/scripts/cli.py prepare --pr https://github.com/owner/repo/pull/123
# 3. From local staged or working tree changes
uv run --script <skill-dir>/scripts/cli.py prepare --staged [--repo PATH]
The command outputs a single structured JSON payload containing:
commits: normalized commit records (hash, subject, category, author, PR reference, revert status).boundaries: mapped CHANGELOG.md paths with their respective modified files.existing_entries: already documented items under ## [Unreleased] to prevent duplicates.contributors: external contributors attribution mapping.diff_stat: file-level change statistics.
Distill and synthesize user-facing entries using the prompt guidance in references/prompts.md. Focus strictly on user-observable behavior; omit internal refactoring, tests, and CI churn.
Output the result depending on your goal:
For PR Body / Release Notes (no file writes):
uv run --script <skill-dir>/scripts/cli.py format --entries-file <temp-dir>/entries.json
For CHANGELOG.md update (idempotent disk patch under ## [Unreleased]):
uv run --script <skill-dir>/scripts/cli.py patch --target CHANGELOG.md --entries-file <temp-dir>/entries.json
Invariants
- Keep entries grouped by standard Keep a Changelog categories:
Breaking Changes, Added, Changed, Deprecated, Removed, Fixed, Security.
- Start each entry with a past-tense verb (Added, Fixed, Changed, Updated) and omit trailing periods.
- Preserve deterministic community attribution format:
([#123](url) by @user).
- Never duplicate entries already present under
## [Unreleased].
- In monorepos, update the nearest package-level
CHANGELOG.md unless instructed to target the root changelog.
1---2name: mk-changelog3description: Generate Keep a Changelog entries and release notes from Git commits, PRs, or staged diffs.4license: AGPL-3.0-or-later5---67# Make Changelog89Generate structured, user-facing changelog entries and release notes from Git commit ranges, GitHub Pull Requests, or staged diffs. Use the bundled Python CLI to inspect repository state deterministically and patch target `CHANGELOG.md` files idempotently.1011## Public entrypoints1213The primary entrypoint for `mk-changelog` is the Python CLI at `scripts/cli.py`.1415```text16uv run --script <skill-dir>/scripts/cli.py <command> [options]17```1819## Required follow-up reads2021| Need | Read | When |22| --- | --- | --- |23| Keep a Changelog standards & categories | `references/conventions.md` | Before drafting or categorizing entries |24| Semantic synthesis prompt templates | `references/prompts.md` | When generating changelog bullets from prepared context |2526## Workflow27281. Resolve `<skill-dir>` to this skill directory.292. Extract deterministic commit, PR, diff, and monorepo changelog boundary context:3031 ```text32 # 1. From a local commit range (e.g. branch to main, or tag to HEAD)33 uv run --script <skill-dir>/scripts/cli.py prepare --range main..HEAD [--repo PATH]3435 # 2. From a GitHub Pull Request URL or number36 uv run --script <skill-dir>/scripts/cli.py prepare --pr https://github.com/owner/repo/pull/1233738 # 3. From local staged or working tree changes39 uv run --script <skill-dir>/scripts/cli.py prepare --staged [--repo PATH]40413. The command outputs a single structured JSON payload containing:42 - `commits`: normalized commit records (hash, subject, category, author, PR reference, revert status).43 - `boundaries`: mapped `CHANGELOG.md` paths with their respective modified files.44 - `existing_entries`: already documented items under `## [Unreleased]` to prevent duplicates.45 - `contributors`: external contributors attribution mapping.46 - `diff_stat`: file-level change statistics.47484. Distill and synthesize user-facing entries using the prompt guidance in `references/prompts.md`. Focus strictly on user-observable behavior; omit internal refactoring, tests, and CI churn.49505. Output the result depending on your goal:5152 - **For PR Body / Release Notes (no file writes):**53 ```text54 uv run --script <skill-dir>/scripts/cli.py format --entries-file <temp-dir>/entries.json55 ```5657 - **For CHANGELOG.md update (idempotent disk patch under ## [Unreleased]):**58 ```text59 uv run --script <skill-dir>/scripts/cli.py patch --target CHANGELOG.md --entries-file <temp-dir>/entries.json60 ```61## Invariants6263- Keep entries grouped by standard Keep a Changelog categories: `Breaking Changes`, `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`.64- Start each entry with a past-tense verb (Added, Fixed, Changed, Updated) and omit trailing periods.65- Preserve deterministic community attribution format: `([#123](url) by @user)`.66- Never duplicate entries already present under `## [Unreleased]`.67- In monorepos, update the nearest package-level `CHANGELOG.md` unless instructed to target the root changelog.
anntnzrb