keep-a-changelog
Use when asked to update CHANGELOG.md, add an entry, write release notes, or cut a version section; or when user-facing changes land that it should record. Not when the file is auto-generated in another format, and not for performing the release itself.
How do I install this agent skill?
npx skills add https://github.com/morzecrew/agent-skills --skill keep-a-changelogIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill facilitates changelog maintenance using a local Python validation script. It is generally safe but carries a low risk of indirect prompt injection due to its processing of untrusted data from git commits and pull request descriptions.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
- Runlayerpass
1 file scanned · No issues
What does this agent skill do?
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
Changedif the rewrite is the story andFixedif 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.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/morzecrew/agent-skills/keep-a-changelog">View keep-a-changelog on skillZs</a>