plugin-releases
Skill1 starsChanged 2 days agoMITView on GitHub
Versions and releases a plugin of this marketplace end to end, from the semver bump and its changelog notes to the reviews and checks before the merge, the changelog date, the tag and GitHub Release that CI creates, the checks after, and the backfill of a version that never got its tag. Use whenever a plugin under plugins/ changed and may need a version bump, a new plugin needs its first version, someone asks which semver level a change takes, a version is about to be merged or published, a tag or Release is missing or must be verified, or someone asks how users receive an update, even if they only say "bump it", "ship it" or "publish the new version".
In this repository5 other files it gives its agents.
- .claude/CLAUDE.mdCLAUDE.md
- referencesSkill
- docs-maintenanceSkill
- plugin-catalog-changesSkill
- plugin-iconsSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 2 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 34
Every released version gets a tag and a GitHub Release with the same name, never a draft or prerelease.
- Distinctive: line 37
Never move, delete or reuse a tag.
- Very specific: line 43
Only the plugin's README.md, CHANGELOG.md, LICENSE, NOTICE.txt, tests/, *.test.ts(x) or evals/ changed: no bump.
- Very specific: line 44
Only .claude-plugin/marketplace.json changed: no plugin bump.
- Very specific: line 54
Set the version: After git fetch origin main, set version in plugins/<plugin>/.claude-plugin/plugin.json to what npm run release:status -- …
- Very specific: line 68
Write the release line in the root CHANGELOG.md, with the same date.
- Very specific: line 81
Merge: only with the owner's authorization, Validate's Checks green on the pull request's latest push, and every review resolved.
- Distinctive: line 99
Verify as in Phase D. A dispatch with an unknown plugin exits 2, and one whose commit isn't on main exits 1.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Plugin releases
Every plugin here is a relative-path entry (./plugins/<plugin>) in a git-hosted marketplace. Users receive a change only when the plugin's version string changes, and they receive whatever main holds the moment a merge lands. So the bump, the notes and every check happen before the merge; after it, CI tags the version and you confirm what users got.
Gotchas
- One version per release.
release.ymltags only each plugin's currentplugin.jsonversion. Never bump a plugin again while its previous version has no tag: that version can then only get its tag through a backfill (Backfill below). - The catalog row moves with the version.
npm run check:consistency(PC-08) fails as soon asplugin.jsonand the rootREADME.mdcatalog cell disagree, so set both in the same change (Phase A), not at release time. - The changelog date is the day the version was prepared, in UTC; never re-date it.
release:changelogwrites it before the merge, and the GitHub Release records the day the version was published. No check compares the two, so a merge on a later day changes nothing. untagged:is not the backfill list.npm run release:statusprintsuntagged:only for each plugin's current version onmain, which the next merge's release tags on its own. A version that will never be tagged that way, an older heading with no tag, shows only as a PC-04 finding ofnpm run check:consistency: those are the versions to backfill.- A rename computes the next version from the old name.
npm run release:status -- --next <new name>finds nothing onorigin/mainand prints0.1.0; pass the old name, and treat the rename as breaking. - Cloud sessions never tag. The cloud proxy refuses tag pushes and answers 403 to
POST …/git/refsandPOST …/releases. Onlyrelease.ymlcreates tags and Releases; a cloud session only dispatches it, with the owner's authorization. - Auto-fix stays off. Claude's Auto-fix for pull requests pushes fixes without asking, which this project doesn't allow; CI failures and review findings go through
github-operations:auto-pr-lifecycle, which asks before every push.
How Claude Code reads the version (official)
From code.claude.com/docs/en/plugins/host-marketplace (Release a new version), plugins/loading (How Claude Code computes the version) and plugins/manifest-reference (version):
- The version comes from
versioninplugin.jsonfirst, then from the marketplace entry; with neither, a relative-path plugin in a git-hosted marketplace uses the commit SHA. - With
versionset, commits pushed without changing it don't reach users:claude plugin updateprints<name> is already at the latest version (<version>). A merge without a bump still changes what a new install receives under the old number. - Set
versiononly inplugin.json. If the marketplace entry also sets one,plugin.jsonwins silently andclaude plugin validatereportsEntry declares version "<a>" but <path>/plugin.json says "<b>". - Ranges in other plugins'
dependenciesresolve against tags named<plugin>--v<version>, held by the marketplace repository.
Project conventions
These go beyond the docs and stay unless the owner changes them:
- Versions are semver. Changelogs follow Keep a Changelog, written with the
docs-maintenanceskill. - Every released version gets a tag and a GitHub Release with the same name, never a draft or prerelease. The Release body is that version's changelog section, then
claude plugin update <plugin>@the-claude-factory. - A plugin's
## [x.y.z]changelog headings are exactly its tags, and## [Unreleased]is empty onmain. - Tags made by
release.ymlare unsigned, because signing in CI would put the key in a GitHub secret. - Never move, delete or reuse a tag. A fix ships as a new version.
Phase A: Version, on the branch, with the change
- Identify the case.
- A new plugin: its first version is
0.1.0. Go to step 4. - Only the plugin's
README.md,CHANGELOG.md,LICENSE,NOTICE.txt,tests/,*.test.ts(x)orevals/changed: no bump. Stop. - Only
.claude-plugin/marketplace.jsonchanged: no plugin bump. A rename or removal goes through theplugin-catalog-changesskill. - Anything else in
plugins/<plugin>/changed: bump. Continue.
- A new plugin: its first version is
- Choose the level from the diff against
origin/main; when a change mixes levels, take the highest.- Major: a removed or renamed skill, agent, command or plugin; changed configuration keys; a new mandatory dependency; changed behavior users rely on.
- Minor: a new backward-compatible component, option or capability, or a higher
engines["claude-code"]floor. - Patch: a bug fix, prompt wording, a performance improvement, a refactor with the same behavior, or a metadata change such as the category, the listing URLs or the icon.
- In
0.x, a breaking change bumps Minor. Moving from0.xto1.0.0needs the owner's authorization, because it promises users a stable interface.
- Check dependents.
npm run release:statusprintsdependent: <plugin> needs <name> <range>for each declared dependency (anyfor a bare name). Keep the new version inside every range that names this plugin, or change the dependent in the same pull request. - Set the minimum Claude Code version when the change relies on a Claude Code feature:
engines["claude-code"]inplugin.json, as">=<lowest version that has the feature>". Outside the range the plugin is not installed, updated or loaded (changelog, 2.1.323; not yet in the manifest reference). Make the README's minimum Claude Code version say the same, and note it under### Changed. - Write the notes with the
docs-maintenanceskill under## [Unreleased]inplugins/<plugin>/CHANGELOG.md: one entry per user-visible change, under Added, Changed, Deprecated, Removed, Fixed or Security, with**Breaking:**where it breaks something. Update the README with the same skill when the change alters what it describes. For a new plugin, run that skill's "New plugin" event instead. - Set the version. After
git fetch origin main, setversioninplugins/<plugin>/.claude-plugin/plugin.jsonto whatnpm run release:status -- --next <plugin> --level <major|minor|patch>prints. Then set the plugin's version cell in the rootREADME.mdcatalog to the same value. - Check it, and show the raw output:
npm run release:statusexits 0 and listschanged: <plugin> <old> -> <new>; it exits 1 on a version that isn't semver, which the validator accepts.claude plugin validate --strict plugins/<plugin>andclaude plugin validate --strict .exit 0. A plugin that DEBT-003 holds back fails here today; report it instead of fixing it in this change.- For a mod (
tests/*.test.ts(x)),claude plugin test plugins/<plugin>exits 0; for hook tests,npm run test:pluginsexits 0. npm run check:consistency -- --offlineexits 0.npm run check:install -- --from local <plugin>exits 0 and prints the new version. It runs in a throwaway configuration, because this checkout and an installedthe-claude-factorycan't both be added under the same marketplace name.- With the owner's approval of the spend, a local smoke eval:
claude plugin eval plugins/<plugin> --case <case> --runs 1 --ablation none --no-publish.
Phase B: Before the merge
- Review the diff yourself before you ask to push: run
/code-reviewon the branch with thecode-reviewskill. For changed scripts and hooks, also launch thepr-review-toolkit:silent-failure-hunterandpr-review-toolkit:pr-test-analyzeragents when thepr-review-toolkitplugin (marketplaceclaude-plugins-official) is installed; when it isn't, say so instead of skipping the step silently. Fix what the reviews find, or report it to the owner when it needs a decision. - Date the release before you push, with the
docs-maintenanceskill, for every pluginnpm run release:statuslists as changed. Validate checks a pull request asmainwill be after the merge, so a version still under## [Unreleased]fails it (PC-05 and the release notes):npm run release:changelog -- <plugin>turns## [Unreleased]into## [X.Y.Z] - <today in UTC>, adds an empty## [Unreleased]above it and writes the compare and release links. It exits 1 and changes nothing when## [Unreleased]is empty: stop and ask the owner what the version changes.- Write the release line in the root
CHANGELOG.md, with the same date. - A version already dated keeps its date.
- Check what
release.ymlwill publish, on a committed tree:npm run release:notes -- <plugin>for every plugin builds the Release bodyrelease.ymlwill publish; it exits 1 when a version has no dated section with notes, and a failure there would stop the release loop at that plugin. Validate runs it the same way on pull requests and onmain.claude plugin tag plugins/<plugin> --dry-runprints<plugin>--v<version>; it exits 1 while any file under the plugin is uncommitted.find plugins/<plugin> -type llists no link out of the plugin.
- List for the owner what will ship:
git fetch origin main && npm run release:status.changed:lines are the new versions, anduntagged:lines are current versions onmainthat this merge's release will also tag. The PC-04 findings ofnpm run check:consistencyare versions that need a backfill (Backfill below) before Validate'sCheckscan pass. - Ask the owner to authorize the push, then drive the pull request with
github-operations:auto-pr-lifecycle. On the pull request:- Validate's
Checksjob must pass. ItsDebtjob reports the checks DEBT items hold back and never blocks. npm run check:install -- --from <pull request branch> <plugin>installs what users will get from the branch.
- Validate's
Phase C: Merge and release
- Merge only with the owner's authorization, Validate's
Checksgreen on the pull request's latest push, and every review resolved. - The release runs on its own. The push to
mainruns Validate; whenCheckspasses, itsReleasejob callsrelease.yml, which tags and publishes each plugin whose current version has no tag, at the merged commit. A plugin whose tag exists is skipped. - If the
Releasejob fails or is cancelled, tell the owner at once: users who update already have the merged version.release.ymlkeeps one release running and one waiting, so a third merge in quick succession cancels the waiting one; the next release then tags that version at its later commit. Fix a failure's cause in a new commit onmainthrough a pull request, then, with the owner's authorization, dispatchrelease.ymlonmain(Backfill below, withoutbackfill_target). Never move or reuse a tag.
Phase D: Verify, and show the raw output
git ls-remote --tags origin '<plugin>--v*'lists exactly the changelog's## [x.y.z]versions.- The tag's commit is an ancestor of
main:git merge-base --is-ancestor <tag commit> origin/main. - The GitHub Release exists with the tag's name and is neither a draft nor a prerelease: the GitHub MCP tool
get_release_by_tag(owner: nerymurillohnd,repo: the-claude-factory,tag: <plugin>--v<version>). npm run release:statusprints nountagged:line.npm run check:install -- --from main <plugin>installs the new version.
Backfill a version that never got its tag
release.yml also runs through workflow_dispatch, with two inputs: plugin, to release only that plugin, and backfill_target, a commit on main where the plugin's plugin.json held the version to release. The tag goes on that commit and the Release body comes from the dispatched branch's changelog, so the version's section must exist and be dated there. Every tag lands on a commit main has: the script refuses a target that isn't on origin/main, whichever branch was dispatched.
- Find the last commit on
mainwhereplugin.jsonheld the version:git log --format=%h origin/main -- plugins/<plugin>/.claude-plugin/plugin.json, thengit show <commit>:plugins/<plugin>/.claude-plugin/plugin.json. - With the owner's authorization, dispatch it from a cloud session with the GitHub MCP tool
actions_run_trigger(method: run_workflow,owner: nerymurillohnd,repo: the-claude-factory,workflow_id: release.yml,ref: <branch>,inputs: {"plugin": "<plugin>", "backfill_target": "<commit>"}). The run uses therelease.ymlof the branch it is dispatched on. - Verify as in Phase D. A dispatch with an unknown plugin exits 2, and one whose commit isn't on
mainexits 1; neither creates anything.
Withdraw a version
Claude Code can't take a published version back: users who updated keep it until a newer one reaches them. Release the fix as a new version through this skill, then mark the withdrawn version [YANKED] in the plugin's CHANGELOG.md with the docs-maintenance skill, with the evidence that it was withdrawn. Never delete its section, its tag or its GitHub Release.
What users run
From code.claude.com/docs/en/plugins/publish (Ship updates to users) and host-marketplace (Turn on auto-update). The release notes and the README give users these:
claude plugin update <plugin>@the-claude-factory [--scope <scope>]installs the new version.claude plugin marketplace update the-claude-factoryrefreshes the listings only; installed plugins keep their versions./reload-pluginsloads the new version into a running session.- Auto-update is off by default for this marketplace; each user turns it on under Marketplaces in
/plugin.
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.

