synesenom/ran / .claude/skills/release
release
VerifiedRelease Skill
You are cutting a versioned release of ranjs: bumping the version, updating the changelog, creating and merging a release PR, and handing off to the GitHub Actions release workflow which tags, publishes to npm, cuts the GitHub release, and rotates the milestone.
This skill runs entirely through GitHub MCP tools — it needs neither the
gh CLI nor a local git tag push. Everything the skill cannot do from an
MCP-only environment (create the v* tag, npm publish, cut the GitHub
release, rotate the milestone) is done server-side by
.github/workflows/release.yml, which the skill triggers via
mcp__github__actions_run_trigger. See
decisions/0037-mcp-orchestrated-release.md.
Invocation
/release [version]
Optional version argument — the exact semver to release, e.g. 1.31.0. If
omitted, the version is computed by bumping the minor part of the current
package.json version (1.30.0 → 1.31.0).
Pre-conditions
- GitHub MCP tools available (
mcp__github__*). NPM_TOKENsecret configured in repo Settings → Secrets → Actions (npm publish permission).RELEASE_TOKENsecret configured — a fine-grained PAT owned by a repo admin (repo: this one, Contents: read+write).github-actions[bot]cannot be added to thev*tag-protection ruleset's bypass list, so the workflow uses this PAT (which authenticates as an admin, who is in the bypass list) solely to push the release tag. One-time setup.mainmust be the default branch and there must be no in-flight release PR or existingv{VERSION}tag.
Throughout, use these MCP tools with owner = the repo owner and repo = the
repo name (derive from the remote, e.g. synesenom/ran).
Workflow
1. Pre-flight
mcp__github__list_pull_requests(stateopen) — abort if aRelease v*PR is already open.mcp__github__get_tagforv{VERSION}once VERSION is known — abort if it already exists.mcp__github__list_commitsonmain— note the latest commit; the release PR bases off it.
Abort with a clear message if any check fails.
2. Determine version
Read the current version from package.json (via mcp__github__get_file_contents
on main, or the local checkout if present).
If a version argument was provided, use it as VERSION.
Otherwise, default to a minor bump: X.Y.Z → X.(Y+1).0.
Under the numpy/scipy-style versioning policy, breaking changes ship in
minor releases (behind a deprecation cycle), so a breaking label does
not trigger a major bump. A major bump (X.Y.Z → (X+1).0.0) is reserved
for a rare, sweeping overhaul and is only ever done by passing an explicit
version argument.
Optionally surface breaking-labelled issues closed since the last release via
mcp__github__search_issues so the operator is aware of behavior changes
(informational only — it does not change the bump type).
Compute NEXT_VERSION = X.(Y+1).0 (the milestone the workflow will create).
Print VERSION, the bump type, any breaking issues, and NEXT_VERSION.
3. Show what's in the release
Use mcp__github__list_commits on main since the last release to display the
commit list. If it is empty, warn and ask the operator whether to continue.
4. Create release branch
mcp__github__create_branch — create release/v{VERSION} from main.
5. Update version files
On the release/v{VERSION} branch, edit and stage (do not commit yet — bundle
with step 6 into one commit):
package.json— set"version"toVERSION.package-lock.json— set both the top-level"version"and thepackages[""].versiontoVERSION(keep them in sync sonpm cion the runner does not fail).
6. Consolidate CHANGELOG
This is the step that stays in the skill's judgement — the workflow only
reads the finished section. Rewrite CHANGELOG.md:
-
Replace the
## [Unreleased]heading with## [VERSION] - YYYY-MM-DD(today's date) and prepend a fresh empty## [Unreleased]section above it. -
Order subsections in the new
## [VERSION]section to the canonical Keep-a-Changelog sequence:Added→Changed→Deprecated→Removed→Fixed→Security. Drop any subsection with no bullets. Merge any duplicate subsections (e.g. two### Addedblocks) into one. -
Merge grouped bullets. Collapse multiple bullets describing the same logical change applied to several items into a single bullet that names all items. One bullet per logical change, not per file.
-
Keep every distinct change. Prefer a slightly longer list over a lossy summary. Do not touch anything below the new versioned heading.
Verify the file parses correctly (no duplicate headings, no orphaned bullets).
6a. Draft the release summary
Write a 2-5 sentence plain-prose paragraph (no markdown headers) covering the
release's user-facing highlights: new distributions/features, notable
behavior or API changes (call out anything mid-deprecation-cycle), and the
general shape of the fix batch. Base it on the ## [VERSION] section just
written in step 6 — this is a compressed read of that section, not new
research.
This text is not written into CHANGELOG.md. It is passed as the
summary input when triggering the release workflow (step 10), which
prepends it above the CHANGELOG notes in the GitHub release — so every
release carries a human-readable overview instead of a raw bullet dump, with
no manual copy-paste step after the fact.
7. Commit release branch
Commit the step 5 + step 6 edits as a single commit Release v{VERSION} on
release/v{VERSION} using mcp__github__push_files (all files in one commit).
8. Create PR
mcp__github__create_pull_request:
- title:
Release v{VERSION} - base:
main, head:release/v{VERSION} - body: the commit list from step 3 plus a note
*Automated release PR — do not add commits to this branch.*
Record the PR number and URL.
9. Merge PR
Wait for the PR's required checks to pass, then merge:
- Poll
mcp__github__pull_request_read(andmcp__github__get_check_runif needed) until the PR is mergeable and checks are green (5-minute timeout, ~15-second interval). mcp__github__merge_pull_requestwith methodmerge.
If the merge is blocked or times out, stop and report — do not force it.
10. Trigger the release workflow
Once the PR is merged (the bumped package.json and consolidated CHANGELOG.md
are now on main), trigger the workflow:
mcp__github__actions_run_trigger—workflow_idrelease.yml,refmain,inputs: { version: "VERSION", summary: "SUMMARY" }(SUMMARYfrom step 6a).
The workflow then, on the runner, does everything MCP cannot:
- creates and pushes the
v{VERSION}tag, - runs lint/typecheck/tests and
npm publish --provenance, - cuts the GitHub release with
SUMMARYprepended above the consolidated## [VERSION]notes fromCHANGELOG.md, - rotates the milestone (creates
v{NEXT_VERSION}, moves open issues, closesv{VERSION}).
Poll mcp__github__actions_list / mcp__github__actions_get for the run and
report its conclusion. If the run fails on the tag step, the most likely cause
is the github-actions[bot] tag-protection bypass not being configured (see
Pre-conditions).
11. Report
End with a concise summary:
Released: v{VERSION}
PR: {PR_URL} (merged)
Workflow: {RUN_URL} → tag, npm publish, GitHub release, milestone rotation
Milestone: v{VERSION} closed, v{NEXT_VERSION} created (by the workflow)
Rules
- All GitHub state changes go through MCP — never assume
ghor a local tag push is available. - Never skip the workflow trigger — without step 10 nothing is tagged or published to npm. The merged PR alone publishes nothing.
- Consolidate the changelog in the skill, not the workflow — the semantic
merge of grouped bullets is judgement the workflow cannot do; it only reads
the finished
## [VERSION]section. - Always draft and pass a
summary(step 6a) — the workflow still publishes without one (silently falling back to the raw CHANGELOG notes alone), but every release should carry a human-readable overview, not just a bullet dump. Writing it is judgement the workflow can't do either, same reasoning as changelog consolidation — draft it in the skill, never leave it for a human to paste in after the fact. - Milestone rotation is best-effort — the workflow warns and continues if the milestone is missing.
- No interactive prompts mid-pipeline — if anything is ambiguous, abort early with a clear message rather than pausing mid-release.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |