Product Changelog
When to Use This Skill
Use this skill when you need to:
- Create a changelog format and template for ongoing product updates
- Write user-friendly version notes for a product release
- Categorize changes into new features, improvements, and bug fixes
- Establish a consistent changelog cadence and style
DO NOT use this skill for internal release notes (engineering-facing), feature announcements (marketing-facing), or technical API documentation. This is for user-facing product changelogs.
Core Principle
A CHANGELOG BUILDS USER TRUST BY SHOWING CONTINUOUS IMPROVEMENT — WRITE EVERY ENTRY SO A NON-TECHNICAL USER UNDERSTANDS WHAT CHANGED AND WHY IT MATTERS TO THEM.
Phase 1: Brief
Required Inputs
| Input |
What to Ask |
Default |
| Product name |
"What product is this changelog for?" |
No default — must be provided |
| Update frequency |
"How often do you ship updates? Weekly, biweekly, monthly?" |
Biweekly |
| Audience |
"Are changelog readers technical or non-technical?" |
Non-technical business users |
| Current changes |
"List the changes in this update — features, improvements, and fixes." |
No default — must be provided |
| Version numbering |
"Do you use version numbers, dates, or both?" |
Date-based (e.g., January 15, 2026) |
| Distribution |
"Where does the changelog live? In-app, blog, email, dedicated page?" |
Dedicated changelog page |
GATE: Confirm the brief before writing.
Phase 2: Structure
Category System
Every change falls into one of these categories:
- New — Features or capabilities that did not exist before
- Improved — Enhancements to existing features (performance, UX, expanded functionality)
- Fixed — Bug fixes and issue resolutions
- Removed (use sparingly) — Deprecated features with migration guidance
Entry Format
Each changelog entry follows this structure:
### [Date or Version]
**New**
- **[Feature name]** — [What it does and why it matters in one sentence]
**Improved**
- **[Feature name]** — [What changed and the user benefit]
**Fixed**
- **[Issue description]** — [What was broken and confirmation it is resolved]
GATE: Confirm the category system and format before writing entries.
Phase 3: Write
Writing Rules
- Lead with the benefit, not the technical change. "Invoices now send 3x faster" beats "Optimized invoice queue processing."
- One sentence per entry. If it needs more, it deserves a feature announcement.
- Use active voice. "You can now export to PDF" not "PDF export has been added."
- Be specific about fixes. "Fixed: Emails with attachments over 5MB failed to send" not "Fixed email bug."
- Group related changes. If 3 fixes relate to the same feature, list them under one sub-heading.
Tone Guide
- Conversational but professional
- Celebratory for big features ("We have been working on this one for months...")
- Matter-of-fact for fixes (acknowledge, confirm fixed, move on)
- No apologies for bugs — just fix and state clearly
Entry Length Guide
| Category |
Length |
Detail Level |
| Major new feature |
2-3 sentences |
Benefit + how to access it |
| Minor improvement |
1 sentence |
What changed + benefit |
| Bug fix |
1 sentence |
What was broken + resolved |
| Deprecation |
2-3 sentences |
What, when, migration path |
Phase 4: Polish
1. Changelog Page Template
Provide a recommended page layout:
- Product name and "Changelog" or "What's New" header
- Filter/search by category (New, Improved, Fixed)
- Subscribe option (email or RSS)
- Archive with expandable months or pagination
- Link to roadmap or feature request board
2. Distribution Plan
- In-app: Badge notification on changelog link when new entries exist
- Email: Monthly digest of changes for subscribers
- Social: Highlight major features in a dedicated post
- Blog: Full write-up for major releases only
3. Quality Checklist
## Changelog Quality Checklist
- [ ] Every entry starts with a benefit, not a technical description
- [ ] Changes are categorized as New, Improved, or Fixed
- [ ] Each entry is one sentence (major features may use 2-3)
- [ ] Active voice used throughout
- [ ] Bug fixes describe what was broken specifically
- [ ] No jargon — readable by non-technical users
- [ ] Date or version number is included
- [ ] Deprecated features include migration guidance
- [ ] Subscribe/notification option exists for the changelog page
Example
### February 15, 2026
**New**
- **Recurring invoices** — Set any invoice to automatically send on a schedule (weekly, monthly, or custom). Find it under Invoice Settings.
- **Client portal** — Your clients can now view all their invoices and payment history in one place. Share the link from any client profile.
**Improved**
- **Dashboard loading speed** — Dashboard now loads 60% faster, especially for accounts with 500+ invoices.
- **CSV exports** — Exports now include payment status and date columns by default.
**Fixed**
- **Tax calculation on discounted items** — Tax was calculated before the discount was applied, resulting in overcharges. Now calculates correctly on the discounted amount.
- **Email notifications** — Some users were not receiving payment confirmation emails. Resolved for all accounts.
Anti-Patterns
- Technical jargon — "Refactored the webhook handler" means nothing to users. Translate to impact.
- Vague fix descriptions — "Fixed a bug" tells users nothing. Be specific about what was broken.
- Skipping updates — inconsistent changelogs erode trust. Ship on your stated cadence, even if it is a small update.
- Marketing fluff in changelogs — save the hype for feature announcements. Changelogs should be factual and scannable.
- No categorization — a flat list of changes is hard to scan. Always categorize.
Recovery
- Very few changes this cycle: Combine with the next cycle, or ship a brief update noting improvements and behind-the-scenes work.
- Breaking change included: Lead with the breaking change, explain what users need to do, and provide a migration guide link.
- User-reported bug is fixed: Consider naming the fix in a way that acknowledges the report: "Fixed (thanks for reporting!): [description]."
- No changelog exists yet: Create a retroactive launch entry summarizing the product's current capabilities, then begin regular updates.
1---2name: product-changelog3description: "Creates product changelog formats with version notes, categorization (new, improved, fixed), and user-friendly language. Use when documenting product updates for users."4allowed-tools: Read Write Glob5metadata:6 source: https://skillmd.com/skills/reaperinvest/product-changelog7 author: matthewhitcham8 version: "1.0"9---1011# Product Changelog1213## When to Use This Skill1415Use this skill when you need to:16- Create a changelog format and template for ongoing product updates17- Write user-friendly version notes for a product release18- Categorize changes into new features, improvements, and bug fixes19- Establish a consistent changelog cadence and style2021**DO NOT** use this skill for internal release notes (engineering-facing), feature announcements (marketing-facing), or technical API documentation. This is for user-facing product changelogs.2223---2425## Core Principle2627A CHANGELOG BUILDS USER TRUST BY SHOWING CONTINUOUS IMPROVEMENT — WRITE EVERY ENTRY SO A NON-TECHNICAL USER UNDERSTANDS WHAT CHANGED AND WHY IT MATTERS TO THEM.2829---3031## Phase 1: Brief3233### Required Inputs3435| Input | What to Ask | Default |36|-------|------------|---------|37| **Product name** | "What product is this changelog for?" | No default — must be provided |38| **Update frequency** | "How often do you ship updates? Weekly, biweekly, monthly?" | Biweekly |39| **Audience** | "Are changelog readers technical or non-technical?" | Non-technical business users |40| **Current changes** | "List the changes in this update — features, improvements, and fixes." | No default — must be provided |41| **Version numbering** | "Do you use version numbers, dates, or both?" | Date-based (e.g., January 15, 2026) |42| **Distribution** | "Where does the changelog live? In-app, blog, email, dedicated page?" | Dedicated changelog page |4344**GATE: Confirm the brief before writing.**4546---4748## Phase 2: Structure4950### Category System5152Every change falls into one of these categories:5354- **New** — Features or capabilities that did not exist before55- **Improved** — Enhancements to existing features (performance, UX, expanded functionality)56- **Fixed** — Bug fixes and issue resolutions57- **Removed** (use sparingly) — Deprecated features with migration guidance5859### Entry Format6061Each changelog entry follows this structure:6263```64### [Date or Version]6566**New**67- **[Feature name]** — [What it does and why it matters in one sentence]6869**Improved**70- **[Feature name]** — [What changed and the user benefit]7172**Fixed**73- **[Issue description]** — [What was broken and confirmation it is resolved]74```7576**GATE: Confirm the category system and format before writing entries.**7778---7980## Phase 3: Write8182### Writing Rules8384- **Lead with the benefit, not the technical change.** "Invoices now send 3x faster" beats "Optimized invoice queue processing."85- **One sentence per entry.** If it needs more, it deserves a feature announcement.86- **Use active voice.** "You can now export to PDF" not "PDF export has been added."87- **Be specific about fixes.** "Fixed: Emails with attachments over 5MB failed to send" not "Fixed email bug."88- **Group related changes.** If 3 fixes relate to the same feature, list them under one sub-heading.8990### Tone Guide9192- Conversational but professional93- Celebratory for big features ("We have been working on this one for months...")94- Matter-of-fact for fixes (acknowledge, confirm fixed, move on)95- No apologies for bugs — just fix and state clearly9697### Entry Length Guide9899| Category | Length | Detail Level |100|----------|--------|-------------|101| Major new feature | 2-3 sentences | Benefit + how to access it |102| Minor improvement | 1 sentence | What changed + benefit |103| Bug fix | 1 sentence | What was broken + resolved |104| Deprecation | 2-3 sentences | What, when, migration path |105106---107108## Phase 4: Polish109110### 1. Changelog Page Template111112Provide a recommended page layout:113- Product name and "Changelog" or "What's New" header114- Filter/search by category (New, Improved, Fixed)115- Subscribe option (email or RSS)116- Archive with expandable months or pagination117- Link to roadmap or feature request board118119### 2. Distribution Plan120121- **In-app:** Badge notification on changelog link when new entries exist122- **Email:** Monthly digest of changes for subscribers123- **Social:** Highlight major features in a dedicated post124- **Blog:** Full write-up for major releases only125126### 3. Quality Checklist127128```129## Changelog Quality Checklist130131- [ ] Every entry starts with a benefit, not a technical description132- [ ] Changes are categorized as New, Improved, or Fixed133- [ ] Each entry is one sentence (major features may use 2-3)134- [ ] Active voice used throughout135- [ ] Bug fixes describe what was broken specifically136- [ ] No jargon — readable by non-technical users137- [ ] Date or version number is included138- [ ] Deprecated features include migration guidance139- [ ] Subscribe/notification option exists for the changelog page140```141142---143144## Example145146```147### February 15, 2026148149**New**150- **Recurring invoices** — Set any invoice to automatically send on a schedule (weekly, monthly, or custom). Find it under Invoice Settings.151- **Client portal** — Your clients can now view all their invoices and payment history in one place. Share the link from any client profile.152153**Improved**154- **Dashboard loading speed** — Dashboard now loads 60% faster, especially for accounts with 500+ invoices.155- **CSV exports** — Exports now include payment status and date columns by default.156157**Fixed**158- **Tax calculation on discounted items** — Tax was calculated before the discount was applied, resulting in overcharges. Now calculates correctly on the discounted amount.159- **Email notifications** — Some users were not receiving payment confirmation emails. Resolved for all accounts.160```161162---163164## Anti-Patterns165166- **Technical jargon** — "Refactored the webhook handler" means nothing to users. Translate to impact.167- **Vague fix descriptions** — "Fixed a bug" tells users nothing. Be specific about what was broken.168- **Skipping updates** — inconsistent changelogs erode trust. Ship on your stated cadence, even if it is a small update.169- **Marketing fluff in changelogs** — save the hype for feature announcements. Changelogs should be factual and scannable.170- **No categorization** — a flat list of changes is hard to scan. Always categorize.171172---173174## Recovery175176- **Very few changes this cycle:** Combine with the next cycle, or ship a brief update noting improvements and behind-the-scenes work.177- **Breaking change included:** Lead with the breaking change, explain what users need to do, and provide a migration guide link.178- **User-reported bug is fixed:** Consider naming the fix in a way that acknowledges the report: "Fixed (thanks for reporting!): [description]."179- **No changelog exists yet:** Create a retroactive launch entry summarizing the product's current capabilities, then begin regular updates.