plugin-catalog-changes
Skill1 starsChanged yesterdayMITView on GitHub
Renames, removes, deprecates or merges plugins in this marketplace without breaking existing installs, through the marketplace's renames map. Use whenever a plugin should get a new name, be retired, withdrawn or deprecated, or be folded into another plugin, or when someone asks what users see after a plugin disappears from the catalog, even if they only say "kill this plugin" or "combine these two".
- Deletes or force-pushes
In this repository5 other files it gives its agents.
- .claude/CLAUDE.mdCLAUDE.md
- referencesSkill
- docs-maintenanceSkill
- plugin-iconsSkill
- plugin-releasesSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 3 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 41
Check the map, and show the raw output:
- Distinctive: line 45
Never reuse a retired name, and never delete the old tags or GitHub Releases: they are the history users and dependents resolve against.
- Very specific: line 51
Add "<old>": "<new>" to renames.
- Very specific: line 53
Update the documents with the docs-maintenance skill: every command and name in the plugin's README.md, its catalog row in the root …
- Very specific: line 58
Remove the entry from plugins in marketplace.json.
- Very specific: line 60
Update the documents with the docs-maintenance skill: remove the plugin's row from the root README.md catalog and the plugin from …
- Very specific: line 68
Update the documents with the docs-maintenance skill: <target>'s README.md for the components it gained, <old>'s removal from the root …
- Very specific: line 69
After the release, run After the release and confirm claude plugin list --json shows <target> (see Version notes).
- Distinctive: line 73
Check what users receive in throwaway configurations, so your own stays untouched:
- Very specific: line 84
after a rename or a merge, check:install exits 0 for <new-or-target> (the new name, or the merge target): claude plugin list --json shows …
≈ “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 catalog changes
Users install, enable and configure a plugin by name@the-claude-factory, and that name is the key in their enabledPlugins and pluginConfigs settings. Changing or dropping a name without telling Claude Code breaks every existing install, so every one of these changes goes through the renames map in .claude-plugin/marketplace.json.
How Claude Code handles it (official)
From code.claude.com/docs/en/plugins/publish (Rename or remove a plugin) and host-marketplace (Rename or remove a plugin; Work around what a marketplace can't do):
- For a different label only, set
displayNameinplugin.jsonand keepname. That is not a rename. renamesmaps each former name to its current name, or tonullwhen the plugin is gone. After the push, a user who still has the old name enabled sees:- renamed: the plugin loads under the new name,
Renamed to "<new>" in the "the-claude-factory" marketplaceshows once, and Claude Code rewrites the key in the user, project and local settings. From a git-hosted marketplace it reportsPlugin "<new>" not cacheduntil the user runs/plugin install <new>@the-claude-factoryonce. null: the key is dropped andRemoved from the "the-claude-factory" marketplaceshows.- enabled in managed settings: the notice recurs until an admin updates
enabledPluginsthere.
- renamed: the plugin loads under the new name,
renamesis append-only history: keep old entries after everyone migrated, and add a second entry for a second rename, because Claude Code follows the chain from the oldest name.- With
"forceRemoveDeletedPlugins": true, Claude Code uninstalls, at each session start, every installed plugin that is neither listed nor renamed, from the user, project and local scopes, and flags it in/pluginasRemoved from marketplace. Plugins installed only by managed settings stay. Without it, a removed plugin stays installed and reportsPlugin "<name>" not found in marketplace. This marketplace sets it totruein.claude-plugin/marketplace.json(owner's decision, 2026-11-13); confirm it is still there withjq '.forceRemoveDeletedPlugins' .claude-plugin/marketplace.jsonbefore a removal. - A user who removes a plugin by hand runs
claude plugin uninstall <plugin> [--scope <scope>] [--keep-data] [--prune]. Uninstalling from the last scope deletes the plugin's options, secrets and data unless--keep-datais passed, and--prunealso removes dependencies nothing else needs. When a removed plugin stores options or data, say this in the removal's line in the rootCHANGELOG.md. - A user who runs
claude plugin marketplace remove the-claude-factoryfrom the last scope that declares it uninstalls every plugin installed from it, and Claude Code deletes their saved options, secrets and data where it can;claude plugin marketplace updaterefreshes the listings without that loss (code.claude.com/docs/en/plugins/cli-reference, plugin marketplace remove). - There is no deprecation state. Deprecating a plugin means removing its entry, mapping its name to
null, and lettingforceRemoveDeletedPluginsuninstall it. claude plugin validate .rejects a chain that cycles or that ends anywhere butnullor a listed name, withrenames.<name>: chain does not resolve. Several former names may point to one plugin (checked on Claude Code 2.1.323).
Steps for every case
- Confirm the case with the owner: rename, removal (deprecation is a removal), or merge into another plugin.
- Find every use of the old name and change the live ones; dated history such as changelog entries and specs keeps the old name:
grep -rn '<old>' . --exclude-dir=.git --exclude-dir=node_modules - Find what depends on the old plugin, and change each dependent first, since a dependency on a missing plugin fails to install:
dependenciesthat name<old>, in eachplugin.jsonand in each marketplace entry. This prints onedependent: <plugin> needs <name> <range>line per declared dependency; any line whose<name>is<old>is a dependent:npm run release:status- symlinks into
plugins/<old>/(find plugins -type l) Tell the owner that plugins in other repositories may depend on<old>and can't be checked from here.
- Make the change for the case (sections below), and make every "plugin" dropdown in
.github/ISSUE_TEMPLATE/*.ymland.github/VULNERABILITY_REPORT.ymllist exactly the plugins ofmarketplace.json, in catalog order. - Check the map, and show the raw output:
npm run check:prexits 0: itslintstep fails on a dropdown left behind, and itsbiome-changedstep on a changed file Biome would reformatclaude plugin validate --strict .exits 0npm run check:consistencyexits 0. ItsPC-02finding is arenameskey still listed inplugins, which the validator doesn't catch;PC-01andPC-08catch a name, source or catalog row left behind.
- Never reuse a retired name, and never delete the old tags or GitHub Releases: they are the history users and dependents resolve against.
Rename
- Choose
<new>: kebab-case, not inplugins, not a key ofrenames, and noplugins/<new>/folder yet. git mv plugins/<old> plugins/<new>, then changenameinplugin.json, the marketplace entry'snameandsource(./plugins/<new>), any URL inplugin.jsonthat contains<old>, and every other live use step 2 of Steps for every case found.- Add
"<old>": "<new>"torenames. - Bump the plugin as a breaking change through the
plugin-releasesskill (Minor in0.x, Major after). Its changelog entry starts with**Breaking:**, maps each old command to the new one, and tells users to run/plugin install <new>@the-claude-factoryonce. - Update the documents with the
docs-maintenanceskill: every command and name in the plugin'sREADME.md, its catalog row in the rootREADME.md, and the rename's line in the rootCHANGELOG.md. - With the owner's authorization, run
npm run labels:sync -- --applyso theplugin: <new>label exists; the old label stays.
Removal or deprecation
- Remove the entry from
pluginsinmarketplace.json. Whetherplugins/<old>/is deleted too is the owner's call. - Add
"<old>": nulltorenames. - Update the documents with the
docs-maintenanceskill: remove the plugin's row from the rootREADME.mdcatalog and the plugin fromPRIVACY.md, and record the removal in the rootCHANGELOG.mdunder### Removed. The removed plugin gets no version bump and no new tag.
Merge into another plugin
- Move the components into
plugins/<target>/, check every moved symlink, then remove<old>'s entry and folder. - Compare the
userConfigkeys of both plugins: Claude Code moves<old>'s saved options to<target>, so a key that means something else in<target>is a breaking change to resolve first. - Add
"<old>": "<target>"torenames. - Bump
<target>through theplugin-releasesskill (at least Minor). Its changelog maps each old command to the new one and tells users to run/plugin install <target>@the-claude-factoryonce. - Update the documents with the
docs-maintenanceskill:<target>'sREADME.mdfor the components it gained,<old>'s removal from the rootREADME.mdcatalog and fromPRIVACY.md, and the merge's line in the rootCHANGELOG.md. - After the release, run After the release and confirm
claude plugin list --jsonshows<target>(see Version notes).
After the release
Check what users receive in throwaway configurations, so your own stays untouched:
T="$(mktemp -d)"
env CLAUDE_CONFIG_DIR="${T}/config" CLAUDE_CODE_PLUGIN_CACHE_DIR="${T}/cache" claude plugin marketplace add "nerymurillohnd/the-claude-factory#main"
env CLAUDE_CONFIG_DIR="${T}/config" CLAUDE_CODE_PLUGIN_CACHE_DIR="${T}/cache" claude plugin install <old>@the-claude-factory
rm -rf "${T}"
npm run check:install -- --from main <new-or-target>- installing
<old>fails withnot found in marketplace - after a rename or a merge,
check:installexits 0 for<new-or-target>(the new name, or the merge target):claude plugin list --jsonshows it at its new version with noerrors, and the installed copy validates - the old name's last tag and GitHub Release still exist:
gh api repos/nerymurillohnd/the-claude-factory/releases/tags/<old>--v<last version>in a terminal session; in a cloud session, whereghis kept for search, the MCP toolgithub:get_release_by_tag(owner: nerymurillohnd,repo: the-claude-factory,tag: <old>--v<last version>).
Version notes
On Claude Code 2.1.319, after a merge claude plugin list left <target> out and claude plugin update failed until the user ran /plugin install <target>@the-claude-factory. Unverified on later versions.
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.

