Download .agents/skills/release/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
Where does release live?
The publisher keeps it at https://github.com/paperclipai/paperclip.
Which agents can use release?
Claude, Cursor, and Codex can read a SKILL.md you add from the publisher's repository.
>
name: release
description: >
Coordinate a full Paperclip release across engineering verification, npm,
GitHub, smoke testing, and announcement follow-up. Use when leadership asks
to ship a release, not merely to discuss versioning.
Release Coordination Skill
Run the full Paperclip maintainer release workflow, not just an npm publish.
This skill coordinates:
stable changelog drafting via release-changelog
canary verification and publish status from master
Docker smoke testing via scripts/docker-onboard-smoke.sh
manual stable promotion from a chosen source ref
GitHub Release creation
website / announcement follow-up tasks
release-content Cases dogfood: a top-level release case with child
blog_post and tweet_storm cases, all linked to the release issue/run
Trigger
Use this skill when leadership asks for:
"do a release"
"ship the release"
"promote this canary to stable"
"cut the stable release"
Preconditions
Before proceeding, verify all of the following:
.agents/skills/release-changelog/SKILL.md exists and is usable.
The repo working tree is clean, including untracked files.
There is at least one canary or candidate commit since the last stable tag.
The candidate SHA has passed the verification gate or is about to.
If manifests changed, the CI-owned pnpm-lock.yaml refresh is already merged on master.
npm publish rights are available through GitHub trusted publishing, or through local npm auth for emergency/manual use.
If running through Paperclip, you have issue context for status updates and follow-up task creation.
If any precondition fails, stop and report the blocker.
Inputs
Collect these inputs up front:
whether the target is a canary check or a stable promotion
the candidate source_ref for stable
whether the stable run is dry-run or live
release issue / company context for website and announcement follow-up
Step 0 — Release Model
Paperclip now uses a commit-driven release model:
every push to master publishes a canary automatically
canaries use YYYY.MDD.P-canary.N
stable releases use YYYY.MDD.P
the middle slot is MDD, where M is the UTC month and DD is the zero-padded UTC day
the stable patch slot increments when more than one stable ships on the same UTC date
stable releases are manually promoted from a chosen tested commit or canary source commit
only stable releases get releases/vYYYY.MDD.P.md, git tag vYYYY.MDD.P, and a GitHub Release
Critical consequences:
do not use release branches as the default path
do not derive major/minor/patch bumps
do not create canary changelog files
do not create canary GitHub Releases
Step 1 — Choose the Candidate
For canary validation:
inspect the latest successful canary run on master
record the canary version and source SHA
For stable promotion:
choose the tested source ref
confirm it is the exact SHA you want to promote
resolve the target stable version with ./scripts/release.sh stable --date YYYY-MM-DD --print-version
Useful commands:
git tag --list 'v*' --sort=-version:refname | head -1
git log --oneline --no-merges
npm view paperclipai@canary version
Step 2 — Draft the Stable Changelog
Stable changelog files live at:
releases/vYYYY.MDD.P.md
Invoke release-changelog and generate or update the stable notes only.
Rules:
review the draft with a human before publish
preserve manual edits if the file already exists
keep the filename stable-only
do not create a canary changelog file
Step 3 — Verify the Candidate SHA
Run the standard gate:
pnpm -r typecheck
pnpm test:run
pnpm build
If the GitHub release workflow will run the publish, it can rerun this gate. Still report local status if you checked it.
For PRs that touch release logic, the repo also runs a canary release dry-run in CI. That is a release-specific guard, not a substitute for the standard gate.
Step 4 — Validate the Canary
The normal canary path is automatic from master via:
.github/workflows/release.yml
Confirm:
verification passed
npm canary publish succeeded
git tag canary/vYYYY.MDD.P-canary.N exists
Useful checks:
npm view paperclipai@canary version
git tag --list 'canary/v*' --sort=-version:refname | head -5
These should reference the stable release, not the canary.
Step 8 — Emit Release-Content Cases
When Cases are enabled, every stable release-content run must materialize a
deterministic case tree. This is part of the release dogfood path, not an
optional artifact. If the API returns 403 Cases are disabled, stop and report
that the operator must enable experimental.enableCases.
Use the current release issue's PAPERCLIP_COMPANY_ID, PAPERCLIP_API_URL,
PAPERCLIP_API_KEY, and PAPERCLIP_RUN_ID. Include X-Paperclip-Run-Id on
all writes so the case activity feed can attribute the run back to the issue.
The fields schema intentionally uses all generic JSON value types: strings,
numbers, booleans, arrays, objects, and nulls. Send the complete fields object on
each upsert because case fields replace as a whole object.
Write the parent body document immediately after the upsert:
PUT /api/cases/:releaseCaseId/documents/body
{
"title": "Paperclip vYYYY.MDD.P release body",
"format": "markdown",
"body": "# Paperclip vYYYY.MDD.P\n\nRelease summary and links...",
"changeSummary": "Initial release case body"
}
Then create or upsert these child cases with parentCaseId set to the release
case id:
blog_post, key paperclip-release:vYYYY.MDD.P:blog-post, status
in_progress, body document key body
tweet_storm, key paperclip-release:vYYYY.MDD.P:tweet-storm, status
in_progress, body document key body
Use deterministic keys exactly so rerunning the release-content flow upserts the
same three cases instead of duplicating them. After the child body documents are
written, list the resulting case identifiers and links in the release issue and
in the parent acceptance issue when one exists.
Failure Handling
If the canary is bad:
publish another canary, do not ship stable
If stable npm publish succeeds but tag push or GitHub release creation fails:
fix the git/GitHub issue immediately from the same release result
do not republish the same version
If latest is bad after stable publish:
./scripts/rollback-latest.sh <last-good-version>
Then fix forward with a new stable release.
Output
When the skill completes, provide:
candidate SHA and tested canary version, if relevant
stable version, if promoted
verification status
npm status
smoke-test status
git tag / GitHub Release status
website / announcement follow-up status
release-content case tree links: parent release case plus blog_post and
tweet_storm children
rollback recommendation if anything is still partially complete
How do I install release?
Download .agents/skills/release/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
Where does release live?
The publisher keeps it at https://github.com/paperclipai/paperclip.
Which agents can use release?
Claude, Cursor, and Codex can read a SKILL.md you add from the publisher's repository.