mcpField
K
keep-a-changelog

keep-a-changelog

github.com/morzecrewDevelopment160 installsUpdated 11w ago
Repository

About keep-a-changelog

A changelog-maintenance skill that helps agents update `## [Unreleased]` and prepare version sections when requested. It applies repository-specific rules and separates user-facing changes from internal work; a validator checks formatting but does not edit.

Key features

  1. 01Maintains the Unreleased section
  2. 02Prepares version sections on request
  3. 03Applies repository-specific changelog rules
  4. 04Identifies consumer-relevant changes
  5. 05Validates changelog mechanics without editing

Use cases

  1. 01Record a user-visible behavior change
  2. 02Check a changelog against house rules
  3. 03Prepare a version section when explicitly requested

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/morzecrew/agent-skills --skill keep-a-changelog

After installing, type/keep-a-changelogin Claude Code to confirm it loaded.

Bundled filesreferences/spec-and-workflows.mdscripts/validate_changelog.py

Details

From the project README

Keep a Changelog Assistant

Changelogs are for humans. A good one lets a reader answer "what does upgrading do to me?" without reading a diff. The agent maintains ## [Unreleased] and, when explicitly asked, prepares version sections; the human decides when to cut, tag and publish.

Format, categories, breaking changes, reverts, yanked releases, entry style, this repository's house rules, and both workflows are in references/spec-and-workflows.md — load it before editing the file. scripts/validate_changelog.py enforces the mechanical half of it:

python3 skills/keep-a-changelog/scripts/validate_changelog.py CHANGELOG.md
python3 skills/keep-a-changelog/scripts/validate_changelog.py --house-rules CHANGELOG.md

It never edits. What it cannot judge is the whole of what follows.

Which changes earn an entry

Only changes meaningful to consumers. The test: does this affect how users install, import, use, or should trust the software? If not, leave it out — even when it was the largest thing in the release.

Typically in: public API changes, new or changed behavior, packaging and installation changes, deprecations, security fixes.

Typically out: test changes, CI and workflow updates, internal tooling, docs-only changes, formatting and lint-only changes, refactors with no observable impact, trivial renames.

Read the product-code boundary from the repository's own layout — wherever the shipped code lives (src/, cmd/ plus internal/, lib/, a package directory) — and treat user-relevant as changes inside it: public APIs and commands, domain primitives, contracts and schemas, behaviors, plus packaging. Never carry one layout's boundary into another repository.

Two judgements the validator will never make for you:

  • Which category a change dominantly belongs to when it fits two. A rewrite that also fixes a bug is Changed if the rewrite is the story and Fixed if the fix is; putting it in both makes the release look twice as large as it was.
  • Whether an entry is true and outcome-shaped. A well-formed entry that describes the implementation instead of the effect passes every check and still fails the reader.

Every commit marked breaking (💥 / ! / a BREAKING CHANGE: footer, see gitmoji-conventional) must produce an entry that names the break, and implies MAJOR for the next release.

Related skills

  • gitmoji-conventional — commit messages and PR titles; its breaking-change markers are the signal that an entry must call out a break. Absent it, read the same signal off the diff: a removed or altered public symbol is a break whatever the commit subject says.

Comments

Markdown supported