Skip to content
Hidden Logic Lab

Draft a customer changelog from a git range via SKILL.md

Claude Code or Cursor follows a SKILL.md that reads a commit or merge range and drafts customer-facing changelog entries with categories and explicit breaking-change callouts.

Cursor, Claude Code, GitHub
·Writing·25 min·Working

A changelog skill checked into the repo, a draft CHANGELOG section for the range, and breaking changes boxed so support and sales see them before publish.

  1. 1

    Run the skill on your last real tag

    Compare the draft to what you actually shipped. Adjust categories and product-area labels until the output matches your voice.

  2. 2

    Commit beside CHANGELOG.md

    Point AGENTS.md at the skill for release chores. One skill file beats a new chat prompt every sprint.

  3. 3

    Publish breaking changes early

    Send the Breaking subsection to support before the tag push. The skill is done when they confirm wording, not when markdown exists.

The prompt to paste

Write SKILL.md for drafting a customer-facing changelog from a git commit range and merged pull requests. Internal chores stay out of the user-facing sections unless they affect operators.

Repository context:
[how you tag releases e.g. v*, main branch, changelog file path CHANGELOG.md or docs/changelog]
[git log / gh pr list commands your team actually uses]
[product areas for grouping e.g. API, Dashboard, Mobile, CLI]

Range context (paste when using):
[from ref e.g. v1.2.0, to ref e.g. v1.3.0 or main@sha]
[optional: gh pr list --merge JSON or paste of merged PR titles]

SKILL.md must include:
1. Purpose — ship accurate release notes derived from git history, not marketing filler.
2. When to use — before tagging a release or sending a product update email; when not to use — mid-sprint internal snapshots without a version.
3. Required inputs: from/to refs, audience (customers vs operators), and whether to include security advisories by CVE id only.
4. Steps for the agent:
   - List commits and merged PRs in range; dedupe merge commits vs squash messages.
   - Read diffs for user-visible PRs; ignore dependency-only bumps unless they fix a known customer issue.
   - Classify each item: Added, Changed, Fixed, Deprecated, Removed, Security — one bullet per customer-visible item.
   - Breaking changes: separate subsection with migration steps; each item names what breaks, who is affected, and deadline if any.
   - Write [verify] on any bullet the commit message claims but the diff does not show.
5. Output format template the skill embeds:
   - ## [Version] — [date]
   - ### Breaking changes (omit section if none after explicit check)
   - ### Added / Changed / Fixed / …
   - ### Internal (optional, one line each, for engineering readers only)
6. Two example prompts: patch release with fixes only vs minor with API shape change.
7. Pitfalls: inventing features from vague commit titles, hiding breaking changes in Fixed, listing every refactor, quoting internal ticket ids customers do not know, skipping docs-only UX changes.
8. Done means: every bullet traceable to a commit or PR link, breaking section explicitly confirmed empty or filled, no [verify] lines left for publish.

Rules:
- Do not invent version numbers; use refs from the paste.
- Prefer behavior language over file names in customer bullets.
- Output only SKILL.md markdown.

Squash merges hide PR bodies. The skill should require gh pr view or linked PR text for anything labeled breaking, not only the one-line commit subject.

Sample case written by Hidden Logic Lab. Not affiliated with Cursor or Claude Code or GitHub.

More in Writing

Get new cases in your inbox

Weekly notes on new use cases and agent workflows. No product pitches.

Occasional notes on new cases. No product pitches in the first note.