---

name: changelog-guide description: | Write and maintain CHANGELOG.md following Keep a Changelog format. Use when: creating changelog entries, preparing releases, documenting changes. Keywords: changelog, release notes, CHANGELOG.md, keep a changelog, 變更日誌, 發布說明.

Changelog Guide

Language: English | 繁體中文

Version: 1.0.0 Last Updated: 2025-12-30 Applicability: Claude Code Skills

---

Purpose

This skill helps write and maintain CHANGELOG.md files following the Keep a Changelog format, ensuring clear communication of changes to users.

Quick Reference

File Structure

Copy# Changelog

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

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

## [Unreleased]

## [1.2.0] - 2025-12-15

### Added
- Feature description

### Changed
- Change description

### Fixed
- Bug fix description

[Unreleased]: https://github.com/user/repo/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/user/repo/compare/v1.1.0...v1.2.0

Change Categories

Commit Type to Changelog Mapping

Entry Format

Standard Format

Copy- [Action verb] [what changed] ([reference])

Examples

Copy### Added
- Add user dashboard with customizable widgets (#123)
- Add support for PostgreSQL 15 (PR #456)

### Changed
- **BREAKING**: Change API response format from XML to JSON (#789)
- Update minimum Node.js version to 18.0 (#101)

### Fixed
- Fix memory leak when processing large files (#112)
- Fix incorrect date formatting in reports (#134)

### Security
- Fix SQL injection vulnerability in search endpoint (HIGH, CVE-2025-12345)

Detailed Guidelines

For complete standards, see:

• Changelog Standards

AI-Optimized Format (Token-Efficient)

For AI assistants, use the YAML format files for reduced token usage:

• Base standard: ai/standards/changelog.ai.yaml

Writing Guidelines

Write for Users, Not Developers

Breaking Changes

Always mark breaking changes clearly:

Copy### Changed
- **BREAKING**: Remove deprecated `getUserById()` method, use `getUser()` instead
- **BREAKING**: Change configuration file format from YAML to TOML

### Removed
- **BREAKING**: Remove support for Node.js 14

Security Advisories

Include severity and CVE if available:

Copy### Security
- Fix SQL injection vulnerability in search endpoint (HIGH, CVE-2025-12345)
- Fix XSS vulnerability in comment rendering (MEDIUM)
- Update dependency `lodash` to patch prototype pollution (LOW)

Version Header Format

Copy## [VERSION] - YYYY-MM-DD

Examples:

Copy## [2.0.0] - 2025-12-15
## [1.5.0-beta.1] - 2025-12-01
## [Unreleased]

Exclusion Rules

The following should NOT be recorded in CHANGELOG:

Common Mistakes

---

Configuration Detection

This skill supports project-specific configuration.

Detection Order

1. Check for existing CHANGELOG.md format
2. Check CONTRIBUTING.md for changelog guidelines
3. If not found, default to Keep a Changelog format

First-Time Setup

If no CHANGELOG.md exists:

1. Suggest creating one with the standard template
2. Suggest documenting guidelines in CONTRIBUTING.md:

Copy## Changelog Guidelines

- Update CHANGELOG.md for all user-facing changes
- Add entries to [Unreleased] section during development
- Use standard categories: Added, Changed, Deprecated, Removed, Fixed, Security
- Reference issue/PR numbers: `Fix bug (#123)`
- Mark breaking changes with **BREAKING** prefix

---

Related Standards

• Changelog Standards
• Versioning Standard
• Commit Message Guide
• Release Standards Skill

---

Version History

---

License

This skill is released under CC BY 4.0.

Source: universal-dev-standards