Changelog Writing

Write changelogs for humans, not machines. Follow the Keep a Changelog convention.

Format Rules

File: CHANGELOG.md at project root
Date format: ISO 8601 (YYYY-MM-DD)
Latest version first (reverse chronological)
One entry per version, every version documented
Follow Semantic Versioning
Version headings are linkable (comparison URLs at bottom)

Change Categories

Group changes under these headings, in this order:

| Category | Use for | | ------------ | ---------------------------------- | | Added | New features | | Changed | Changes to existing functionality | | Deprecated | Features marked for future removal | | Removed | Features removed in this release | | Fixed | Bug fixes | | Security | Vulnerability patches |

Omit empty categories. Never invent new category names.

Unreleased Section

Always keep an ## [Unreleased] section at the top:

## [Unreleased]

### Added

- New user profile endpoint.

At release time, move Unreleased entries into a new versioned heading.

Version Heading Format

## [1.2.0] - 2025-08-15

Yanked releases append [YANKED]:

## [1.1.0] - 2025-07-01 [YANKED]

Comparison Links

At the bottom of the file, define diff links for every version:

[Unreleased]: https://github.com/org/repo/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/org/repo/compare/v1.1.0...v1.2.0
[1.1.0]: https://github.com/org/repo/releases/tag/v1.1.0

Anti-Patterns

| Don't | Why | | -------------------------- | ------------------------------------------- | | Dump git log as changelog | Noise: merge commits, docs changes, typos | | Skip deprecation notices | Users can't prepare for breaking changes | | Use regional date formats | Ambiguous (01/02/03). Use ISO 8601 | | Document only some changes | Partial changelog is worse than none | | Use GitHub Releases alone | Non-portable, less discoverable than a file |

Writing Style

Write entries as imperative statements from the user's perspective
Focus on what changed for the user, not implementation details
Be specific: "Add dark mode toggle in settings" not "Update UI"
Group related changes into a single entry when appropriate

Reading Order

| Task | Files to Read | | -------------------- | ----------------------- | | Create new CHANGELOG | SKILL.md + example.md | | Add release entries | SKILL.md (categories) | | Review format | SKILL.md (format rules) | | See full example | example.md |

In This Reference

| File | Purpose | | ----------------------------------- | -------------------------- | | example.md | Complete example changelog |