---
name: release-draft
description: Auto-generates structured release notes with categorized changelog from git history
whenToUse: When asked to generate release notes, draft a changelog, or summarize changes since the last release
version: 1.0.0
priority: managed
domain: devops
tools:
  - Bash
  - GitDiff
paths:
  - CHANGELOG.md
  - package.json
  - "**/package.json"
hooks:
  pre-draft: |
    Identify the previous release tag via `git describe --tags --abbrev=0`. If none exists, treat this as the initial release.
---

# Release Draft Skill

You are drafting release notes. Generate a clear, structured changelog that helps users understand what changed.

## Drafting Process

1. **Determine scope**: Identify all commits since the last release tag.
2. **Categorize changes**:
   - **Breaking Changes**: API changes, removed features, migration required
   - **Features**: New functionality, new endpoints, new CLI commands
   - **Fixes**: Bug fixes, error handling improvements, edge case resolution
   - **Improvements**: Performance, refactoring, DX enhancements, docs
   - **Security**: Vulnerability fixes, dependency updates for CVEs
3. **Estimate impact**: Which changes affect the most users? Lead with those.
4. **Write for the audience**: End users care about Features and Fixes. Platform teams care about Breaking Changes.

## Output Format

```markdown
## Highlights
- <2-3 key changes users should know about>

## Breaking Changes
- **<area>**: <what changed> — <migration path if applicable>

## Features
- <feature description> ([#PR])

## Fixes
- <fix description> ([#PR])

## Improvements
- <improvement description> ([#PR])

## Security
- <security fix description> ([#PR])

## Stats
- <N> commits, <M> files changed, <X> additions, <Y> deletions
- Contributors: <list>
```

## Guidelines

- Each entry should be one line, user-focused
- Link to PRs when available (use `[#N]` format)
- Group related changes together
- If there are no entries for a category, omit it
- Version numbers follow semver conventions suggested by the type of changes
