# Release Narrative

> Write release notes, what's new posts, and ship announcements that tell users what shipped in their terms. Use whenever the user mentions release notes, changelog, what's new, ship announcement, version notes, or needs to communicate what changed in a release.

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

---


# release-narrative

release notes are user-facing. they exist to help users get value from what shipped. write for them, not for the internal team.

## the structure

```
[version] — [date]

[one-sentence summary of the headline change in user value terms]

new
- [feature]: [what it does for the user, in their language]

improved
- [improvement]: [the before and after, concretely]

fixed
- [bug]: [the symptom, not the technical cause]

breaking changes (only when present)
- [thing]: [old behavior → new behavior, with migration step]

heads up (only when present)
- [anything that affects workflow even if not a breaking change]
```

## the rules

### order by user impact, not by ship order

the most important change to the most users goes first. internal ordering, alphabetical ordering, or ticket-number ordering all serve the team, not the reader.

### one sentence per item

if you need two sentences, the item is two items, or you're explaining instead of stating.

### user language

what the user sees and does. not what the database does.

- bad: "fixed null pointer exception in the auth middleware on token expiration"
- good: "fixed an issue where you'd get logged out unexpectedly during long sessions"

### specific over general

- bad: "improved performance"
- good: "dashboards with 1000+ rows now load in 1.2 seconds, down from 4 seconds"

### one verb tense across all items

usually past tense for what shipped. don't mix "added" and "you can now".

### no internal jargon

no jira ticket numbers in user-facing notes. no internal project codenames. no "as discussed in the #product channel".

### breaking changes get prominent treatment

if there's a breaking change, label it clearly, name the old and new behavior, and tell users exactly what to change.

## what not to include

- celebrating internal milestones in user-facing channels
- "we listened to your feedback" (just ship the fix)
- "exciting news" (the news is the news)
- every commit (release notes are not a git log)
- bugs nobody noticed (sometimes leave them out; sometimes mention them with context)

## the tone

calm. confident. specific. write like a colleague telling another colleague what happened, not like a marketing department.

if the brand voice is more playful, the structure stays the same; the diction relaxes a notch. don't sacrifice clarity for personality.

## output

```
[version] — [date]

[summary sentence]

new
- [items in user-impact order]

improved
- [items in user-impact order]

fixed
- [items in user-impact order]

breaking changes (if any)
- [items with migration steps]

heads up (if any)
- [items]
```

length depends on the release. a small patch may be three bullets. a major release with breaking changes may be a longer post with deep-link sections.

## what to avoid

- inflating tiny changes
- understating breaking changes
- using exclamation points to signal importance
- ending with "as always, thanks for using [product]"
- a post-mortem disguised as release notes (post-mortems are their own genre)