Changelog Skill for Claude

/changelog

Updates a release unit's CHANGELOG.md in preparation for tagging it. Ratel releases

per unit (ADR-0008): each unit ships on its own tag (<prefix>-v*) at its own version.

For workflow-wired units, .github/workflows/release.yml rejects a tag whose unit CHANGELOG

doesn't contain the version being released. vercel-ai-sdk is temporarily published

manually via scripts/publish-rc.sh; still run this skill before its tag even though the

workflow gate does not cover it yet.

Run it once per unit you're releasing.

Release units it touches

The units and their manifests/CHANGELOGs live in one registry —

scripts/release-units.mjs — which every release tool reads. Run node scripts/release-units.mjs --list

for the authoritative set; the current eight units are:

| Unit | Registry | CHANGELOG path |

|---|---|---|

| core | ratel-ai-core (crates.io) | src/core/CHANGELOG.md |

| sdk-ts | @ratel-ai/sdk (npm) | src/sdk/ts/CHANGELOG.md |

| sdk-py | ratel-ai (PyPI) | src/sdk/python/CHANGELOG.md |

| telemetry-core | ratel-ai-telemetry (crates.io) | src/telemetry/core/CHANGELOG.md |

| telemetry-ts | @ratel-ai/telemetry (npm) | src/telemetry/ts/CHANGELOG.md |

| telemetry-py | ratel-ai-telemetry (PyPI) | src/telemetry/python/CHANGELOG.md |

| vercel-ai-sdk | @ratel-ai/vercel-ai-sdk (npm) | src/adapters/ts-vercel-ai-sdk/CHANGELOG.md |

| mastra | @ratel-ai/mastra (npm) | src/adapters/ts-mastra/CHANGELOG.md |

@ratel-ai/mcp-server lives in ratel-ai/ratel-mcp and maintains its own CHANGELOG there.

Procedure

1. Pick the unit and read its version

If the user hasn't named the unit, run node scripts/releasable.mjs — it lists which

units have commits since their last release tag. Pick the unit $UNIT being released.

Read its canonical version:

node scripts/release-units.mjs --version "$UNIT"   # -> $TARGET

If the user supplies a different version explicitly, prefer that and warn them the working

tree disagrees.

2. Determine the diff range

The range is from the unit's own last release tag to HEAD:

prefix=$(node scripts/release-units.mjs --tag-prefix "$UNIT")
FROM=$(git describe --tags --match "${prefix}*" --abbrev=0 2>/dev/null || true)

If $FROM is empty the unit has never shipped; the whole history is in range.

3. Generate the draft

bash .claude/skills/changelog/draft.sh --unit "$UNIT"

It emits a single ### <package-name> block for the unit, containing either

Keep-a-Changelog sections (### Added, ### Fixed, ### Changed) or the sentinel

_No user-facing changes._. (Omit --unit to draft every unit at once.) With no

<from-ref> argument the script ranges each unit from its own last tag automatically.

If draft.sh exits 127, git-cliff is missing. Tell the user how to install it (the

script's stderr already does), and stop.

4. Branch on RC vs GA

Inspect $TARGET, and edit only this unit's CHANGELOG:

• RC (X.Y.Z-rc.N): prepend a new section above the most recent versioned section:

  ## [X.Y.Z-rc.N] - YYYY-MM-DD

  <draft content for the unit, or the sentinel>

Use today's date in YYYY-MM-DD (UTC).

• GA (no -rc suffix): enter GA-collapse mode:
• Find every ## [X.Y.Z-rc.*] section already present that matches the same

MAJOR.MINOR.PATCH as $TARGET.

• Union their bullet entries (per subsection: ### Added, ### Changed, ### Fixed)

with the new draft entries from step 3 (commits since the last RC tag).

• Deduplicate bullets within each subsection (case-insensitive, whitespace-normalised).
• Drop the _No user-facing changes._ sentinel if any real entries exist; keep it only

if the unioned set is empty.

• Replace all the matched RC sections with a single ## [X.Y.Z] - YYYY-MM-DD section

containing the merged content.

• Leave non-matching prior versions (e.g. ## [0.1.4]) untouched.

5. Curate with the user

Show the unit's CHANGELOG pending changes in the conversation. Ask the user to confirm or

edit. Common curation moves:

• Rephrase bullets for user-facing clarity (the draft uses commit subjects verbatim).
• Drop bullets that are not user-visible (internal refactors that slipped past

cliff.toml's skip rules).

• Merge duplicates that survived deduplication.
• Promote / demote between Added / Changed / Fixed if the commit prefix was wrong.

6. Write the file

Once approved, write only this unit's CHANGELOG using the Edit tool. Do not commit.

The release commit is the user's responsibility — they typically include the CHANGELOG

alongside the version bump in a single release: <unit>-vX.Y.Z commit.

If releasing more than one unit, repeat from step 1 for each.

7. Remind

Tell the user:

• The CHANGELOG is staged in the working tree (unstaged).
• Next step is the release commit + <unit>-v<version> tag + push.
• For workflow-wired units, the release.yml tag-version-check job verifies the unit's

CHANGELOG contains the tag version; if it doesn't, the release is blocked.

• For vercel-ai-sdk, publish manually with scripts/publish-rc.sh after the tag push; its

CHANGELOG is not workflow-gated yet.

Conventions

• Date format: YYYY-MM-DD in UTC.
• Subsection order: ### Added, ### Changed, ### Fixed, ### Removed, ### Deprecated, ### Security. Omit empty subsections.
• Sentinel: _No user-facing changes._ for a unit with no in-scope commits.
• Keep ## [Unreleased] at the top — it stays empty between releases.

Why this exists

ADR 0008 (docs/adr/0008-release-engineering.md) records the per-unit tag/version split, the

CHANGELOG mechanism, and the rationale. Read it if you're unsure why something is structured

the way it is.