Skip to main content
skill CX Codex

changelog · itechmeat — Claude Code skill: CHANGELOG.md in Keep a Changelog format

Keeps CHANGELOG.md on the Keep a Changelog 1.1.0 spec: six change types, version headers, ISO dates, comparison links at the bottom.

MIT 192 installs ★ 23 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add itechmeat/llm-code --skill changelog -a claude-code
Open on GitHub

What changelog does

The skill spells out the rules an agent follows when it creates or edits CHANGELOG.md. Entries go into one of six sections: Added, Changed, Deprecated, Removed, Fixed, Security. A release gets a ## [X.Y.Z] - YYYY-MM-DD header, dates stay ISO 8601, and compare links close the file.

It also names the habits that wreck a changelog: pasting git log output, writing 01/02/2024, dropping deprecation notices, keeping section headers with nothing under them. Each entry opens with a verb, points at the affected component and carries an issue reference like (#123) where one exists. A mapping table links Conventional Commits to sections, feat: to Added and fix: to Fixed, and points at conventional-changelog, semantic-release and release-please for generation.

One rule bites teams that write in another language: every entry must be English, so a Russian draft gets translated first. The filename is fixed too — uppercase CHANGELOG.md, nothing else.

What it helps with

  • Start a CHANGELOG.md from scratch that follows the spec
  • Sort a release's changes into the six section types
  • Stamp versions and ISO dates without regional-format mixups
  • Mark a pulled release as [YANKED]
  • Map Conventional Commits onto changelog sections

Example prompts for the agent

  • Update CHANGELOG.md from the diff since the last tag; new features go under Added.
  • Cut release 1.2.0: add the ## [1.2.0] - 2024-01-20 header and the compare links at the end of the file.
  • Rewrite the entries in CHANGELOG.md in English and switch the dates to ISO 8601.

How to install changelog

1Skills CLI (Vercel)

npx skills add itechmeat/llm-code --skill changelog -a claude-code

2Manually: put the files in place

~/.claude/skills/changelog/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/changelog/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about changelog

How do I install changelog in Claude Code?

Run npx skills add itechmeat/llm-code --skill changelog -a claude-code. The skill then sits at ~/.claude/skills/changelog/SKILL.md.

What does the changelog skill do?

It hands the agent a written format spec for CHANGELOG.md: section types, version header shape, ISO 8601 dates, compare links, plus rules for a readable entry.

Does it work with Conventional Commits?

Yes. A mapping table sends feat: to Added and fix: to Fixed, and the skill names conventional-changelog, semantic-release and release-please as tools that can build the file from commits.

Source text

SKILL.md · MIT
---
name: changelog
description: "Keep a Changelog format. Covers structure, change types, versioning. Use when creating or updating CHANGELOG.md files following the Keep a Changelog specification, or applying semver-compatible changelog conventions. Keywords: CHANGELOG.md, semver, Keep a Changelog."
metadata:
  version: "1.1.0"
  release_date: "2023-03-06"
---

# Changelog

Format specification for CHANGELOG.md based on Keep a Changelog 1.1.0.

## Language Requirement (Mandatory)

- All changelog content MUST be written in English.
- If source information is provided in another language, translate it to English.
- Do not mix languages within the same changelog.

## Quick Reference

### File Header

```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.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
```

### Section Structure

```markdown
## [Unreleased]

### Added

- New feature description

## [1.0.0] - 2024-01-15

### Added

- Feature A
- Feature B

### Changed

- Modified behavior X

### Fixed

- Bug fix Y
```

## Types of Changes

| Type         | Purpose                           |
| ------------ | --------------------------------- |
| `Added`      | New features                      |
| `Changed`    | Changes in existing functionality |
| `Deprecated` | Soon-to-be removed features       |
| `Removed`    | Now removed features              |
| `Fixed`      | Bug fixes                         |
| `Security`   | Vulnerabilities                   |

## Format Rules

### Version Header

```markdown
## [X.Y.Z] - YYYY-MM-DD
```

- Version in brackets, linked to comparison
- Date in ISO 8601 format (YYYY-MM-DD)

### Date-Based Versioning (Alternative)

For projects using date-based versioning instead of semver:

```markdown
## [YYYY-MM-DD]
```

Use current date instead of `[Unreleased]`. This project uses date-based versioning.

### Yanked Releases

```markdown
## [0.0.5] - 2014-12-13 [YANKED]
```

Use when version was pulled due to serious bug or security issue.

### Comparison Links (at file end)

```markdown
[unreleased]: https://github.com/user/repo/compare/v1.0.0...HEAD
[1.0.0]: https://github.com/user/repo/compare/v0.9.0...v1.0.0
[0.9.0]: https://github.com/user/repo/releases/tag/v0.9.0
```

## Guiding Principles

1. **For humans, not machines** — Write clear, readable entries
2. **Entry for every version** — Document all releases
3. **Group same types** — Keep Added/Changed/Fixed together
4. **Linkable versions** — Use comparison links
5. **Latest first** — Reverse chronological order
6. **Show release dates** — Use ISO 8601 format
7. **State versioning scheme** — Mention Semantic Versioning if used

## Complete Example

```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.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

- New authentication method

## [1.2.0] - 2024-01-20

### Added

- User profile page
- Export to CSV functionality

### Changed

- Improved loading performance by 40%

### Deprecated

- Legacy API endpoint `/api/v1/users` (use `/api/v2/users`)

### Fixed

- Login timeout issue on slow connections

## [1.1.0] - 2024-01-10

### Added

- Dark mode support

### Security

- Fixed XSS vulnerability in comment field

## [1.0.0] - 2024-01-01

### Added

- Initial release with core features
- User registration and login
- Dashboard with analytics

[unreleased]: https://github.com/user/project/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/user/project/compare/v1.1.0...v1.2.0
[1.1.0]: https://github.com/user/project/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/user/project/releases/tag/v1.0.0
```

## Bad Practices

### Commit log diffs

**Don't** dump git log into changelog:

- Full of noise (merge commits, obscure titles)
- Not human-readable
- Mixes important and trivial changes

### Ignoring deprecations

**Don't** skip deprecation notices:

- Users need to know what will break
- Document deprecations before removals
- List breaking changes clearly

### Confusing dates

**Don't** use regional date formats:

- Use ISO 8601: `YYYY-MM-DD`
- Avoids ambiguity (is 01/02/2024 Jan 2 or Feb 1?)

### Inconsistent changes

**Don't** document only some changes:

- Changelog should be single source of truth
- Important changes must be mentioned
- Consistently updated

## Writing Tips

### Good Entry Examples

```markdown
### Added

- OAuth2 authentication with Google and GitHub providers
- Rate limiting for API endpoints (100 req/min)

### Changed

- Database queries now use prepared statements for better security
- Upgraded dependency `lodash` from 4.17.20 to 4.17.21

### Fixed

- Memory leak in WebSocket connection handler
- Race condition in concurrent file uploads
```

### Entry Guidelines

- Review current git changes (diff or changed files list) before drafting; ensure all material changes are covered.
- Start with verb or noun describing the change
- Be specific (mention affected component/endpoint)
- Reference issue/PR numbers when relevant: `(#123)`
- Keep entries concise but informative
- Omit empty sections (do not include a section header if there are no entries for it)

## File Naming

Required: `CHANGELOG.md` (uppercase). Do not use lowercase or alternative names.

Do not use alternative filenames.

## GitHub Releases vs CHANGELOG.md

| Aspect          | GitHub Releases | CHANGELOG.md      |
| --------------- | --------------- | ----------------- |
| Portability     | GitHub-only     | Universal         |
| Discoverability | Less visible    | Standard location |
| Version control | Separate UI     | In repository     |
| Diff links      | Manual setup    | Easy to add       |

GitHub Releases can complement but shouldn't replace CHANGELOG.md.

## Conventional Commits Integration

Changelogs work best with [Conventional Commits](../commits/SKILL.md) format:

| Commit Type       | Changelog Section    |
| ----------------- | -------------------- |
| `feat:`           | Added                |
| `fix:`            | Fixed                |
| `perf:`           | Changed              |
| `refactor:`       | Changed              |
| `docs:`           | (often omitted)      |
| `BREAKING CHANGE` | Highlight in Changed |
| Security fix      | Security             |
| `revert:`         | Removed or Fixed     |

### Automated Generation

Tools that parse Conventional Commits and generate changelogs:

- [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog)
- [semantic-release](https://semantic-release.gitbook.io/)
- [release-please](https://github.com/googleapis/release-please)

See [commits skill](../commits/SKILL.md) for commit message format.

## Workflow Integration

### Unreleased Section Pattern

1. Add changes to `## [Unreleased]` during development
2. At release time, rename to `## [X.Y.Z] - YYYY-MM-DD`
3. Create new empty `## [Unreleased]` section
4. Add comparison link for new version

### Pre-commit Checklist

Before release:

- [ ] All notable changes documented
- [ ] Unreleased section moved to version
- [ ] Date added in ISO 8601 format
- [ ] Comparison link added
- [ ] Breaking changes highlighted
- [ ] Deprecations documented

## Critical Prohibitions

- Do not use git log as changelog
- Do not omit breaking changes or deprecations
- Do not use ambiguous date formats
- Do not leave changelog inconsistently updated
- Do not forget to update Unreleased → version at release
- Do not write changelog entries in any language other than English

## README Synchronization

After writing changelog, review the project's main README.md:

1. **Check for outdated information** — features, skills, tools lists
2. **Add new entries** — if changelog introduces new skills, features, or components
3. **Remove deprecated items** — if changelog removes functionality
4. **Update descriptions** — if changelog changes existing functionality

**What to sync:**

- Skills/features tables
- Compatibility lists
- Installation instructions
- Links and references

**What NOT to sync:**

- Changelog content itself (no duplication)
- Version history
- Detailed change descriptions

**Do NOT mention README.md updates in CHANGELOG** — README synchronization is implied and should not be logged as a separate change.

## Links

- Official specification: https://keepachangelog.com/en/1.1.0/
- Semantic Versioning: https://semver.org/spec/v2.0.0.html
- Related: [commits skill](../commits/SKILL.md) — Conventional Commits format

## Templates

- [CHANGELOG.template.md](assets/CHANGELOG.template.md) — Empty template to start
- [CHANGELOG.example.md](assets/CHANGELOG.example.md) — Complete working example

© itechmeat · MIT · itechmeat/llm-code

Similar skills

All skills for Git and GitHub →

changelog by other authors comes first.

changelog Donchitos Turns git commits and sprint records into two changelogs: one internal, one for players. Useful right before a release, when the notes still need writing. CX Codex +1 659installs changelog Remocn changelog gathers changes from git tags, commits, or merged pull requests, writes them as short human-readable updates, and feeds them into a video template. Use it when you need a quick announcement video for a new version. CX Codex +1 462installs changelog Shpigford Drafts customer-facing release notes from merged pull requests and inserts them directly into static site/changelog.html. CX Codex +1 135installs changelog chrisbanes A skill for Claude Code checks changelog entries against Git history and evidence from issues and PRs. It runs when preparing or reviewing release notes. CX Codex +1 159installs changelog pipecat-ai Builds changelog files for meaningful commits in a pull request. CX Codex +1 ★ 17,367repo stars add-to-changelog davila7 add-to-changelog — a Claude Code command that writes entries to CHANGELOG.md following the Keep a Changelog format. Pass the version, change type, and message as arguments. CX Codex +1 277installs changelog-maintenance aj-geddes changelog-maintenance — a skill that gets your agent to write and maintain CHANGELOG.md in Keep a Changelog format, with Added, Changed, Fixed and Security sections. CX Codex +1 503installs changelog-writer patricio0312rev changelog-writer turns git commits, PR titles and issue references into a CHANGELOG and release notes. Useful right before a release, when changes need sorting and a version number. CX Codex +1 631installs changelog-generator Alireza Rezvani changelog-generator is a Claude Code skill that builds release notes from Conventional Commits and recommends a SemVer bump. It runs for release prep, commit checks, and hotfix planning. CX Codex +1 618installs ai-changelog sammcj ai-changelog sets up an AI-maintained CHANGELOG.md workflow across your project. Configures CalVer, SemVer, or simple date-based logging for non-code repositories. CX Codex +1 ★ 173repo stars Changelog Generator claude-office-skills Changelog Generator converts git commits and feature lists into clean release notes. Useful for engineering teams documenting new software versions. CX Codex +1 4,800installs

From the same set16

The whole set →

Project sponsors

Companies that keep this analytics open