release
Skill0 starsChanged 10 days agoApache-2.0View on GitHub
Prepare a change in this repo (pi-plugin-cc) for release. Picks the Semantic Versioning bump against the default branch, sets the version in package.json, package-lock.json, plugin.json, and marketplace.json with `npm run bump-version`, writes the CHANGELOG.md entry under that version, and updates the docs the change makes stale (README, COMPARISON, DEVELOPMENT, CLAUDE.md). Use when a change is ready for a pull request, after fixing a bug or adding or changing a command, flag, output, or setup step, or when asked to bump the version or cut a release. sync-upstream runs it after porting upstream codex-plugin-cc changes.
193 other projects use a version of this.
Adopted by
Most recently taken up by
- naomiaro/waveform-playlisttheir own version, first seen Nov 16, 2026
- osmlab/name-suggestion-indextheir own version, first seen Nov 16, 2026
- vulnerability-lookup/vulnerability-lookuptheir own version, first seen Nov 16, 2026
- ClickHouse/mcp-clickhousetheir own version, first seen Nov 16, 2026
- bpatrik/pigallery2their own version, first seen Nov 16, 2026
- Shasnow/StarRailAssistanttheir own version, first seen Nov 16, 2026
Used with
Projects with it also use create-agent-adapter, changelog-style and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
MicrosoftSkillcreate-agent-adapter
Technical guide for creating a new Paperclip agent adapter. Use when building a new adapter package, adding support for a new AI coding tool (e.g. a new CLI agent, API-based agent, or custom process), or when modifying the adapter system. Covers the required interfaces, module structure, registration points, and conventions derived from the existing claude-local and codex-local adapters.
Also in 5 projects that use this
GrinvSkillchangelog-style
Turn a commit range into CHANGELOG.md entries following common-changelog style. Use when finishing a PR or cutting a release, to write/fix the [Unreleased] section's entries — moving [Unreleased] under a new dated version heading is a separate, automated step (see the release skill / scripts/sync-version.ts), not this skill's job.
Also in 4 projects that use this
Microsoft AzureSkillcomponent-release
Prepares a verifiable Agent Landing Zone UI release. Use for release branches, VERSION, changelog entries, tags, release notes, and compatibility evidence; never publish without explicit human approval.
Also in 4 projects that use this
GrinvSkilldocs-consistency-check
Check README/manifest.json/server.json/CHANGELOG.md/AGENTS.md and docs/*.md for drift against the actual registered tools and source. Use after adding, renaming, or removing a tool, or as part of a live-audit pass.
Also in 4 projects that use this
Microsoft AzureSkilldocumentation-consistency
Keeps AI Landing Zone contributor, user, and operator documentation aligned with shipped Bicep behavior. Use for parameters, defaults, outputs, topology, deployment flow, operations, or releases.
Also in 8 projects that use this
parcadeiSkillagent-context-isolation
Agent Context Isolation
Also in 3 projects that use this
- +3 more from Grinv
Other versions193 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 193
- paperclipai/paperclip★ 114ksame name
- modelcontextprotocol/servers★ 92ksame name
- remotion-dev/remotion★ 73ksame name
- traefik/traefik★ 66ksame name
- usememos/memos★ 64ksame name
- tw93/Pake★ 64ksame name
- AmruthPillai/Reactive-Resume★ 46ksame name
- amruthpillai/reactive-resume★ 46ksame name
- reactive-resume/reactive-resume★ 46ksame name
- Yeachan-Heo/oh-my-claudecode★ 41ksame name
183 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository2 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- sync-upstreamSkill
The file
We split this skill into the rules it gives an agent
7 rules. 0 are common, 3 are distinctive, and 4 are very specific to this project.
0
Common
Most of the 183 edited versions we read keep these.
3
Distinctive
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 20
Run this skill once per pull request, after the code and tests are done.
- Very specific: line 69
If another pull request takes your number first, rebasing conflicts in package.json and CHANGELOG.md.
- Very specific: line 98
Write one bullet per change users can see, saying what they see.
- Very specific: line 101
Leave the Synced upstream: codex-plugin-cc vX.Y.Z line alone unless you are syncing.
- Distinctive: line 115
Update only the docs the table names.
- Distinctive: line 133
All four must pass. CI runs the same checks.
- Very specific: line 144
After the pull request merges, the user may tag v<version> for a GitHub release (upstream tags v1.0.6).
“Common” is measured: kept by at least 6 in 10 of the 183 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Release a change
Users install this plugin from the repository's default branch
(/plugin marketplace add 5kahoisaac/pi-plugin-cc), so every change merged to main that touches
plugins/pi/ reaches them, but only once the version changes. Claude Code copies an installed
plugin into ~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/ and keeps users there:
- "Bump
versionon each release: users stay on their cached copy until the string changes." plugin.json'sversionwins over the marketplace entry's. When both are set and differ,claude plugin validatereports the mismatch.
Both points come from the Claude Code docs, Host and maintain a marketplace, "Release a new version".
Run this skill once per pull request, after the code and tests are done. It never commits, tags, or pushes. Leave those to the user.
Preconditions
- The change is complete and
npm testpasses. Release notes describe working behavior. origin/mainis current:git fetch origin.
Step 1 — Find the base version and whether the change ships
git cat-file -e origin/main:package.json \
&& git show origin/main:package.json | node -p 'JSON.parse(require("node:fs").readFileSync(0, "utf8")).version'
node -p 'require("./package.json").version' # this branch's version
git diff --name-only origin/main...HEAD -- plugins/pi # committed on this branch
git status --porcelain -- plugins/pi # not committed yet, including new files- Base version: the first command's output. If
origin/mainhas nopackage.json, this branch introduces the first version,0.1.0, and needs no bump. - Ships: either of the last two commands lists a file. Only
plugins/pi/is copied into the plugin cache, so a change there needs a version above the base. - Repo-only: nothing under
plugins/pi/changed (tests, CI,scripts/, the skills, README, contributor docs, the marketplace listing). It needs no bump. Skip to Step 5; add a CHANGELOG line only if this branch already carries a version above the base.
Step 2 — Choose the version
SemVer rule 4: "Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable." This project's own rule while it is on 0.y.z: breaking changes and new features bump the minor version, and everything else bumps the patch.
The public interface is what users and Claude touch: the slash commands with their flags,
arguments, and accepted values; each command's rendered output and --json payload; the
pi:pi-rescue subagent; the hooks' behavior; PI_COMPANION_* variables; and the supported Pi and
Node.js versions.
| Change | On 0.y.z | From 1.0.0 |
Breaking: removes or renames a command or flag, rejects input that used to work, changes output or --json fields that commands parse, raises the minimum Pi or Node.js version | minor | major |
| Feature: new command, flag, accepted value, or output field that keeps old usage working | minor | minor |
Fix, prompt or wording change, docs under plugins/pi/, refactor, performance | patch | patch |
Then compare this branch's version with the base:
- Equal: bump from the base, e.g. a fix on
0.1.0becomes0.1.1. - Already above the base: this branch bumped earlier. Keep it, unless the change now needs a
higher level (base
0.1.0, branch0.1.1, and you add a feature: re-bump to0.2.0). - If another pull request takes your number first, rebasing conflicts in
package.jsonand CHANGELOG.md. Rebase ontomainand run this skill again.
Going to 1.0.0 is the user's decision. Never make that bump on your own.
Step 3 — Set the version everywhere
npm run bump-version -- X.Y.Zscripts/bump-version.mjs (upstream's script) writes all six fields: package.json version,
package-lock.json version and packages[""].version, plugins/pi/.claude-plugin/plugin.json
version, and .claude-plugin/marketplace.json metadata.version and plugins[pi].version.
Like upstream, the version sits in both plugin.json and the marketplace entry, so the two must
match. Never edit them by hand. npm run check-version confirms they agree, and npm test checks the
same in CI.
Step 4 — Write the CHANGELOG entry
- There is no
[Unreleased]section. Every change sits under its version heading,## [X.Y.Z] — YYYY-MM-DD, newest first.tests/commands.test.mjsfails unless the newest heading ispackage.json's version. - For a new version, add its heading above the newest one and date it today. For a re-bump
(
0.1.1→0.2.0), rename the existing heading. For a version this branch already added, add to its section. - Group bullets under Keep a Changelog's types and use only the ones that apply:
Added,Changed,Deprecated,Removed,Fixed,Security.0.1.0has onlyAdded, because there is no earlier version to compare it with. - Write one bullet per change users can see, saying what they see. For a fix, give the symptom
and the fix ("
/pi:statusprinted a literal<br>; each follow-up command now has its own line"), not just "fix status". - Leave the
Synced upstream: codex-plugin-cc vX.Y.Zline alone unless you are syncing. sync-upstream reads the newest one, and a sync adds a new one to its version's section.
Step 5 — Update the docs the change makes stale
| Change | Doc |
| A command, flag, setup step, or output users see | README.md (keep upstream's structure) |
| Something done differently from upstream because Pi differs | COMPARISON.md: the summary row and the numbered section, with evidence (Pi docs, Observed, Upstream, Plugin) |
| Install, readiness, or sign-in | README.md and COMPARISON.md §7 |
| Repo layout, a convention, or a new trap | CLAUDE.md (AGENTS.md is a symlink to it) |
| Loading, validation, debugging, or release workflow | DEVELOPMENT.md |
| License or attribution | Never weaken LICENSE or either NOTICE |
Update only the docs the table names. README.md documents behavior, not internals.
Step 6 — Style gates
- "Pi" is capitalized in prose. Lowercase
pionly in literal commands, paths, and flags (pi -p,/pi:task,pi-companion.mjs). - State behavior. No marketing language, no TODOs or placeholders.
- Escape
|inside table cells as\|.
Step 7 — Verify
npm test
npm run check-version
claude plugin validate --strict ./plugins/pi
claude plugin validate --strict .All four must pass. CI runs the same checks. Re-read each edited doc once, and confirm LICENSE and both NOTICE files are untouched.
Step 8 — Report
Tell the user:
- the base version, the new version, and the table row that decided it;
- the files the bump touched and the CHANGELOG section;
- which docs you updated (one line why each) and which you left alone;
- the verification results.
After the pull request merges, the user may tag v<version> for a GitHub release (upstream tags
v1.0.6). Claude Code does not read tags.
Notes
- Local testing needs no bump. A marketplace added from a local path (
npm run dev:bind) loads the plugin in place, so edits apply at/reload-plugins(Plugin loading reference, "In-place and copied plugins"). - Example:
mainis at0.1.0and a branch fixesrender.mjs. Bump to0.1.1and add## [0.1.1] — <today>with a### Fixedbullet. If the same branch then adds--jsonto/pi:status, re-bump to0.2.0, rename the heading, add an### Addedbullet, and update the README usage. - Example: a branch changes only
tests/and CI. No bump and no CHANGELOG entry.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

