changelog-from-commits

SKILL.md

Changelog from commits

Drafts polished release notes from raw commit history. Two failure modes this skill is built to avoid: (1) mechanical bullet-by-bullet "what dev wrote in the commit" notes that nobody reads, and (2) marketing fluff that hides the actual changes. Aim is the third thing: a tight, honest, useful note.

When to trigger

• The user pastes git log, git log --oneline, GitHub PR titles, or a list of commits.
• The user says: "write release notes", "draft a changelog for v1.4", "summarize what we shipped", "user-facing version of this", "what should we tell users".
• The user says they're shipping a release and asks how to communicate it.

Workflow

1. Read voice.md for tone rules (default: warm, plain, second person, no marketing-speak).
2. Read audiences.md to know which audience(s) to tailor for. Most products have at least two: end-users and devs/integrators. The same release may need two different write-ups.
3. Group commits into themes. Skip pure refactor / chore / dependency-bump commits unless they have user impact. Bucket the rest:
   • New — features users can now do that they couldn't before.
   • Better — existing features improved (perf, UX, reliability).
   • Fixed — bugs squashed.
   • Heads up — breaking changes, deprecations, things that require user action.
4. Write each item once, in user language. Convert "Refactor billing service to use idempotency key" → "Fixed: rare double-charge on retry from flaky networks." Always lead with the user-visible benefit; mention the technical detail only if devs need it.
5. Cite commit hashes/PR numbers in parentheses. Keeps the artifact traceable for the team without cluttering the prose.
6. Add a one-line release headline at the top — what's the single most important thing in this release. If you can't pick one, the release is too big or too small.
7. End with a "How to update" line if action is required. Skip if not.

Output format

# v{{version}} — {{one-line headline}}

_{{date}} · {{words-of-context-if-any}}_

## New
- ... (#PR)

## Better
- ... (#PR)

## Fixed
- ... (#PR)

## Heads up
- ... (#PR)

## How to update
{{or skip if not needed}}

Hard rules

• Never invent a feature. If a commit message is cryptic, ask the user to clarify or explicitly say (unclear from commit message — verify before publishing).
• Never list more than 8 items per section. If you would, the release is doing too much; split into themes or push some to "minor changes" at the bottom.
• No exclamation marks. Excitement is in the substance, not the punctuation.
• No "we're excited to announce" or any variant. State what shipped.
• Always cite at least one commit hash/PR per item — even if it's (see internal commit a1b2c3d).

voice.md

Default profile. Edit to taste.

• Warm, plain, second-person ("you can now…").
• No marketing fluff: skip "delighted to", "excited to announce", "best-in-class", "seamless".
• No exclamation marks.
• Past tense for what shipped, present for current state, no future tense (don't promise next release in this release's notes).
• Use specific numbers when you have them ("30% faster page load" beats "faster page load").
• Lead with user benefit; technical detail in parens only when it matters to a developer.

Length

• One screen of text max. If your changelog is longer, your release is too big.
• Each bullet: one sentence. Maximum two clauses.

audiences.md

By default this skill produces a single end-user-facing changelog. If your release has multiple audiences, list them here and the skill will produce one variant per audience.

end-users

• Who: the people who click around in the product.
• Care about: what's new they can do, what's faster, what's no longer broken.
• Don't care about: refactors, dependency upgrades, internal architecture.

developers (if you ship an SDK or API)

• Who: integrators using your API/SDK.
• Care about: breaking changes (loud), new endpoints, deprecations, perf characteristics, type changes.
• Format: include version constraints, migration paths, before/after code blocks where useful.

ops / SREs (rarely needed)

• Care about: runtime behavior, resource changes, deployment-affecting flags.
• Format: terse, actionable, with rollback notes.

examples/01_input_git_log.md → examples/02_output_release_notes.md

Input: a raw git log between v1.3 and v1.4 with billing fixes, dashboard CSV export, keyboard shortcuts, an API perf cache, and a deprecation notice. The user asks: "Write release notes for v1.4. Two versions: end-users and developers."

End-user variant:

# v1.4 — CSV exports, keyboard nav, and a billing fix you'll never see

_April 27, 2026_

## New
- Export any report table to CSV. Look for the new export button in
  the top right of every table. (#418)
- Keyboard shortcuts for navigating rows: J for next, K for previous.
  Works on every list in the app. (#419)

## Better
- Project list pages load in about a quarter of the time they used to
  (340ms → 90ms at p95). (#421)

## Fixed
- Sessions that expired in the middle of work used to dump you on a
  500 error. Now you get the login page, the way it was supposed to
  work. (#427)
- Closed a rare hole where a flaky network could cause a double-charge
  on retry. (#412, #414)

Developer variant:

# v1.4 — API import, /v1/projects cache, deprecation notice

_April 27, 2026_

## New
- POST /v1/projects/import — bulk-import projects from a JSON array.
  Up to 500 projects per call. See API docs for schema. (#430)

## Better
- GET /v1/projects is now cached server-side for 60s. p95 dropped from
  340ms to 90ms. Cache-Control headers reflect this. (#421)

## Fixed
- All payment retries now use idempotency keys. Webhook delivery
  duplicates no longer cause duplicate charges. (#412, #414)
- 401 responses on expired sessions instead of 500s. Status code
  change is the only API-visible effect. (#427)

## Heads up — deprecation
- POST /v1/legacy_projects is deprecated this release and will be
  removed in v2.0. Migrate to POST /v1/projects. (#432)

## How to update
- API consumers: no client changes required for v1.4 itself.
- Stop using /v1/legacy_projects before v2.0 ships (Q3 2026).