# Release Notes

> Write user-facing release notes + changelogs. Keep-a-Changelog format, sections Added/Changed/Fixed/Deprecated/Removed/Security. Per-audience tone (user/dev/ops). Anti-marketing-fluff bans. Wraps `writer`. Use when the user says 'release notes for vX.Y.Z', 'changelog entry', 'what's new', 'product update'.

- **Type:** Skill
- **Install:** `agentstack add skill-mikefluff-skills-release-notes`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Mikefluff](https://agentstack.voostack.com/s/mikefluff)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Mikefluff](https://github.com/Mikefluff)
- **Source:** https://github.com/Mikefluff/skills/tree/main/skills/release-notes
- **Website:** https://www.npmjs.com/package/@mikefluff/skills

## Install

```sh
agentstack add skill-mikefluff-skills-release-notes
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

Write release notes that users actually read. Output: structured markdown release notes ready to publish on a changelog page / inside-app modal / email / GitHub release.

Use when the user wants to announce changes to their product or library to its **users** (or developers consuming an API/SDK). Not for internal engineering decisions — that's `rfc-writer`. Not for marketing landing pages — that's `landing-copy`.

This skill does NOT:
- write RFCs / design docs / ADRs (use `rfc-writer`)
- write landing-page marketing copy (use `landing-copy`)
- write commit messages or PR descriptions (those are for engineers; release notes are downstream)
- write blog posts about a release (different shape — use `essay-write` or `viral-text`)

## ROLE

Read commits / PRs / feature list + target audience → group by Keep-a-Changelog sections → write one bullet per change in the right register → strip marketing fluff → run final writer cleanup → return markdown.

## PIPELINE

1. **Identify audience.** End user (uses the product UI) / developer (uses the API/SDK) / ops (deploys / monitors the product). Tone differs significantly — see `references/audience-tone.md`.

2. **Identify scope.** Single feature announcement / version release / quarterly recap / monthly digest. Each has different length and structure.

3. **Gather changes.** From git log / PR list / user-provided list. Group into:
   - **Added** — new features, new APIs, new options
   - **Changed** — behavior changes (non-breaking)
   - **Fixed** — bug fixes
   - **Deprecated** — still works, will be removed in vX
   - **Removed** — gone in this version
   - **Security** — vulnerabilities patched
   - **Breaking** — only for major versions (semver)

   See `references/sections.md`.

4. **Write one bullet per change.**
   - Lead with the verb in past tense for "Added/Changed/Fixed/Removed"
   - Lead with the noun being deprecated for "Deprecated"
   - One line per bullet (allow continuation only if context matters)
   - User-facing benefit first, technical detail second

5. **Apply anti-fluff rules.** Strip marketing language ("revolutionary", "game-changing"), "We're excited to announce", "We're thrilled to share". See `references/banned-patterns.md`.

6. **Order within sections.** Most-impactful items first. Don't bury big features under a 12-bullet "Fixed" list.

7. **Add a header / lead** (1-2 lines) for context: what version, what date, what theme if there is one. See `references/structure.md`.

8. **Final pass.** Run through `writer` for anti-neuroslop + typography + structural-prose layers.

   **Delete the water, not the function.** Version numbers, dates, migration steps, breaking-change warnings and upgrade commands are load-bearing. Writer's default treatment is deletion; here that turns a changelog into an announcement nobody can act on. Treat them by replacement or simplification, and verify each survived the pass. See `forbidden-substitutions.md` in the `writer` skill.

## MODES

- `release-notes  ` — write release notes for vX.Y.Z
- `release-notes --from-git ` — read git log since a tag, summarize
- `release-notes --from-prs ` — write notes from a list of PR titles/descriptions
- `release-notes --recap quarterly|monthly|annual` — longer recap covering multiple releases
- `release-notes --audience user|dev|ops` — explicit audience selection
- `release-notes --format changelog-md|github-release|email|in-app` — output format
- `release-notes --improve ` — rewrite weak release notes

## REFERENCES (load on demand)

| File | When to load |
|---|---|
| [references/sections.md](references/sections.md) | When categorizing changes — Keep-a-Changelog 6 sections + how to decide which applies |
| [references/audience-tone.md](references/audience-tone.md) | When picking voice — end-user / developer / ops differences |
| [references/structure.md](references/structure.md) | When assembling — version header, lead, ordering, length budgets per format |
| [references/banned-patterns.md](references/banned-patterns.md) | After draft — strip marketing fluff, hype, vague "we improved X" |

## EXAMPLES

See [examples/before-after.md](examples/before-after.md) — 5 calibration pairs: weak release notes vs strong, across SaaS / API / library / mobile-app contexts.

## CONSTRAINTS

- **No marketing hype.** "Revolutionary", "groundbreaking", "game-changing", "next-generation" — strip on sight. The work speaks for itself.
- **No "We're excited / thrilled / proud to announce".** State what shipped. The user doesn't care about your feelings.
- **No "Improved X" without specifics.** Replace with: "Reduced X latency from 2.1s to 380ms" / "Now supports Y format" / "Fixed Z bug that affected users of W".
- **Past tense for shipped work.** "Added dark mode" not "Adding dark mode" not "We are adding dark mode".
- **One bullet per change.** Don't merge two features into one line ("Improved auth and payment flows" → split).
- **Specific over abstract.** "Improved performance" → "Reduced search latency 5x"; "Better security" → "Enabled MFA by default for new accounts".
- **Link to longer docs when relevant.** Release note is the headline; help-article / RFC / docs page is the body.
- **Date in ISO format.** `2026-05-20`, not "May 20, 2026" or "20/05/2026".
- **Version follows semver.** Major (breaking) / minor (features) / patch (fixes).
- **No emoji in dev/ops audience.** OK in light user-facing notes (🎉 for milestones), avoid in technical contexts.

## INVOCATION HINTS

When the user says any of:
- "release notes for vX.Y.Z"
- "changelog entry / update"
- "what's new in version..."
- "summarize this release"
- "monthly / quarterly recap"
- "GitHub release notes"
- "in-app announcement for the latest version"
- "draft a release note about ..."

RU triggers (use the skill when the user writes any of):
- «релизные заметки / релиз-ноуты»
- «changelog для v3.4 / журнал изменений»
- «что нового в версии ...»
- «обнови changelog»
- «опиши релиз / напиши анонс релиза»
- «месячная / квартальная сводка по релизам»
- «текст для in-app анонса нового релиза»

For RU tone (formal B2B, less emoji, числа в RU-формате), see [`references/audience-tone.md`](references/audience-tone.md) section `RU tone notes`.

Use this skill. For internal design docs / RFCs → `rfc-writer`. For marketing landing announcements → `landing-copy`. For viral social posts about the release → `viral-text`.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Mikefluff](https://github.com/Mikefluff)
- **Source:** [Mikefluff/skills](https://github.com/Mikefluff/skills)
- **License:** MIT
- **Homepage:** https://www.npmjs.com/package/@mikefluff/skills

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-mikefluff-skills-release-notes
- Seller: https://agentstack.voostack.com/s/mikefluff
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.