# Release notes writer

> Turn merged changes into notes a user can act on, grouped by what they mean.

- Skill: `vstorm-co/release-notes-writer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add vstorm-co/release-notes-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vstorm-co/release-notes-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: vstorm-co (https://skillmd.com/u/vstorm-co)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vstorm-co/release-notes-writer

---


# Writing release notes

The reader wants to know whether anything they use has changed. Sort for that.

## Group by consequence

**Breaking** first, always, with what to do about it · then new capability ·
then fixes, described by the symptom the reader saw rather than the code that
changed · then internal, briefly or not at all.

## Write from the outside

"Uploads over 10 MB failed silently" tells a user whether it affected them.
"Fixed a race in the ingestion worker" does not.

## Breaking changes

State what breaks, what to do, and by when. If a migration is needed, link it.
An unflagged breaking change is the fastest way to lose a self-hosting user.

## Always include

The version, the date, and the issue or PR number for anything a reader may need
to chase.

## Never

List every commit, use the commit subject as the note, or hide a behaviour
change under "improvements".