# Git:changelog

> Generate Changelog - analyzes git history and creates a human-readable changelog for non-technical teams

- Skill: `ikatsuba/git-changelog` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ikatsuba/git-changelog`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ikatsuba/git-changelog/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: IKatsuba (https://skillmd.com/u/ikatsuba)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/ikatsuba/git-changelog

---


# Generate Changelog

Analyzes git history for a specified time period and generates a human-readable changelog for non-technical teams. 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 `$ARGUMENTS` (`$0`) 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:
```bash
# 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 | 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:

```markdown
# Changelog

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

---

## Highlights

> [2-3 sentence summary of the most important changes]

---

## 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
   - Bad:"Refactored auth module to use JWT tokens"
   - Good:"Your login is now more secure"

2. **Benefit-focused** - Emphasize the benefit, not the implementation
   - Bad:"Added Redis caching layer"
   - Good:"Pages load up to 3x faster"

3. **Plain language** - Avoid technical terms
   - Bad:"Fixed race condition in async handler"
   - Good:"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
   - Bad:"Fixed broken search"
   - Good:"Search now works reliably"

6. **Celebrate big wins** - Make important features feel special
   - Bad:"Added dark mode"
   - "Dark mode is finally here! Easy on the eyes, day or night"

7. **Acknowledge feedback** - Show users they're heard
   - Good:"You asked, we listened — bulk export is now available"

## Arguments

- `$ARGUMENTS` (`$0`) - 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:
- `git:changelog last week` - Changes from the past 7 days
- `git:changelog since 2024-01-01` - All changes since January 1st
- `git:changelog v2.0.0..v2.1.0` - Changes between two releases