# Release Notes > Writes user-friendly release notes with categorized changes, migration guides, and known issues. Use when communicating software updates to users and stakeholders. - Skill: `reaperinvest/release-notes` (Agent Skill) - Install (CLI): `npx skillmds@latest add reaperinvest/release-notes` - Raw SKILL.md: https://api.skillmd.com/api/skills/reaperinvest/release-notes/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: reaperinvest (https://skillmd.com/u/reaperinvest) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/reaperinvest/release-notes --- # Release Notes ## When to Use This Skill Use this skill when you need to: - Write release notes for a software update or new version - Communicate breaking changes with migration guides - Document known issues and workarounds for a release - Create release notes that serve both technical and non-technical audiences **DO NOT** use this skill for product changelogs (ongoing, shorter entries), feature announcements (marketing-focused), or internal engineering post-mortems. This is for formal release notes tied to a specific version or update. --- ## Core Principle RELEASE NOTES SERVE TWO AUDIENCES SIMULTANEOUSLY — USERS WHO WANT TO KNOW WHAT CHANGED AND DEVELOPERS WHO NEED TO KNOW WHAT BROKE. WRITE FOR BOTH. --- ## Phase 1: Brief ### Required Inputs | Input | What to Ask | Default | |-------|------------|---------| | **Version number** | "What is the version or release identifier?" | No default — must be provided | | **Release date** | "When is this release going live?" | Today | | **Changes list** | "List all changes — features, improvements, fixes, breaking changes." | No default — must be provided | | **Breaking changes** | "Are there any breaking changes that require user action?" | None | | **Known issues** | "Are there any known issues shipping with this release?" | None | | **Audience** | "Are readers technical developers, end users, or both?" | Both | **GATE: Confirm the brief before writing.** --- ## Phase 2: Categorize Changes Sort every change into one of these categories: - **Highlights** — Major features or changes worth calling out at the top - **New Features** — Capabilities that did not exist before - **Improvements** — Enhancements to existing functionality - **Bug Fixes** — Issues resolved in this release - **Breaking Changes** — Changes that require user action or code updates - **Deprecations** — Features being phased out (with timeline) - **Known Issues** — Problems shipping with this release (with workarounds) Present the categorized list for confirmation. **GATE: Confirm categorization before writing the full notes.** --- ## Phase 3: Write ### Release Notes Format ``` # Release Notes — v[X.Y.Z] **Release Date:** [Date] ## Highlights [1-2 paragraph summary of the most important changes in this release. Write for someone skimming — they should understand the impact in 30 seconds.] ## New Features - **[Feature name]** — [What it does and how to access it. 1-2 sentences.] ## Improvements - **[Area improved]** — [What changed and the user benefit. 1 sentence.] ## Bug Fixes - **[Issue description]** — [What was broken and confirmation it is resolved. 1 sentence.] ## Breaking Changes ### [Change title] **Impact:** [Who is affected and how] **Action required:** [Exactly what users must do] **Migration guide:** [Step-by-step instructions] **Deadline:** [When the old behavior stops working] ## Deprecations - **[Feature name]** — Deprecated as of this release. Will be removed in v[X.Y.Z]. Use [alternative] instead. ## Known Issues - **[Issue description]** — [Workaround if available. Expected fix in v[X.Y.Z].] ``` ### Writing Rules - **Highlights section is mandatory** — even for small releases, summarize the key changes in 2-3 sentences - **User-facing language** — translate technical changes to user impact - **Specific bug fix descriptions** — "Fixed login failure on Safari 17" not "Fixed authentication bug" - **Breaking changes get full treatment** — impact statement, action required, migration steps, and deadline - **Known issues include workarounds** — never list a known issue without a workaround or expected fix date --- ## Phase 4: Polish ### 1. Migration Guide (if breaking changes exist) Write a step-by-step migration guide: - Before/after code examples - Configuration changes required - Timeline for backward compatibility - Support contact for migration issues ### 2. Distribution Plan | Channel | Format | Audience | |---------|--------|----------| | In-app notification | Highlight summary + link | All users | | Email | Full release notes | Opted-in users | | Documentation site | Complete notes with migration guides | Developers | | Blog | Highlights only with feature focus | Prospects and public | | Social media | One-liner about the biggest change | General audience | ### 3. Quality Checklist ``` ## Release Notes Checklist - [ ] Version number and date are clearly stated - [ ] Highlights section summarizes key changes in 2-3 sentences - [ ] All changes are categorized (New, Improved, Fixed, Breaking, Deprecated) - [ ] Breaking changes include impact, action required, and migration steps - [ ] Bug fixes describe what was broken specifically - [ ] Known issues include workarounds or fix timelines - [ ] Language is understandable by non-technical users - [ ] No internal jargon, ticket numbers, or code references in user-facing notes - [ ] Distribution plan covers all relevant channels - [ ] Deprecation timeline is specific (version number and date) ``` --- ## Example **Version:** v2.4.0 **Release date:** February 27, 2026 **Highlights excerpt:** "Version 2.4.0 introduces recurring invoices and a redesigned dashboard. Recurring invoices let you schedule automatic billing on any cadence — set it once, and invoices send themselves. The new dashboard loads 60% faster and surfaces your most important metrics at a glance." **Breaking change excerpt:** ``` ### API v1 Endpoints Deprecated **Impact:** All users making API calls to api.example.com/v1/ endpoints. **Action required:** Update your API calls to use /v2/ endpoints by April 30, 2026. **Migration guide:** 1. Replace /v1/ with /v2/ in all endpoint URLs 2. Update the Authorization header format (see docs) 3. Test with the sandbox environment 4. Switch production calls before April 30 **Deadline:** April 30, 2026. After this date, /v1/ endpoints will return 410 Gone. ``` --- ## Anti-Patterns - **Dumping git commit messages** — "Fixed #4521" and "Refactored user service" are not release notes. Translate to user impact. - **Hiding breaking changes** — burying them at the bottom guarantees angry users. Lead with breaking changes or highlight them prominently. - **No migration guide** — telling users something broke without telling them how to fix it is worse than not telling them at all. - **Skipping known issues** — users will find them anyway. Documenting them proactively builds trust. - **Marketing fluff** — release notes are not blog posts. Be factual, specific, and concise. --- ## Recovery - **Tiny release with few changes:** Write a brief note. Even "Bug fixes and performance improvements" is better than silence, but add specifics. - **Major breaking change with complex migration:** Create a dedicated migration guide document. Link from the release notes. - **Known issue with no workaround:** State the issue, acknowledge the impact, and provide a timeline for the fix. Offer direct support contact. - **Release was rolled back:** Publish a note explaining the rollback, what was affected, and when the re-release is expected.