Agent skill

changelog-writer

Generates changelogs and release notes from git commits, PR titles, and issue references. Organizes changes by impact type (breaking, features, fixes, improvements), formats according to Keep a Changelog standard, and provides version tagging and semantic versioning suggestions. Use when users request "create changelog", "write release notes", "document version changes", or "prepare release".

View SKILL.md on GitHub Repository

Stars 23

Forks 2

Install this agent skill to your Project

npx add-skill https://github.com/patricio0312rev/skills/tree/main/foundation/changelog-writer

SKILL.md

Changelog & Release Notes Writer

Generate professional changelogs and release notes from version control history.

Core Workflow

Analyze commits: Parse git history since last release
Categorize changes: Group by type (feat, fix, docs, etc.)
Identify breaking changes: Flag incompatible changes
Extract highlights: Surface most important changes
Format document: Follow Keep a Changelog format
Suggest version: Recommend semantic version bump
Generate release notes: Create user-friendly summary

Commit Analysis

Extract Information From

Commit messages (preferably conventional commits)
PR titles and descriptions
Issue references (#123)
Merge commit messages
Commit authors

Parse Patterns

feat(auth): add OAuth2 support
^    ^      ^
|    |      └─ Description
|    └─ Scope (optional)
└─ Type

Types to Categories:

feat → Added
fix → Fixed
docs → Documentation
style, refactor → Changed
perf → Performance
test → Testing
chore, ci → Internal
BREAKING CHANGE → Breaking Changes

Changelog Format (Keep a Changelog)

markdown

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

- New feature X
- Support for Y

### Changed

- Updated Z behavior

### Fixed

- Resolved issue #123

## [2.1.0] - 2024-01-15

### Added

- OAuth2 authentication support
- User profile management API
- Dark mode toggle

### Changed

- Improved error messages
- Updated dependencies to latest versions

### Deprecated

- Legacy authentication method (will be removed in 3.0.0)

### Fixed

- Memory leak in WebSocket connection
- Incorrect date formatting in reports
- Race condition in concurrent requests

### Security

- Patched XSS vulnerability in user input

## [2.0.0] - 2023-12-01

### Breaking Changes

- ⚠️ Removed support for Node.js 16
- ⚠️ Changed API response format for `/users` endpoint
- ⚠️ Renamed `config.yaml` to `config.yml`

### Added

- Complete API rewrite with improved performance
- WebSocket support for real-time updates

### Migration Guide

See [MIGRATION_v2.md](./docs/MIGRATION_v2.md) for upgrade instructions.

[unreleased]: https://github.com/user/project/compare/v2.1.0...HEAD
[2.1.0]: https://github.com/user/project/compare/v2.0.0...v2.1.0
[2.0.0]: https://github.com/user/project/releases/tag/v2.0.0

Release Notes Format

markdown

# Release v2.1.0 - "Feature Release Name"

Released: January 15, 2024

## 🎉 Highlights

This release brings major improvements to authentication and user experience:

- **OAuth2 Support**: Users can now sign in with Google, GitHub, and Microsoft
- **Dark Mode**: Toggle between light and dark themes
- **Performance**: 40% faster API response times

## ✨ New Features

- OAuth2 authentication with popular providers (#456)
- User profile management API (#478)
- Dark mode toggle in settings (#492)
- Export data in CSV format (#501)

## 🐛 Bug Fixes

- Fixed memory leak in WebSocket connections (#489)
- Resolved incorrect date formatting in reports (#495)
- Fixed race condition in concurrent API requests (#503)

## 🔄 Changes

- Improved error messages across the application
- Updated all dependencies to latest stable versions
- Refined UI animations for smoother experience

## 🔒 Security

- Patched XSS vulnerability in user input validation
- Updated JWT library to address CVE-2024-1234

## 📚 Documentation

- Added OAuth2 setup guide
- Updated API reference with new endpoints
- Improved troubleshooting section

## 🙏 Contributors

Thank you to all contributors who made this release possible:

- @alice - OAuth2 implementation
- @bob - Dark mode feature
- @charlie - Bug fixes and testing

## 📦 Installation

```bash
npm install project-name@2.1.0
# or
yarn add project-name@2.1.0
```

🔗 Links

Full Changelog
Documentation
Migration Guide

Note: This is a minor release. No breaking changes. Safe to upgrade from 2.0.x.


## Semantic Versioning Rules

Given a version number MAJOR.MINOR.PATCH (e.g., 2.1.0):

1. **MAJOR** (2.x.x → 3.x.x)
   - Breaking changes
   - Incompatible API changes
   - Removed features

2. **MINOR** (2.1.x → 2.2.x)
   - New features
   - Backward-compatible functionality
   - Deprecated features

3. **PATCH** (2.1.0 → 2.1.1)
   - Bug fixes
   - Security patches
   - Performance improvements

**Special versions:**
- `0.x.x` - Initial development (breaking changes allowed in minor)
- `x.y.0-alpha.1` - Pre-release
- `x.y.0-beta.2` - Beta release
- `x.y.0-rc.1` - Release candidate

## Git Commands for Changelog Generation

```bash
# 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 with PR numbers
git log --merges --pretty=format:"%s" v2.0.0..HEAD

# Get contributors
git log v2.0.0..HEAD --format='%aN' | sort -u

# Get commit count by type
git log v2.0.0..HEAD --oneline | grep -E '^[a-f0-9]+ (feat|fix|docs)' | cut -d' ' -f2 | sort | uniq -c

Breaking Changes Detection

Look for these indicators:

Commit message contains BREAKING CHANGE:
Commit type has ! (e.g., feat!:)
PR labeled with "breaking-change"
Major dependency updates
API endpoint changes
Config file format changes

Document clearly:

markdown

### Breaking Changes

⚠️ **API Response Format Changed**

The `/api/users` endpoint now returns:

```json
// Before
{ "data": [...] }

// After
{ "users": [...], "total": 100 }
```

Migration: Update your API client to access users instead of data.


## Automation Tools

### Using conventional-changelog
```bash
npm install -g conventional-changelog-cli

# Generate changelog
conventional-changelog -p angular -i CHANGELOG.md -s

# Generate for specific version
conventional-changelog -p angular -i CHANGELOG.md -s -r 0

Using git-cliff

bash

# Install git-cliff
cargo install git-cliff

# Generate changelog
git-cliff --tag v2.1.0 > CHANGELOG.md

# Generate release notes
git-cliff --tag v2.1.0 --unreleased

GitHub Release Script

bash

#!/bin/bash
# scripts/release.sh

VERSION=$1
PREVIOUS_TAG=$(git describe --tags --abbrev=0)

# Generate release notes
gh release create "$VERSION" \
  --title "Release $VERSION" \
  --notes "$(git log $PREVIOUS_TAG..HEAD --pretty=format:'- %s')"

User-Facing vs Developer-Facing

User-Facing (Release Notes)

Focus on benefits and features
Less technical jargon
Include screenshots/demos
Highlight user experience improvements
Provide upgrade instructions

Developer-Facing (Changelog)

Technical details
API changes
Breaking changes with migration guides
Dependencies updates
Internal refactorings

Templates by Project Type

Library/Package

Focus on: API changes, breaking changes, new methods

Application

Focus on: New features, bug fixes, UI improvements

CLI Tool

Focus on: New commands, flag changes, behavior changes

API Service

Focus on: Endpoint changes, performance, security

Best Practices

Be specific: "Fixed login bug" → "Fixed session timeout on mobile"
Link issues: Reference GitHub issues (#123)
Credit contributors: Acknowledge work
Highlight impact: Mark breaking changes clearly
Group logically: By type, not chronologically
Update regularly: With each release
Follow conventions: Keep a Changelog format
Semantic versioning: Use correctly

Changelog Entry Examples

Good Examples

markdown

### Added

- OAuth2 authentication support (#456) - @alice
- Export data in CSV format with custom column selection (#501)

### Fixed

- Resolved memory leak in WebSocket connections affecting long-running sessions (#489)
- Fixed race condition in concurrent API requests that caused data inconsistency (#503)

Bad Examples

markdown

### Added

- Added stuff
- New feature

### Fixed

- Fixed bug
- Updates

Version Suggestion Algorithm

If breaking changes detected:
  MAJOR++, MINOR=0, PATCH=0
Else if new features:
  MINOR++, PATCH=0
Else if only fixes:
  PATCH++

Release Checklist

Before publishing release:

Review all commits since last release
Identify breaking changes
Categorize changes properly
Update CHANGELOG.md
Write release notes
Update version in package.json/pyproject.toml
Create git tag
Push tag to trigger CI/CD
Publish to package registry (npm, PyPI, etc.)
Create GitHub release with notes
Announce on relevant channels

Output Checklist

Every changelog generation should provide:

Formatted CHANGELOG.md following Keep a Changelog
Release notes draft (user-friendly)
Semantic version suggestion (X.Y.Z)
Breaking changes clearly marked
Migration guide for breaking changes
Git tag command to run
Links to compare view

Maintainer

patricio0312rev Core maintainer

Source details

Full Name: patricio0312rev/skills
Branch: main
Path in repo: foundation/changelog-writer
License: MIT License
Topics: ai claude-code claude cursor skills copilot-coding-agent cursor-ai

Featured Tools

Join Our Newsletter

Stay updated with the latest AI tools, news, and offers by subscribing to our weekly newsletter.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

patricio0312rev/skills

rate-limiting-abuse-protection

Implements rate limiting and abuse prevention with per-route policies, IP/user-based limits, sliding windows, safe error responses, and observability. Use when adding "rate limiting", "API protection", "abuse prevention", or "DDoS protection".

23 2

Explore

patricio0312rev/skills

rbac-permissions-builder

Implements role-based access control with permission matrix, route guards, policy functions, and UI permission hints. Provides middleware/guards, helper utilities, test suggestions, and permission checking patterns. Use when building "RBAC", "permissions", "access control", or "authorization".

23 2

Explore

patricio0312rev/skills

websocket-realtime-builder

Implements real-time features using WebSockets with Socket.io, rooms, authentication, and reconnection handling. Use when users request "real-time updates", "WebSocket", "Socket.io", "live chat", or "push notifications".

23 2

Explore

patricio0312rev/skills

webhook-receiver-hardener

Secures webhook receivers with signature verification, retry handling, deduplication, idempotency keys, and error responses. Provides verification code, dedupe storage strategy, runbook for incidents. Use when implementing "webhooks", "webhook security", "event receivers", or "third-party integrations".

23 2

Explore

patricio0312rev/skills

auth-module-builder

Implements secure authentication patterns including login/registration, session management, JWT tokens, password hashing, cookie settings, and CSRF protection. Provides auth routes, middleware, security configurations, and threat model documentation. Use when building "authentication", "login system", "JWT auth", or "session management".

23 2

Explore

patricio0312rev/skills

rest-to-graphql-migrator

Migrates REST APIs to GraphQL incrementally with schema stitching, REST datasources, and gradual endpoint migration. Use when users request "migrate to GraphQL", "REST to GraphQL", "GraphQL wrapper", or "API modernization".

23 2

Explore

Didn't find tool you were looking for?

Search AI Tools

Install this agent skill to your Project

SKILL.md

Changelog & Release Notes Writer

Core Workflow

Commit Analysis

Extract Information From

Parse Patterns

Changelog Format (Keep a Changelog)

Release Notes Format

🔗 Links

Breaking Changes Detection

Using git-cliff

GitHub Release Script

User-Facing vs Developer-Facing

User-Facing (Release Notes)

Developer-Facing (Changelog)

Templates by Project Type

Library/Package

Application

CLI Tool

API Service

Best Practices

Changelog Entry Examples

Good Examples

Bad Examples

Version Suggestion Algorithm

Release Checklist

Output Checklist

Recommended Agent Skills

rate-limiting-abuse-protection

rbac-permissions-builder

websocket-realtime-builder

webhook-receiver-hardener

auth-module-builder

rest-to-graphql-migrator