Release Notes

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:

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:

Step 3: Determine Tone

Adjust tone based on audience:

Step 4: Structure the Release Notes

Output Format

# 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:

Anti-Patterns

References

• Keep a Changelog
• Slite: How to Write Release Notes