# Release Notes > - Skill: `frank-luongt/release-notes-2` (Agent Skill) - Install (CLI): `npx skillmds@latest add frank-luongt/release-notes-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/frank-luongt/release-notes-2/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: frank-luongt (https://skillmd.com/u/frank-luongt) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/frank-luongt/release-notes-2 --- --- name: release-notes description: Transform technical changelogs and tickets into user-facing release notes written in benefit language. Use when shipping a release, communicating product updates, or preparing changelog communications. tags: [release-notes, communication, changelog, product-updates] --- # Release Notes Transform technical changelogs, PRs, and tickets into clear, user-facing release notes that communicate **what changed and why it matters** — in language customers understand. --- ## Purpose Technical changelogs are written for developers. Release notes are written for customers. This skill bridges the gap — translating implementation details into benefit-oriented language that helps users understand, adopt, and appreciate product improvements. --- ## When to Use - After merging a release branch and preparing for deployment - Weekly or bi-weekly product update communications - Monthly product newsletters - App store update descriptions - In-app "What's New" notifications ## When NOT to Use - Internal engineering changelogs (keep those technical) - Security advisories (use a dedicated security disclosure format) - API breaking change notices (use migration guides) --- ## Required Input Provide any combination of: - Git log / PR list for the release - Completed JIRA/Linear tickets - Sprint review notes - PRD sections for shipped features - Technical changelogs --- ## The Process ### Step 1: Categorize Changes Sort every change into one of these categories: | Category | Icon | Description | | --- | --- | --- | | **New Features** | New | Entirely new capabilities | | **Improvements** | Improved | Enhancements to existing features | | **Bug Fixes** | Fixed | Issues that are now resolved | | **Breaking Changes** | Breaking | Changes that require user action | | **Deprecations** | Deprecated | Features being removed in a future release | ### Step 2: Rewrite in Benefit Language Transform each change from technical to user-facing: **Rules:** - Lead with the **benefit**, not the implementation - Use **plain language** — no jargon, no ticket numbers, no internal terms - Keep each entry to **1–3 sentences** - Be specific about the improvement (quantify when possible) **Examples:** | Technical (Before) | User-Facing (After) | | --- | --- | | Implemented Redis caching for dashboard queries | Dashboards now load up to 3x faster | | Fixed null pointer exception in report export | Report exports no longer fail for accounts with empty custom fields | | Added SAML SSO support (SCIM provisioning) | Enterprise teams can now sign in with their company SSO — no more separate passwords | | Migrated search to Elasticsearch | Search results are now more accurate and return in under 200ms | | Refactored payment processing module | (Omit — internal refactoring with no user-visible change) | | Updated React from v17 to v18 | (Omit — unless there's a user-visible improvement) | ### Step 3: Determine Tone Adjust tone based on audience: | Audience | Tone | Example | | --- | --- | --- | | **B2B Professional** | Clear, confident, concise | "Dashboards now load up to 3x faster." | | **Consumer / Friendly** | Warm, conversational, excited | "Your dashboards just got a speed boost — they load 3x faster now!" | | **Developer / API** | Technical, precise, actionable | "Dashboard API response times reduced from ~900ms to ~300ms via query caching." | ### Step 4: Structure the Release Notes --- ## Output Format ```markdown # Release Notes — [Version or Date] **Released:** [date] --- ## New Features ### [Feature Name] [1-3 sentences describing what it does and why it matters to the user] ### [Feature Name] [description] --- ## Improvements - **[Area]** — [What improved and the benefit] - **[Area]** — [What improved and the benefit] --- ## Bug Fixes - Fixed an issue where [user-visible problem] — [what works now] - Fixed an issue where [user-visible problem] — [what works now] --- ## Breaking Changes ### [Change Description] **What changed:** [specific change] **What you need to do:** [clear migration steps] **Deadline:** [if applicable] --- ## Deprecations - **[Feature/API]** will be removed on [date]. [Migration path or alternative]. ``` --- ## Filtering Rules **Include:** - Any change that affects what users see, do, or experience - Performance improvements users would notice - Bug fixes for reported issues - Security improvements (without disclosing vulnerability details) **Exclude:** - Internal refactoring with no user-visible impact - Dependency updates (unless they fix a user-visible issue) - Build system or CI/CD changes - Test additions or modifications - Code style or formatting changes --- ## Distribution Channels Adapt the release notes for each channel: | Channel | Format | Length | | --- | --- | --- | | In-app notification | 1–3 bullet highlights | Very short | | Email newsletter | Full release notes with context | Medium | | Blog post | Narrative with screenshots | Long | | App store description | Top 3 changes in bullet form | Very short | | Changelog page | Full structured notes | Medium | | Slack/Discord | Emoji-formatted highlights | Short | | API docs | Technical details + migration guides | Technical | --- ## Anti-Patterns | Avoid | Why | Instead | | --- | --- | --- | | Ticket numbers in notes | Customers don't know what PROJ-1234 means | Describe the change in plain language | | "Various bug fixes" | Dismissive, unhelpful, erodes trust | List specific fixes or say "stability improvements including [example]" | | Technical jargon | "Optimized SQL query" means nothing to users | "Reports now load faster" | | Listing internal refactors | Adds noise, no user value | Only include user-visible changes | | No categorization | Hard to scan, important changes get buried | Use consistent categories | | Stale release notes | Notes published days/weeks after release | Ship notes with the release | --- ## References - [Keep a Changelog](https://keepachangelog.com/) - [Slite: How to Write Release Notes](https://slite.com/learn/release-notes)