---

name: utils:changelog description: Generate Changelog - analyzes git history and creates a human-readable changelog for non-technical teams

Generate Changelog

Analyzes git history for a specified time period and generates a vibrant, human-readable changelog that non-technical teams will actually enjoy reading. Perfect for product managers, marketing, support teams, and external release notes.

When to use

Use this skill when the user needs to:

• Create release notes for stakeholders
• Summarize development progress for product/marketing teams
• Generate sprint or iteration summaries
• Prepare changelog for external communication

Instructions

Step 1: Parse Arguments

The <args> should specify the time period. Supported formats:

• last week, last month, last 2 weeks
• since 2024-01-01, since v1.2.0
• from 2024-01-01 to 2024-01-31
• v1.0.0..v1.1.0 (between tags)

If no period specified, default to "last week" and confirm with the user.

Step 2: Gather Git History

1. Run git log for the specified period with full commit messages
2. Include merge commits to capture feature branches
3. Gather commit metadata (author, date, files changed)

Example commands:

# Last week
git log --since="1 week ago" --pretty=format:"%h|%s|%b|%an|%ad" --date=short

# Between dates
git log --after="2024-01-01" --before="2024-01-31" --pretty=format:"%h|%s|%b|%an|%ad" --date=short

# Between tags
git log v1.0.0..v1.1.0 --pretty=format:"%h|%s|%b|%an|%ad" --date=short

Step 3: Analyze and Categorize Changes

Group commits into business-friendly categories:

| Category | Emoji | Keywords to detect | |----------|-------|-------------------| | New Features | 🚀 | feat, add, implement, introduce | | Improvements | 💪 | improve, enhance, update, optimize | | Bug Fixes | 🐛 | fix, resolve, repair, correct | | Security | 🔒 | security, vulnerability, CVE | | Performance | ⚡ | perf, performance, speed, optimize | | Breaking Changes | ⚠️ | breaking, BREAKING CHANGE | | Deprecations | 📦 | deprecate, deprecated |

Transformation rules:

1. Remove technical jargon (PR numbers, file paths, function names)
2. Convert developer language to user-facing benefits
3. Combine related commits into single entries
4. Focus on WHAT changed for users, not HOW it was implemented

Step 4: Generate the Changelog

Create output in this format:

# 📋 Changelog

**Period:** [Start Date] → [End Date]

---

## ✨ Highlights

> [2-3 sentence summary of the most important changes. Make it sound exciting and valuable!]

---

## 🚀 New Features

- **[Feature Name]** — [Brief description of what users can now do]
- **[Feature Name]** — [Brief description of what users can now do]

## 💪 Improvements

- **[Area]** — [What got better and why it matters]
- **[Area]** — [What got better and why it matters]

## 🐛 Bug Fixes

- Fixed an issue where [user-facing problem description]
- Resolved a problem with [user-facing problem description]

## 🔒 Security

- [Description without exposing vulnerability details]

## ⚡ Performance

- [Description of what is now faster/more efficient]

---

📊 **Stats:** [X] changes by [Y] contributors

🙏 **Contributors:** @name1, @name2, @name3

Tone Guidelines

Make the changelog feel alive and engaging:

• Use active voice: "You can now..." instead of "Added ability to..."
• Celebrate wins: "Finally! Dark mode is here"
• Be human: "No more frustrating login errors"
• Add context when helpful: "Based on your feedback, we..."

Step 5: Handle Edge Cases

No commits found:

• Inform user that no changes were found for the period
• Suggest alternative time ranges

Too many commits (>100):

• Warn user about large volume
• Offer to summarize by category or split into multiple sections

Technical-only changes:

• If all changes are internal (refactoring, dependencies, CI/CD):
  • Create a brief "Technical Improvements" section
  • Note that no user-facing changes were made

Step 6: Output Options

Ask user their preferred output:

1. Display - Show the changelog in the conversation
2. File - Save to a file (default: CHANGELOG-[date].md)
3. Clipboard - Copy to clipboard for pasting elsewhere

Writing Guidelines

1. User perspective - Write from the user's point of view

   • ❌ "Refactored auth module to use JWT tokens"
   • ✅ "Your login is now more secure"

2. Benefit-focused - Emphasize the benefit, not the implementation

   • ❌ "Added Redis caching layer"
   • ✅ "Pages load up to 3x faster"

3. Plain language - Avoid technical terms

   • ❌ "Fixed race condition in async handler"
   • ✅ "Fixed a rare issue where data could appear incorrect"

4. Concise - Keep entries to 1-2 sentences max

5. Positive framing - Frame fixes as improvements

   • ❌ "Fixed broken search"
   • ✅ "Search now works reliably"

6. Celebrate big wins - Make important features feel special

   • ❌ "Added dark mode"
   • ✅ "🌙 Dark mode is finally here! Easy on the eyes, day or night"

7. Acknowledge feedback - Show users they're heard

   • ✅ "You asked, we listened — bulk export is now available"

Arguments

• <args> - Time period specification
  • Relative: last week, last 2 weeks, last month
  • Since: since 2024-01-01, since v1.0.0
  • Range: from 2024-01-01 to 2024-01-31
  • Tags: v1.0.0..v1.1.0

Examples:

• changelog last week - Changes from the past 7 days
• changelog since 2024-01-01 - All changes since January 1st
• changelog v2.0.0..v2.1.0 - Changes between two releases