arabelatso/release-notes-writer
Automatically generate user-facing release notes from git commits, pull requests, changelogs, and code changes. Use when preparing software releases, creating version announcements, documenting what changed between versions, or communicating updates to users. Analyzes commit messages, PR descriptions, and code diffs to produce categorized markdown release notes organized by New Features, Improvements, Bug Fixes, and Breaking Changes. Focuses on user-visible changes while filtering out internal/technical details. Triggers when users ask to generate release notes, create changelog, write version announcement, or summarize changes for a release.
npx skills add https://github.com/ArabelaTso/Skills-4-SE --skill release-notes-writer
Generate polished, user-facing release notes from git history, pull requests, and code changes, automatically categorizing and summarizing changes in a clear, accessible format.
Collect the scope and sources for the release notes:
Define the release scope:
Quick commands to get started:
# Get commits since last tag
git log $(git describe --tags --abbrev=0)..HEAD --oneline
# Get commits between two tags
git log v2.0.0..v2.1.0 --oneline
# Get commits since specific date
git log --since="2024-01-01" --oneline
# List all tags
git tag -l
# Get merged PRs (if using GitHub)
gh pr list --state merged --limit 50
Gather details from available sources:
# Get commit messages with details
git log v2.0.0..v2.1.0 --pretty=format:"%h - %s (%an)" --no-merges
# Get commits by author
git log v2.0.0..v2.1.0 --author="AuthorName" --oneline
# Get commit messages with full body
git log v2.0.0..v2.1.0 --format="%h %s%n%b%n"
Parse commit message conventions:
feat: or feature: → New Featurefix: or bugfix: → Bug Fixperf: or performance: → Performance Improvementdocs: or doc: → Documentationrefactor: → Code Quality/Refactoringtest: → Testingchore: → Internal/MaintenanceBREAKING: or !: → Breaking ChangeIf using GitHub CLI:
# Get merged PRs
gh pr list --state merged --limit 100 --json number,title,body,labels,mergedAt
# Get PR details
gh pr view <PR-NUMBER>
Extract from PR:
Check for existing changelog entries:
# Look for changelog files
find . -name "CHANGELOG.md" -o -name "HISTORY.md" -o -name "RELEASES.md"
# Check for unreleased section
grep -A 20 "Unreleased" CHANGELOG.md
Infer changes from code when commits lack detail:
# See what files changed
git diff --stat v2.0.0..v2.1.0
# See what functions/classes were added
git diff v2.0.0..v2.1.0 --unified=0 | grep "^+def\|^+class"
# See API changes
git diff v2.0.0..v2.1.0 -- "*.py" | grep -E "^[+-]def |^[+-]class "
Organize changes into standard categories:
User-visible new capabilities:
Examples:
Corrections to existing functionality:
Enhancements to existing features:
Changes requiring user action:
Include:
Exclude or minimize:
Transform technical to user-friendly:
❌ "Refactored AuthService to use dependency injection"
✅ "Improved authentication reliability"
❌ "Updated webpack config for tree shaking"
✅ "Reduced bundle size by 20%"
❌ "Fixed race condition in concurrent processing"
✅ "Improved stability when processing multiple items simultaneously"
Create formatted markdown output:
# Release Notes - Version X.Y.Z
**Release Date:** YYYY-MM-DD
## Summary
[1-3 sentence overview of the release]
---
## ✨ New Features
- **[Feature Title]**: [User-friendly description]
- **[Feature Title]**: [Description with benefit]
## 🚀 Improvements
- **[Improvement Title]**: [How this makes things better]
- **[Improvement Title]**: [Description]
## 🐛 Bug Fixes
- Fixed [issue description]
- Resolved [problem users were experiencing]
## ⚠️ Breaking Changes
- **[Breaking Change Title]**: [What changed and what users need to do]
- **Migration:** [Step-by-step guidance]
- **Before:** `code example`
- **After:** `code example`
---
## 📊 Statistics
- X features added
- Y bugs fixed
- Z improvements made
## 🙏 Contributors
Thank you to all contributors who made this release possible:
- @username1
- @username2
Make each change clear and valuable:
Use active, benefit-focused language:
❌ "Added pagination to API"
✅ "You can now request data in pages, making it easier to work with large datasets"
❌ "Implemented OAuth2 authentication"
✅ "Sign in with your Google, GitHub, or Microsoft account"
❌ "Optimized database queries"
✅ "Reports now load 3x faster"
Be specific about impact:
❌ "Performance improvements"
✅ "Search results now appear in under 100ms, down from 2 seconds"
❌ "Better error handling"
✅ "Error messages now include specific suggestions for fixing the issue"
Include code examples for API changes:
### Breaking Change: Authentication Method Updated
**Before:**
client = APIClient(session_token="abc123")
**After:**
client = APIClient(api_key="sk-abc123")
**Migration:** Update your initialization code to use the new `api_key` parameter.
Before finalizing:
Check completeness:
Check clarity:
Check organization:
# Release Notes - Version 2.3.0
**Release Date:** February 15, 2026
## Summary
Version 2.3.0 brings enhanced search capabilities, performance improvements, and several bug fixes.
---
## ✨ New Features
- **Advanced Search Filters**: Filter search results by date, category, and status for more precise results
- **Keyboard Shortcuts**: Navigate the app faster with new keyboard shortcuts (press `?` to see all)
- **Export to Excel**: Export your data to Excel format in addition to CSV
## 🚀 Improvements
- **Faster Search**: Search results now appear instantly (improved from 2s to <100ms)
- **Better Mobile Experience**: Optimized interface for mobile devices
- **Smarter Autocomplete**: Autocomplete suggestions now learn from your previous searches
## 🐛 Bug Fixes
- Fixed issue where saving large files would occasionally fail
- Resolved problem with date picker not working in Safari
- Corrected timezone display for users in Asia-Pacific regions
---
## 📊 Statistics
- 3 new features
- 4 bugs fixed
- 3 improvements
- 47 commits
- 8 contributors
## 🙏 Contributors
Thank you to: @alice, @bob, @charlie, @diana, @eve, @frank, @grace, @henry
Focus on user value:
Be honest about breaking changes:
Use consistent language:
Group related changes:
Credit contributors:
Take arabelatso/release-notes-writer from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.