Docs: Changelog

Build or update the changelog from conventional commits and project it to every surface the project uses

SKILL.md

GitHub

Distro: Changelog

One source of truth, projected outward, the same shape as the roadmap system. CHANGELOG.md at the repo root is canonical; GitHub Releases, an in-app what's-new surface and a docs-site page are projections built from it, never written independently. A projection that drifts from the file is a bug.

Scope

The first argument, always optional, always defaulting to root:

Scope Covers Tag series Changelog file
root (default) the whole repo v* CHANGELOG.md
plugin:NAME one plugin's own subtree NAME-v* plugin's own changelog source, or <plugin dir>/CHANGELOG.md
pkg:NAME one release package from .github/release-packages.json the package's prefix (api/v*, say) the package's changelog path

plugin:NAME resolves NAME against .claude-plugin/marketplace.json's plugins[] entries: name gives the tag prefix (NAME-v), source gives the subtree directory (strip a leading ./) that git log and safe-version-next.sh scope to. No matching entry is an error, not a silent fallback to root. This is why the token carries a kind: prefix rather than a bare name: docs is both a target and a real top-level directory here, so slot one has to be unambiguous on sight. A future subtree of some other kind gets its own resolver (dir:, say); the parse rule (root, or anything containing :, is a scope; anything else is a target) never changes.

pkg:NAME resolves NAME against .github/release-packages.json's packages[] entries (the manifest is {"signers": [...], "packages": [{name, dir, prefix, changelog, consumers}]}): dir becomes {scope-dir}, prefix becomes {prefix} verbatim (it already ends in v, as in api/v) and changelog becomes {changelog-path}. No matching entry is an error, not a silent fallback to root. A repo with this manifest is tagged by its own CI, so safe-version-next.sh plays no part in a pkg: run: the series is read straight from git tag --list "{prefix}*" --sort=-v:refname and the next version is whatever CI tagged. Nobody creates or suggests a 1.x tag in a manifest series by hand. Only the repo's Declare Stable workflow, a manual dispatch by a signer listed in the manifest's signers[], moves a package from 0.x to 1.0.0; this skill never proposes one and never writes a [1.0.0] section for a tag that does not already exist.

Where the changelog is written is not always inside {scope-dir}. A hand-maintained plugin (every plugin in this repo) keeps it at <plugin dir>/CHANGELOG.md. A plugin generated by a build script regenerates its subtree wholesale, so a file written there is deleted on the next rebuild; such a script names its changelog source as a constant (CHANGELOG_SOURCE, beside README_SOURCE and VERSION_SOURCE), found by reading the plugin's docs rather than assumed, and that path is {changelog-path}. Root scope has no such indirection: {changelog-path} is always CHANGELOG.md at the repo root.

Every step below runs identically for every scope; only the directory git log and svu/safe-version-next.sh are scoped to ({scope-dir}), the tag prefix they use ({prefix}) and where the changelog file itself is written ({changelog-path}) change. All three are plain prose placeholders, not literal shell variables, filled in from what Step 1 resolves. {scope-dir} and {changelog-path} are the same path for root scope, but diverge for a build-output plugin, where history is scoped to the built subtree while the file itself lives with the plugin's other hand-maintained sources.

Targets

Token Surface Applies when
md CHANGELOG.md, Keep a Changelog layout always; this is the source
release GitHub Release notes per tag (gh release) repo has tags on GitHub
app structured data for an in-app what's-new surface the app has (or wants) one
docs changelog page in the docs site a docs site exists
all every surface that applies to this project

No arguments: build md, then refresh any projection that already exists in the repo (an existing release for the previous tag, an existing changelog data file or docs page). Never scaffold app or docs surfaces unasked; offer when the project looks like it wants one.

Step 1: Establish the range

Parse $ARGUMENTS (whitespace-separated words) into scope, targets and an optional tag, in that order. This is prose parsing, not variable substitution: $ARGUMENTS is the only token the harness fills in; every other placeholder in this skill ({scope-dir}, {changelog-path}, {prefix}, {tag}) is a value this step resolves and later steps refer back to.

  1. Scope (always optional, first word only counts as scope): the literal word root, or any word containing :, is consumed as the scope word and removed from the argument list. Any other first word (md, release, v2.5.0, no arguments at all) means scope defaults to root and that word is left for the next rule to read. root resolves to {scope-dir} = {changelog-path} = . (repo root, and CHANGELOG.md within it) and {prefix} = v. plugin:NAME resolves NAME against .claude-plugin/marketplace.json's plugins[] entries: source (with a leading ./ stripped) becomes {scope-dir}, and {prefix} becomes NAME-v; {changelog-path} is resolved per the Scope section above (the plugin's own build-script constant when one exists, else {scope-dir}/CHANGELOG.md). pkg:NAME resolves NAME against .github/release-packages.json's packages[] entries: dir becomes {scope-dir}, prefix becomes {prefix} and changelog becomes {changelog-path}. For either kind, no matching entry is an error, not a silent fallback to root.
  2. Targets: the next remaining word, if it's one of md/release/app/docs/all; otherwise targets defaults per the Targets section below and that word is left for the next rule.
  3. Tag: whatever word remains, if any; this is the optional version argument scoping the run to one release.
  • (a) No file at {changelog-path} → build fresh from the earliest tag matching {prefix}* (or full history under {scope-dir} if untagged).
  • (b) Placeholder, or already Keep a Changelog-shaped → a <!-- doc-changelog: generated ... --> marker (left as the first line by this skill from now on, mirroring doc-readme's convention) or a file that's already unambiguously in Keep a Changelog structure (a prior unmarked run of this same skill); proceed with the normal forward-generation logic below.
  • (c) Hand-written changelog in some other format/voice → stop and flag it explicitly before writing anything: offer to convert it to Keep a Changelog format, or to respect the existing format and append new entries in its own voice instead. Don't silently Frankenstein a Keep a Changelog section onto a differently-structured hand-written file.

git tag --list "{prefix}*" --sort=-v:refname for existing tags in this scope's series; for root and plugin scopes, ~/.claude/library/scripts/safe-version-next.sh (with --plugin NAME --dir {scope-dir} for a plugin scope) rather than bare svu current/svu next, so the 0.x guard and the plugin's own tag/directory scoping both apply here the same as they do to any other tag this config creates. A pkg: scope skips the script entirely: CI tags that repo, so the tag list is the whole truth and no next version is ever computed here. The unit of work is tag-to-tag within this series: each version section covers previousTag..tag (both {prefix}-matching), and [Unreleased] covers latestTag..HEAD, in both cases limited to commits touching {scope-dir} (-- {scope-dir} on every git log, a no-op for the root scope, where {scope-dir} is .). If the file at {changelog-path} exists (state b), its most recent version heading shows where it stopped: only generate forward from there; never rewrite sections already published.

The resolved tag from Step 1's parse (if any) names a tag in this scope's series: scope the run to that single release (previousTag..{tag}), leaving every other section untouched. This is pr-land's hand-off; it can invoke /doc-changelog root md {tag}, /doc-changelog plugin:NAME md {tag} or /doc-changelog pkg:NAME md {tag} right after tagging, once per tag the landing produced.

Promote, don't regenerate: when a new tag lands and [Unreleased] already carries curated entries, promote that content into the new version section, verify nothing in the tag range is missing (add what is), and rebuild [Unreleased] from newTag..HEAD. Hand-polish survives; only genuinely new material gets derived.

Step 2: Build the canonical entries

For each version in range, read git log --first-parent previousTag..tag --format='%h %s%n%b' -- {scope-dir}: with merge-commit landings this yields one commit per merged PR (plus direct-to-main commits), so each entry derives from a PR-level change rather than branch-internal noise. The -- {scope-dir} limit is what makes a plugin or package scope mean anything: a PR that touches both root config and a plugin (docs plus marketplace/roadmap/** in one PR, say) contributes an entry to both changelogs independently, as does one that touches two packages at once (apps/api and supabase), each changelog reading only the part of that PR's diff under its own scope, each reading only the part of that PR's diff under its own scope. A stacked-PR landing does not preserve this: gh stack merge makes one merge commit for the whole stack, titled for the top PR, so first-parent history shows a single line for every layer (see library/references/stacked-prs.md). When a range contains one, read git log --no-merges previousTag..tag -- {scope-dir} for that landing and write one entry per coherent change, as for any other. Fall back to the full log (still -- {scope-dir}-limited) only when the first-parent output is too thin to describe the release. Map conventional-commit types to Keep a Changelog sections:

Commit type Section
feat Added
fix Fixed
enhance, perf Changed
BREAKING CHANGE footer or ! its own Breaking entry, listed first
refactor, docs, test, chore, ci, deps omitted unless user-visible

Entries describe the change from the user's side ("Exports now include timestamps"), not the commit's ("add timestamp to export serialiser"). Collapse commit-level noise: one entry per coherent change, not per commit. British spelling; no em-dashes.

Step 3: Write {changelog-path}

Keep a Changelog structure: # Changelog intro, ## [Unreleased], then ## [x.y.z] - YYYY-MM-DD sections newest first, comparison links at the bottom when the repo is on GitHub. On a fresh build (state a/b from Step 1), the very first line is the marker comment: <!-- doc-changelog: generated {date}. Delete this line once you hand-edit this file. -->.

Collapsibility for older entries. Once the file holds more than a handful of version sections, wrap everything older than the most recent few in GFM's native <details><summary>: [Unreleased] and the newest 2-3 versions stay always-visible, older ones collapse behind a one-line summary (<summary>0.4.0 and earlier</summary>). No custom chevron needed. Adjusting which sections are wrapped as new versions land is presentational only; it doesn't touch a section's own entries, so it isn't the "rewrite already-published sections" the red flags below warn against.

No badge row and no separate provenance line here: each entry is already dated by construction, which is its own honesty record; a "generated on X" line would just repeat what the file already states more precisely.

Scan the new or changed sections before showing them:

~/.claude/library/scripts/slop-scan.py --strict - <<'SLOP_EOF'
<draft sections>
SLOP_EOF

Non-zero exit: rewrite to clear every L<n> <rule>: <excerpt> line and rescan, at most twice. If hits remain, list them under the draft so the reviewer decides.

Show the draft (or the diff, when updating) and await approval before writing.

npm packages (a package.json with no "private": true): check CHANGELOG.md ships or is reachable: either listed in files or linked from the README, since the npm page shows only the README. Flag whichever is missing; registry users otherwise never see release history.

Step 4: Project

Only after md is approved and written:

  • release: for each new tag (in this scope's {prefix} series), gh release create {tag} --title {tag} --notes-file - fed with that version's section verbatim (gh release edit when the release exists). The Release body is the section, not a rewrite. A plugin's NAME-v* tags and a package's {prefix}* tags get their own GitHub Releases, distinct from the root v* series; several series point at the same commit when one landing bumped them all.
  • app: emit the structured form the app consumes. Root scope only; a plugin or package has no in-app what's-new surface of its own. If none exists yet and the user asked for app, propose the simplest fit for the stack (for SvelteKit: a changelog.json importable by a route) and build it from the same entries.
  • docs: update the docs-site changelog page from the same sections, matching that site's existing format. Root scope only, for the same reason.

Step 5: Report

Versions covered, surfaces written, surfaces skipped and why, plus any npm visibility flag from Step 3.

Red flags

Never: write a projection that disagrees with CHANGELOG.md; rewrite already-published version sections (corrections get an explicit edit, called out to the user); invent user-facing descriptions for changes you don't understand; quote the commit and ask; create or suggest a 1.x tag in a pkg: series (only the repo's Declare Stable workflow, dispatched by a listed signer, does that).

<raw-arguments value="$ARGUMENTS" />