Guide · Agent skill

How to use the Paperclip Release Coordinator agent skill

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The Paperclip Release Coordinator is an agent skill, a packaged set of instructions that tells an AI agent how to run Paperclip's maintainer release process from start to finish. This guide explains what the skill does, how to install it, how to ask for it in plain language, and what it needs before it runs. It is written for Paperclip maintainers and release managers, not for general users of the project.

Paperclip Release Coordinatorpaperclipai/paperclip · MIT Download the skill

Quick start

1Install the skill. Download the ZIP from the directory page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings, Capabilities, Skills in the Claude apps.
2Confirm prerequisites. Check that the repo is a clean Git checkout with tags, that pnpm and Docker are available, and that the release-changelog skill exists at .agents/skills/release-changelog.
3Ask for the release in plain terms. Request a canary check or a stable promotion, for example "promote this canary to stable". State the candidate source ref and whether the run is dry-run or live.
4Run the verification gate. The agent runs pnpm -r typecheck, pnpm test:run and pnpm build against the candidate SHA and reports the results.
5Validate the canary and smoke test. The agent confirms the automatic canary published and runs the Docker onboarding smoke test, stopping if any check fails.
6Promote to stable and finish follow-ups. The agent guides the manual stable workflow, then creates follow-up tasks for the changelog, website and announcements that reference the stable release.

What is an agent skill?

An agent skill is a folder of instructions, centred on a SKILL.md file, that an AI agent can load when a task matches the skill's description. The agent reads the steps and follows them instead of improvising.

The release skill is named release and lives in the repository at .agents/skills/release. Its description says it coordinates a full Paperclip release across engineering verification, npm, GitHub, smoke testing and announcement follow-up, and should be used when leadership asks to ship a release rather than only to discuss versioning.

What the skill makes the agent do

The skill is meant to run the full maintainer workflow, not just an npm publish. Its source lists the work it coordinates: stable changelog drafting through the release-changelog skill, canary verification, Docker smoke testing, manual stable promotion from a chosen source ref, GitHub Release creation, and follow-up tasks for the website and announcements.

It also includes a release-content step. When Paperclip Cases are enabled, the agent creates a top-level release case with child blog_post and tweet_storm cases, all linked to the release issue and run.

Checks preconditions, such as a clean working tree and a canary or candidate commit since the last stable tag
Runs the standard gate: typecheck, tests and build
Validates the automatic canary published from master
Runs the Docker onboarding smoke test
Guides a manual stable promotion through a GitHub workflow
Creates follow-up tasks for the changelog, website and announcements
Creates linked release-content case records when that feature is enabled

Install the release skill

Download the ZIP for the skill from the directory page and unzip it. For a personal setup, place the skill folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.

In the Claude apps, you can instead upload the skill under Settings, then Capabilities, then Skills.

Personal install: unzip into ~/.claude/skills/
Project install: unzip into the project's .claude/skills/ folder
Claude apps: Settings, then Capabilities, then Skills, then upload

Trigger the skill with natural requests

The skill is designed to start when leadership asks for a release. The source lists these example phrasings as triggers: "do a release", "ship the release", "promote this canary to stable" and "cut the stable release".

Because the skill publishes to npm and GitHub, avoid casual wording such as a general question about version numbers. The skill's own rules say it should only run when a real release is requested.

"Do a release for the Paperclip repo."
"Promote this canary to stable."
"Cut the stable release from the tested commit."
"Check the latest canary and tell me if it is ready to promote."

What you need before you start

The skill checks preconditions before it proceeds and stops to report any blocker. Prepare these items first so the run does not stall.

A Git repository with the Paperclip source and tags
pnpm, plus the repo's test and build scripts
npm publish rights through GitHub trusted publishing, or local npm auth for emergency or manual use
Docker, for the smoke test script
Paperclip API access (company ID, API URL, API key and run ID) for case and follow-up steps
The release-changelog skill at .agents/skills/release-changelog
A clean working tree, including untracked files

Commands the skill uses

The skill runs the repo's own scripts. For verification it runs the standard gate. For smoke testing it runs the Docker onboarding script, optionally in an isolated variant with its own port and data directory.

For stable promotion, the skill resolves the target version with the release script. Local emergency commands are listed in the source for cases where the GitHub workflow is not used.

pnpm -r typecheck
pnpm test:run
pnpm build
PAPERCLIP_VERSION=canary ./scripts/docker-onboard-smoke.sh

Safety notes: scripts and network access

This skill runs scripts and uses the network. It can publish to npm and create GitHub Releases and tags, and the skill's own description notes that publishing is hard to undo. Review the release notes and the target commit before a live run.

The source recommends a dry run of the stable workflow first when practical. The skill also stops the stable release if smoke testing fails, and it should not be used for discussion alone.

Use dry-run mode for the stable workflow before the live publish
Confirm the exact source SHA you intend to promote
Stop the release if any smoke test step fails
Review the stable changelog with a human before publishing
Do not use the skill for casual versioning discussion

Tips for a smooth release

The skill follows a commit-driven model in which every push to master publishes a canary automatically and stable releases are promoted manually from a tested commit. Stable releases get a changelog file, a git tag and a GitHub Release, while canaries do not.

If a smoke test fails, the source's guidance is to fix the issue on master, wait for the next automatic canary and rerun the smoke test.

Check the latest successful canary run on master and record its version and source SHA
Use the git tag list to confirm the most recent stable tag before choosing a version
Keep manual edits to the changelog; the skill is told to preserve them if the file already exists
Make sure the release-changelog skill is present before you start

git tag --list 'v*' --sort=-version:refname | head -1
git log --oneline --no-merges
npm view paperclipai@canary version

What people use it for

Checking whether the latest automatic canary is healthy before promoting it to stable
Running a dry-run of the stable workflow to preview a promotion before the live publish
Verifying a candidate commit with the typecheck, test and build gate
Generating a consistent release checklist for a release manager to review
Creating linked release-content case records and follow-up tasks after a stable release

Frequently asked questions

How do I install the Paperclip release agent skill?

Download the skill ZIP from the directory page and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps you can also upload it under Settings, then Capabilities, then Skills.

What do I need to run the release skill?

You need a Git repository with the Paperclip source and tags, pnpm with the repo's scripts, npm publish rights through GitHub trusted publishing or local npm auth, Docker for the smoke test, Paperclip API access for case and follow-up steps, and the release-changelog skill at .agents/skills/release-changelog.

Is the Paperclip release skill free to use?

The source does not state pricing or licence terms beyond identifying the project's licence as MIT. Check the repository's licence file for the terms that apply to the code.

Can people outside the Paperclip team use this skill?

Not usefully. The skill depends on the repo's specific scripts, workflows and npm package names, so it is intended for Paperclip maintainers and release managers working in that repository.

Does the skill publish to npm automatically?

Canaries publish automatically when commits land on master through the release workflow. Stable releases are promoted manually through a workflow dispatch or local emergency commands, and the skill runs only when a real release is requested.

What should I do if the Docker smoke test fails?

Stop the stable release, fix the issue on master, wait for the next automatic canary, and rerun the smoke test. The source says the stable release should not proceed while smoke testing is failing.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you are a Paperclip maintainer or release manager who needs a consistent, checklist-driven path from canary to stable release. Skip it if you are outside the maintainer team or only want to talk about versioning, because it runs scripts and publishes to npm and GitHub, which are hard to reverse.

Download the skill