---
name: keep-a-changelog-format
source: https://app.decimal.ai/s/keep-a-changelog-format@1/SKILL.md
source_sha256: 31e7d055243c
---

# Keep a Changelog format

## Contract

When producing a CHANGELOG file or release notes, label and order every entry with
the exact Keep a Changelog vocabulary and layout below. Apply this whenever the task
is "write/update a changelog", "draft release notes", or "turn these commits into a
changelog" — even if the user doesn't name the format.

## Rules

### The six section headings (exact words, exact order)

Group entries under these SIX headings only, spelled EXACTLY like this, as level-3
`###` headings, in THIS order. Omit a heading when it has no entries — never reorder,
never rename, never invent a seventh:

1. `### Added` — new features and capabilities. NOT "Features", "New Features", "New",
   "Additions".
2. `### Changed` — changes to existing behavior, including performance work, tuning,
   renames, and refactors. NOT "Updated", "Improvements", "Enhancements", "Changes",
   "Performance", "Renamed".
3. `### Deprecated` — features still present but marked for future removal. NOT
   "Deprecations", "Obsolete".
4. `### Removed` — features deleted in THIS release. NOT "Deletions", "Dropped",
   "Deleted", "Breaking".
5. `### Fixed` — bug fixes. NOT "Bug Fixes", "Fixes", "Bugfixes", "Patches".
6. `### Security` — vulnerability fixes and security hardening. NOT "Security Fixes",
   "Vulnerabilities". Never fold a security issue under `Fixed`.

Each entry is a Markdown list item (`- ...`) under its heading.

### Layout

- Start the file with a `# Changelog` title (level-1). An intro line is optional.
- Put a `## [Unreleased]` section at the very top, above every released version, for
  merged-but-unshipped work. When the user gives no version/date, everything goes here.
- Write each released version header as `## [X.Y.Z] - YYYY-MM-DD`: the version in
  square brackets, then a space, a hyphen, a space, then an ISO 8601 date.
- List released versions in reverse-chronological order — newest version first, oldest
  last. When inserting a new release, place it above all existing ones.
- Mark a pulled/retracted release by appending ` [YANKED]` to its version header:
  `## [1.5.0] - 2026-11-20 [YANKED]`.

### Date normalization

Convert every date to ISO 8601 `YYYY-MM-DD`. This includes spelled-out, slashed,
day-first, and ordinal dates:

- "June 26, 2026" → `2026-06-26`
- "06/26/2026" and "2026/06/26" → `2026-06-26`
- "7 Feb 2026" and "Aug 2, 2026" → `2026-02-07`, `2026-08-02`
- "the thirty-first of January 2026" / "October 5th, 2026" → `2026-01-31`, `2026-10-05`

### Conventional-commit mapping

When the input is commit messages (`feat:`, `fix:`, `perf:` …), map type → section:

| Commit type        | Section       |
|--------------------|---------------|
| `feat`             | Added         |
| `fix`              | Fixed         |
| `perf`, `refactor` | Changed       |
| `revert`           | Removed       |
| `docs`, `style`, `test`, `chore`, `ci`, `build` | omit (not user-facing) |

A security-relevant `fix` still goes under `Security`, not `Fixed`.

## Worked examples

### Added (not "Features")
BEFORE:
```
### Features
- OAuth login
```
AFTER:
```
### Added
- OAuth login
```

### Changed — performance counts as Changed (not "Improvements"/"Performance")
BEFORE:
```
### Performance Improvements
- Search index is 3x faster
```
AFTER:
```
### Changed
- Search index is 3x faster
```

### Deprecated (not "Deprecations")
BEFORE:
```
### Deprecations
- v1 REST endpoints (removal next year)
```
AFTER:
```
### Deprecated
- v1 REST endpoints (removal next year)
```

### Removed (not "Dropped"/"Deletions")
BEFORE:
```
### Dropped
- Legacy XML parser
```
AFTER:
```
### Removed
- Legacy XML parser
```

### Fixed (not "Bug Fixes")
BEFORE:
```
### Bug Fixes
- Crash on logout
```
AFTER:
```
### Fixed
- Crash on logout
```

### Security — never fold under Fixed
BEFORE:
```
### Fixed
- SQL injection in the report builder
- Off-by-one in pagination
```
AFTER:
```
### Security
- SQL injection in the report builder

### Fixed
- Off-by-one in pagination
```

### Version header + ISO date
BEFORE:
```
## 2.1.0 (June 26, 2026)
```
AFTER:
```
## [2.1.0] - 2026-06-26
```

### Reverse-chronological order
BEFORE (oldest first):
```
## [1.0.0] - 2026-01-01
## [1.1.0] - 2026-06-01
```
AFTER (newest first):
```
## [1.1.0] - 2026-06-01
## [1.0.0] - 2026-01-01
```

### Unreleased bucket
BEFORE:
```
## [0.0.0] - TBD
### Added
- Dark-mode toggle
```
AFTER:
```
## [Unreleased]
### Added
- Dark-mode toggle
```

### YANKED release
BEFORE:
```
## [1.5.0] - 2026-11-20 (pulled — data-loss bug)
```
AFTER:
```
## [1.5.0] - 2026-11-20 [YANKED]
```

## Edge cases & exceptions

- **No version or date yet** → put the work under `## [Unreleased]`. Do not invent a
  version number or a date.
- **A "fix" that closes a vulnerability** → `Security`, not `Fixed`. Security wins.
- **A rename** (e.g. "Projects" → "Workspaces") → `Changed`, not a new "Renamed"
  heading.
- **Performance / refactor work** → `Changed`. There is no "Performance" heading.
- **A brand-new project's first release** → still opens with `# Changelog`; pre-1.0
  work with no version goes under `## [Unreleased]`.
- **Empty section** → omit it entirely; don't emit `### Removed` with nothing under it.
- **Brackets are mandatory** on both `[Unreleased]` and every `[X.Y.Z]` — even the
  first release.

## Do / Don't

- Always write `### Added`; never `### Features` or `### New Features`.
- Always write `### Fixed`; never `### Bug Fixes`.
- Always write `### Changed` for perf/refactor/rename; never `### Improvements` or
  `### Performance`.
- Always put security under `### Security`; never fold it into `### Fixed`.
- Always wrap the version in square brackets: `## [2.1.0] - ...`; never bare `## 2.1.0`.
- Always render the date as `YYYY-MM-DD`; never leave "June 26, 2026" or "06/26/2026".
- Always list newest version first; never oldest-first.
- Always mark a pulled release `[YANKED]`; never silently delete it.

## Common mistakes (the base's wrong defaults)

- Reaching for GitHub's auto-generated "Features / Bug Fixes / Performance
  Improvements" headings instead of the six canonical ones.
- Folding security fixes into `Fixed`.
- Writing the version header as `## 2.1.0` or `## v2.1.0` without brackets.
- Leaving prose dates ("June 26, 2026") instead of ISO `2026-06-26`.
- Listing versions oldest-first, or appending a new release at the bottom.
- Inventing a placeholder version/date instead of using `[Unreleased]`.
- Creating ad-hoc headings like "Renamed", "Deprecations", or "Dropped".

## Quick checklist

- [ ] Headings are exactly Added / Changed / Deprecated / Removed / Fixed / Security.
- [ ] Headings appear in that canonical order; empty ones omitted.
- [ ] File opens with `# Changelog`; `## [Unreleased]` sits on top.
- [ ] Each version header is `## [X.Y.Z] - YYYY-MM-DD` with brackets.
- [ ] Every date is ISO 8601.
- [ ] Versions are newest-first.
- [ ] Security separate from Fixed; pulled releases marked `[YANKED]`.