| name | changelog-generation |
| description | Use when generating release notes or changelogs from PR merges, production deployments, or when the user asks for a summary of changes between branches or releases |
Changelog Generation
Overview
Generate stakeholder-friendly changelogs from pull request merges. Analyzes individual PRs within a merge to produce non-technical release notes organized by impact category. Works for both monorepos (multi-project) and single-project repositories.
When to Use
- User provides a PR link merging a development branch into production
- User asks for release notes or changelog for a deployment
- User asks to summarize changes between branches or tags
Workflow
Model tiering. This skill is mechanical — extract PRs, classify into fixed buckets, and rewrite
titles/descriptions into non-technical bullets against the style guide below. There is no
architectural judgment here. When a merge spans many PRs (roughly 8+), delegate the PR-analysis
pass (steps 1–2) to a subagent dispatched with model: sonnet, handing it the PR list and the
content/categorization rules; it returns the classified, rewritten items and keeps the per-PR gh
chatter out of the main context. For a handful of PRs, run inline — the subagent overhead isn't
worth it. Either way the work is Sonnet-appropriate; reserve the top tier for other skills.
1. PR Analysis
- Receive PR link or branch range from user
- Extract individual PRs included in the merge using
gh pr list or gh api
- Identify affected areas: In monorepos, map changed file paths to projects. In single repos, identify affected modules/features.
- Analyze each PR:
- Extract title and description
- Classify change type (feature, bug fix, enhancement, etc.)
- Determine affected project(s) or module(s)
- Summarize in non-technical terms considering broader codebase context
2. Content Guidelines
Target audience: Non-technical stakeholders
Writing style:
- Brief, high-level descriptions focusing on functionality, not implementation
- Bullet points for easy scanning
- No technical jargon or implementation details
- Focus on user impact and business value
- 1-2 lines maximum per item
- Present tense, active voice
Exclude:
- PR links
- Technical implementation details
- Code-specific terminology
- Developer-focused information
3. Categorization
Organize changes into these categories:
| Category | Include |
|---|
| New Features | New functionality, pages, forms, first-time implementations |
| Bug Fixes | Issue resolutions, error corrections, broken functionality fixes |
| Enhanced User Experience | UI/UX improvements, performance enhancements, accessibility |
| [Dynamic 4th Category] | Name based on remaining changes (e.g., "Infrastructure Updates", "Content Updates") |
4. Formatting
Heading hierarchy: The heading levels differ between monorepos and single-project repos. The rule is that each format uses every level down from H1 without gaps:
- Monorepo: H1 = release date/version → H2 = project → H3 = category section. The date stands alone at the top because it spans every project.
- Single project: there is only one project, so the date and project name are merged into the H1, freeing categories to move up to H2.
Single Project
# [Project Name] Release Notes — [Date or Version]
## New Features
- [Brief description]
## Bug Fixes
- [Description of resolved issue]
## Enhanced User Experience
- [UI/UX improvement]
## [Dynamic Category Name]
- [Other improvements]
Monorepo (Multi-Project)
# Release Notes — [Date or Version]
## [Project Name]
### New Features
- [Project-specific new functionality]
### Bug Fixes
- [Project-specific fixes]
## [Another Project]
### Enhanced User Experience
- [Project-specific improvements]
## System-Wide Changes
### [Dynamic Category Name]
- [Shared schema/infrastructure changes]
Monorepo detection: If the repo has a turbo.json, workspace config in package.json, or multiple distinct project directories, use multi-project format. Group changes by project, with a "System-Wide Changes" section for shared code.
Formatting rule: Do not insert blank lines between subsection headings and their bullet lists.
Quality Checklist
Before finalizing:
