Ship a plugin: from a repo to an install that runs
A plugin that validates can still fail every user it reaches: its server
never starts, chat skips half of it, an update never arrives, or an
organization's members see it under a name nobody chose. Each failure is
silent, and each depends on the route the plugin travels. This skill
names the route first, then checks what ships, what each surface loads,
what version does, what an org sync fixes for good, and how to test
the install and the plugin's own skills without the user's real config.
It does not teach plugin layout or components: the Claude Code docs'
plugins/components page and claude plugin validate own those. A mod,
a pane or a hook module that changes Claude Code's own interface, is
plugin-authoring's. Submitting to Anthropic's directory is out of
scope.
This skill is path-scoped to .claude-plugin/*.json, so it is listed
only once a session reads or writes a plugin.json or
marketplace.json in its working directory. A plugin's own repository
holds both; anywhere else it costs nothing.
Every claim below was read in the Claude Code and claude.com docs on
2026-10-22 against Claude Code 2.1.308, unless it says otherwise.
Past it, its references/, then the live page: code.claude.com by the
claude-code-docs MCP server or
curl -s https://code.claude.com/docs/en/<page>.md, and claude.com,
which that server does not cover, by
curl -s https://claude.com/docs/<path>.md. A live page that
contradicts a line here wins: say so, act on the page, and route the
fix by capture-learning, bar a dated measured line that names the
page it overrules and the call that measured it, which a page changed
since its date sends back to re-measure. An observed claim is cited or
marked pending a doc check, and stands, marked observed, only where no
page covers it, as step 5's label claim does: silence is no
contradiction, and a page that later covers it wins.
1. Name the route
Ask which route the plugin travels, or read it from the repo: a
marketplace.json alone says little, since one repository can serve
every route at once.
| Route |
Who gets it |
What version does |
How a change arrives |
Local-path marketplace, marketplace add ./path |
whoever reads the path: the author, or a team on a shared directory |
nothing: current files load each session |
the next session or /reload-plugins; no dependency install |
| Marketplace added by source: GitHub, git URL |
anyone who can clone it with credentials already on their machine |
plugin.json, then the entry, else the commit SHA |
claude plugin update; auto-update is off until a user or admin turns it on; none past a ref pinned to a commit (below) |
| claude.ai organization sync |
members in chat, in Cowork, and in Claude Code sessions signed in to that account |
not read: claude.ai records its own |
a push to the default branch with Sync automatically on, or Re-sync; tags are not read |
| Claude Code managed settings |
every machine that receives them |
as added by source |
auto-update, when managed settings turn it on; none past a ref pinned to a commit (below) |
A repo's committed settings: extraKnownMarketplaces and enabledPlugins in its .claude/settings.json |
each contributor who trusts the folder and installs the plugin in that clone (below) |
as for the marketplace's route |
as for the marketplace's route |
A local-path test proves the least. The plugin loads in place from
the source directory, with no copy and no dependency install, so it sees
whatever the author's build left there. Every other route copies the
plugin into the cache and sees only what was committed.
A repo's committed enabledPlugins installs nothing. Each
contributor runs, once per clone, or at --scope user for every
project:
claude plugin install <name>@<marketplace> --scope project
Until then the plugin does not load at session start; with its
marketplace registered, /plugin's Errors tab shows not cached or
Plugin "<name>" is enabled in project settings but isn't installed here,
and with neither message, the marketplace is missing: add it first.
The repo's
extraKnownMarketplaces registers nothing in a folder the contributor
has not trusted, without a message. Two kinds of plugin skip the
install: one in a seed directory (plugins/org § "Seed containers and
CI"), and a relative-path one: listed in a marketplace added from a
local path, it loads at session start; in a git marketplace,
/reload-plugins loads it for that session alone, and
CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1 for one -p run (plugins/loading,
plugins/org, read 2026-11-14).
A ref set to the full lowercase SHA of a commit on a branch or tag
holds a marketplace there: a
github or git source then moves on neither a refresh nor an
auto-update, so an admin can pin a reviewed commit. Update Claude Code
on every machine first, since a client before v2.1.324 cannot load a
marketplace pinned so. A reserved name such as
claude-plugins-official refuses a SHA, and a plugin entry with its
own remote source still updates: pin that entry too, by its sha
(plugins/marketplace-reference, read 2026-11-14).
2. Ship what runs
Nothing builds a plugin. Claude Code's only install step is a Node.js
dependency install into the cached copy, and it runs only when the
plugin root holds both a package.json and a supported lockfile. Its
limits, each checked against the plugins/loading page on 2026-11-07:
- the lockfile is
npm-shrinkwrap.json or package-lock.json at
lockfileVersion 2 or 3, or bun.lock at 2 or lower; yarn.lock,
pnpm-lock.yaml and bun.lockb get no install
- every dependency is a registry package pinned exactly, fetched over
https unless from the installing user's own default npm registry; a
git, GitHub, folder, workspace or linked dependency gets no install
- frozen resolution: the lockfile's exact versions, and no install when
package.json and the lockfile list different dependencies
- a separate install folder holding only a copy of the dependency list,
so the plugin's
.npmrc, .env and bunfig.toml are not read (so a
registry or token set there cannot reach the install, an inference)
--ignore-scripts, so nothing compiles, native modules included
- npm
overrides or Bun patchedDependencies get no install
- 60 seconds, then it counts as failed
- "You can't turn the automatic install off"
So a .mcp.json pointing at a gitignored dist/ installs cleanly and
its server never starts. A plugin whose install fails or is skipped
still loads; /plugin and claude plugin list note the missing
node_modules. An update the user starts can retry an install that
failed or timed out, even at an unchanged version; one skipped for its
lockfile or a missing package manager stays skipped.
Pick one way out:
- Commit a bundle. A single-file bundle in a plugin folder that
holds no
package.json, so no install runs, with the repo's test
script regenerating it so a stale bundle shows as a diff. One session
reached ✔ Connected from a fresh clone this way, with an esbuild
CommonJS bundle (observed once, 2.1.308, 2026-10-22).
- Ship JavaScript and an exact npm lockfile, registry dependencies
only, and let the install run. An npm lockfile reaches the most users;
Claude Code runs that lockfile's package manager from the user's
PATH and tries no other.
- Install from a
SessionStart hook into ${CLAUDE_PLUGIN_DATA},
for what the install cannot provide: lifecycle scripts, Python, Yarn
or pnpm, git dependencies. The plugins/components page has the hook.
Then, whatever the way:
- Durable files go in
${CLAUDE_PLUGIN_DATA}. ${CLAUDE_PLUGIN_ROOT}
names a per-version cache directory and moves on every update.
- Nothing outside the plugin folder is copied, so a script reading
../shared finds nothing in the cache. A symlink inside the plugin is
kept, one to elsewhere in the marketplace is copied in its place, and
one leading outside the marketplace is skipped. Installed from a local
path, or from a command source in its default copy mode, a plugin
keeps only the symlinks that resolve inside itself and skips the rest
(plugins/host-marketplace, read 2026-11-15).
- A component path that escapes the plugin is rejected, whether
plugin.json or a marketplace entry declares it, loaded in place or
from the cache: a path outside the plugin as written, such as
../shared-utils, or a symlink leading outside it, bar one to another
plugin in the same marketplace. On macOS and Linux a path holding a
backslash anywhere is rejected even inside the plugin, so a component
declared with backslashes loads on Windows only: write forward
slashes, ./commands/deploy.md. Each shows as a
path escapes plugin directory error, and the plugin loads without
that component (plugins/loading, read 2026-11-15). Since 2.1.325,
loading skips and claude plugin validate reports some unsafe paths
and links in the plugin's folder
(Claude Code CHANGELOG.md 2.1.325, read 2026-11-15).
- Git LFS files arrive as pointer files. No clone fetches LFS.
3. Check each component against each surface
A surface skips what it does not load, so a plugin can look complete in
Claude Code and partial in chat. The rules that bite:
- A local MCP server, any command the app starts,
.mcpb included,
is ignored in chat, and loads in Cowork only when the session runs on
the user's computer.
- A remote
http or sse server is listed in chat on the plugin's
Connectors tab and works once the user connects it there. Setting
a plugin's availability adds no connector: an Owner also adds it in
Organization settings > Connectors.
- A server referencing
${user_config.*} is ignored in chat when the
URL holds the reference, and in Cowork when a referenced option has no
default, since Cowork never prompts. Only Claude Code prompts.
- A top-level
bin/ makes chat and Cowork refuse the whole plugin,
and org sync reject it with Plugin contains a top-level bin/ directory while syncing the rest. Keep executables in the plugin's
scripts folder and call ${CLAUDE_PLUGIN_ROOT}/scripts/<name>.
- Agents and hooks load in Cowork and Claude Code, not chat; LSP
servers, output styles and themes load in Claude Code only.
- A plugin's
settings, a root settings.json or the manifest's
settings key, loads in Claude Code only, and only its agent key
still works: 2.1.323 deprecated it, warning at startup, in claude plugin list and in claude plugin validate, and removed the
subagentStatusLine setting (Claude Code CHANGELOG.md, read 2026-11-14).
Each form still ran the plugin's agent as the main thread, its prompt
and model (observed 2026-11-14, 2.1.325). code.claude.com no longer
documents the component, so a page that covers it later wins. Build
no new plugin on it: point users to their own agent setting or
--agent, as the warning does.
The full table is in
references/surfaces-and-org-sync.md.
Chat runs a skill's scripts in claude.ai's code execution sandbox,
so a script tested only on the author's machine is untested there. A
probe of a personal chat read Ubuntu 24.04.5 x86_64, root in
/home/claude, Python 3.13.18, poppler's pdftotext 24.02.0, a POSIX
locale with UTF-8 stdout, and pypi.org answering 200 (observed
2026-11-15); an organization's network setting may differ. What a
Windows author's own run misses:
- The host's tools are not the sandbox's. Git Bash's
pdftotext is
xpdf 4.06 (observed 2026-11-15), whose -v exits 99 where poppler's
exits 0, so pdftotext -v || echo missing calls it missing: probe
with command -v, and the version with
pdftotext -v 2>&1 | head -n 1. Python 3.14 and older write piped
stdout on Windows in the ANSI code page, cp1252 here, unless
PYTHONUTF8=1 (observed 2026-11-15, Python 3.13); 3.15 made UTF-8
the default (PEP 686).
- Chat runs a script as
python3 -I (reported: an organization's
plugin-repo session, 2026-10-27), and -I leaves the script's folder
off sys.path: a script importing its sibling exited 1,
ModuleNotFoundError, under -I, and ran without it (observed
2026-11-15, Python 3.13).
- Test it there: zip the scripts, checks that build their own
inputs and run each script by
sys.executable -I, and a prompt asking
for each tool's version, locale and sys.stdout.encoding, then
every check against its stated result; upload it to a chat with code
execution on. Read each result from the tool call's Response panel,
not the reply, which dropped a line of one output before correcting
itself (observed 2026-11-15). A probe stops first on a marker of the
sandbox, which has /mnt/user-data where Git Bash has no /mnt, so
pasted elsewhere it reports nothing as the sandbox's:
( test -d /mnt/user-data || { echo "not claude.ai's sandbox"; exit 1; }; echo "claude.ai's sandbox" ).
The user's coding-bash.md rule, where their config holds one, has
the measurement; with none, this line is the whole of it.
A Linux container built to the probe's values stands in locally, but a
pass there is not a pass in chat, which still decides a release. Beyond
that probe, nothing here was run in chat or Cowork: say so before
promising a behaviour there.
4. Decide what version does
Choose per release line, after step 1's route:
- Bump
version on every release: users stay on their cached copy
until the string changes, and claude plugin update prints <name> is already at the latest version (<version>). for every push between.
- Omit
version from both plugin.json and the marketplace entry:
each commit is a new computed version, the commit SHA, which also
names the cache directory (12 characters there, observed 2026-10-22).
It still waits for an update or auto-update.
- Never set it in both files.
plugin.json wins without warning at
load, and claude plugin validate reports Entry declares version "<a>" but <path>/plugin.json says "<b>".
What follows from the choice:
claude plugin validate --strict fails a missing version; drop
--strict where version is omitted on purpose.
claude plugin tag needs a version, and checks plugin.json and
the entry agree before it creates <name>--v<version>.
engines["claude-code"] in plugin.json states the Claude Code
versions the plugin supports: a client outside that range does not
install, update or load it, and install and update pick the newest
plugin version that fits
(Claude Code CHANGELOG.md 2.1.323, read 2026-11-15). So a release
that raises the floor leaves an older client on the newest version
still in its range, an inference. No plugin page documents the key or
the range's form (plugins/manifest-reference, read 2026-11-15): leave
the form unstated rather than guess it; a page that covers it wins.
- An org-synced member gets claude.ai's version whatever the file says,
and a local-path user gets the current files.
5. Before an organization sync
The sync is stricter than marketplace add, and two of its steps cannot
be undone. Check with the user, before they open Sync from GitHub:
- The repository is private or internal on github.com and gitlab.com.
- Each plugin source is
github, url, git-subdir, or a path from
./. A bare name under metadata.pluginRoot is rejected as an
unsupported source: write ./plugins/<name>.
- No plugin has a top-level
bin/ (step 3).
- The marketplace's label is its repository's
<owner>/<repo>, and
nothing changes it. The dialog's "Marketplace name" field is a
read-only echo of the repository picked above it, the Marketplaces
tab's ⋯ menu offers no rename, and marketplace.json has no field
for it: its name is the install id, not this label (user-observed on
a Team plan, 2026-10-22 and 2026-11-02; no claude.com page covers it,
org-sync and admin read in full on 2026-11-07; Enterprise is
unseen). Name the repository with the label in
mind; whether renaming it later relabels the marketplace, or breaks
the sync, is untested.
After it syncs:
- Never use Delete source to fix one plugin. It "permanently deletes
every plugin in that marketplace for every member".
- A synced plugin cannot be reverted. Fix it in the repository, push
to the default branch, and Re-sync; meanwhile set its availability
to Not available, and any Enterprise group's own setting too.
- A plugin's
name is permanent. Change the label with displayName;
a rename that cannot wait goes through marketplace.json's renames.
- A developer with both routes gets the managed-settings copy; Claude
Code reports the synced copy as not loaded.
6. Test the install in a throwaway config
Test what users get, not the working tree, and not in the user's own
config. Each Bash call is a fresh shell, so set CLAUDE_CONFIG_DIR on
every command, and use a scratch directory the session's tools can reach:
git clone --branch <branch> <repo-url> <scratch>/clone # committed files only
mkdir <scratch>/config # empty: no plugins, settings or sign-in
CLAUDE_CONFIG_DIR=<scratch>/config claude plugin validate <scratch>/clone
CLAUDE_CONFIG_DIR=<scratch>/config claude plugin validate <scratch>/clone/<plugin-dir>
CLAUDE_CONFIG_DIR=<scratch>/config claude plugin marketplace add <scratch>/clone
CLAUDE_CONFIG_DIR=<scratch>/config claude plugin install <plugin>@<marketplace> --config <key>=<value>
cd <scratch> && CLAUDE_CONFIG_DIR=<scratch>/config claude mcp list
CLAUDE_CONFIG_DIR=<scratch>/config claude plugin details <plugin>@<marketplace>
- Validate each plugin directory too. A marketplace run opens no
skill, hook or MCP file of a plugin kept in another directory.
validate, plugin list and details do not check .lsp.json.
claude plugin validate doesn't read it, and an invalid entry skips
the whole file at load. A copy of a plugin whose .lsp.json had
extensionToLanguage emptied passed both validates, claude plugin list read it ✔ enabled, and details still counted LSP servers (1) (2.1.319, 2026-11-07). /plugin's Errors tab shows
Invalid LSP server config for ".lsp.json".
- Pass
--config for every required option. The shell install never
prompts for userConfig, and prints userConfig options not yet set
when one is missing.
- Run
claude mcp list from the scratch directory, outside the repo,
so a project .mcp.json cannot answer for the plugin's server, which
is listed as plugin:<plugin>:<server>.
claude plugin details shows the component inventory and the
always-on token cost the plugin adds to every session.
That recipe ran twice with no sign-in (2.1.308, 2026-10-22). Added from a
local path, the clone loads in place with no dependency install, which
fits a committed bundle. A plugin relying on step 2's dependency
install needs the copied route: add the pushed branch as
<owner>/<repo>#<branch> instead, so the install runs in the cache.
That variant follows from the loading reference and was not run here.
It is the plugin counterpart of the fresh-session claude mcp list
check in claude-config-scoping.md.
7. Test the plugin's own skills
Step 6 proves the plugin installs and its server connects, not that its
skills change what Claude does. claude plugin eval, Claude Code
2.1.269 or later, runs that:
- Cases live in the plugin's
evals/: a directory per case with a
prompt.md or case.yaml and at least one grader. claude plugin eval init from the plugin root interviews the user and writes them.
- Each case runs three times with the plugin and three without, so
the report's
Δ is what the plugin added. Every run is a full
claude -p child on the user's plan or bill: pass --max-cost-usd.
- No real MCP server starts unless asked. A tool answers from
evals/mocks/<server>/<tool>.md, and a tool without one is not
available; --allow-real-servers runs the real process, as the user,
outside the run's sandbox.
- The report stays local when Claude starts the run; from the user's
own shell, signed in to a claude.ai plan with artifacts, it publishes
as a private artifact unless
--no-publish. Never add
--publish-report unasked.
- A non-interactive run cannot answer the trust prompt and exits 1:
pass
--trust-plugin only for a plugin the user would run.
- A case granted Bash or PowerShell fails on native Windows, which
has no sandbox backend: each run is refused and scores 0, so run those
suites under WSL2.
- Gitignore each suite's
results/: evals/results/ in the
plugin's own .gitignore, or /<plugins dir>/*/evals/results/, such
as /plugins/*/evals/results/, in a marketplace's root one, where a
bare evals/results/ matches only a root evals/, as a pattern with
a slash before its end is relative to its .gitignore (git-scm.com
gitignore, read 2026-11-14).
The case format, graders, mocks and options are in
references/plugin-eval.md.
8. Constraints
- Name the route before advising on
version or updates. The same
advice is right on one route and a trap on the next.
- Never test in the user's real config. Install into a throwaway
CLAUDE_CONFIG_DIR, from committed files.
- Never promise chat or Cowork behaviour from a Claude Code test.
- Never recommend Delete source to fix a synced plugin or its name.
- The repository's name, which the org sync shows as the marketplace's
label, and the plugin
name are the user's to choose,
before the sync; ask rather than default.
- Bound every eval run with
--max-cost-usd, and publish no report
the user did not ask to publish.
1---2name: ship-plugin3model: inherit # inert anyway: a paths: skill has no cold slash route4effort: xhigh5disable-model-invocation: false6description: "Ships a Claude Code plugin so it installs and runs where its users are. A plugin gets no build step, so a .mcp.json pointing at a gitignored dist/ installs cleanly and its server never starts; chat, Cowork and Claude Code each load a different part of a plugin, and a top-level bin/ makes chat, Cowork and org sync refuse it; version means something different for a local-path marketplace, one added by source and one synced to a claude.ai organization; a synced marketplace is labelled with its repository's owner/repo and nothing renames it, and Delete source removes every plugin for every member. Ends with an install test in a throwaway CLAUDE_CONFIG_DIR (claude plugin validate, install --config, claude mcp list) and claude plugin eval for the plugin's own skills. Not for a mod, which plugin-authoring makes."7when_to_use: "Use when writing or changing a plugin.json or marketplace.json, turning an MCP server or a set of skills into a plugin, releasing or versioning one, syncing a marketplace to a claude.ai organization, or when a plugin's server never connects or shows no tools, an update changes nothing, or chat ignores part of a plugin."8paths:9 - "**/.claude-plugin/*.json"10metadata:11 source: https://skillmd.com/skills/wardawgmalvicious/ship-plugin12---1314# Ship a plugin: from a repo to an install that runs1516A plugin that validates can still fail every user it reaches: its server17never starts, chat skips half of it, an update never arrives, or an18organization's members see it under a name nobody chose. Each failure is19silent, and each depends on **the route the plugin travels**. This skill20names the route first, then checks what ships, what each surface loads,21what `version` does, what an org sync fixes for good, and how to test22the install and the plugin's own skills without the user's real config.2324It does not teach plugin layout or components: the Claude Code docs'25`plugins/components` page and `claude plugin validate` own those. A mod,26a pane or a hook module that changes Claude Code's own interface, is27`plugin-authoring`'s. Submitting to Anthropic's directory is out of28scope.2930This skill is path-scoped to `.claude-plugin/*.json`, so it is listed31only once a session reads or writes a `plugin.json` or32`marketplace.json` in its working directory. A plugin's own repository33holds both; anywhere else it costs nothing.3435Every claim below was read in the Claude Code and claude.com docs on362026-10-22 against Claude Code 2.1.308, unless it says otherwise.37Past it, its `references/`, then the live page: code.claude.com by the38`claude-code-docs` MCP server or39`curl -s https://code.claude.com/docs/en/<page>.md`, and claude.com,40which that server does not cover, by41`curl -s https://claude.com/docs/<path>.md`. A live page that42contradicts a line here wins: say so, act on the page, and route the43fix by `capture-learning`, bar a dated measured line that names the44page it overrules and the call that measured it, which a page changed45since its date sends back to re-measure. An observed claim is cited or46marked pending a doc check, and stands, marked observed, only where no47page covers it, as step 5's label claim does: silence is no48contradiction, and a page that later covers it wins.4950## 1. Name the route5152Ask which route the plugin travels, or read it from the repo: a53`marketplace.json` alone says little, since one repository can serve54every route at once.5556| Route | Who gets it | What `version` does | How a change arrives |57| --- | --- | --- | --- |58| Local-path marketplace, `marketplace add ./path` | whoever reads the path: the author, or a team on a shared directory | nothing: current files load each session | the next session or `/reload-plugins`; no dependency install |59| Marketplace added by source: GitHub, git URL | anyone who can clone it with credentials already on their machine | `plugin.json`, then the entry, else the commit SHA | `claude plugin update`; auto-update is off until a user or admin turns it on; none past a `ref` pinned to a commit (below) |60| claude.ai organization sync | members in chat, in Cowork, and in Claude Code sessions signed in to that account | not read: claude.ai records its own | a push to the default branch with **Sync automatically** on, or **Re-sync**; tags are not read |61| Claude Code managed settings | every machine that receives them | as added by source | auto-update, when managed settings turn it on; none past a `ref` pinned to a commit (below) |62| A repo's committed settings: `extraKnownMarketplaces` and `enabledPlugins` in its `.claude/settings.json` | each contributor who trusts the folder and installs the plugin in that clone (below) | as for the marketplace's route | as for the marketplace's route |6364**A local-path test proves the least.** The plugin loads in place from65the source directory, with no copy and no dependency install, so it sees66whatever the author's build left there. Every other route copies the67plugin into the cache and sees only what was committed.6869**A repo's committed `enabledPlugins` installs nothing.** Each70contributor runs, once per clone, or at `--scope user` for every71project:7273```bash74claude plugin install <name>@<marketplace> --scope project75```7677Until then the plugin does not load at session start; with its78marketplace registered, `/plugin`'s **Errors** tab shows `not cached` or79`Plugin "<name>" is enabled in project settings but isn't installed here`,80and with neither message, the marketplace is missing: add it first.81The repo's82`extraKnownMarketplaces` registers nothing in a folder the contributor83has not trusted, without a message. Two kinds of plugin skip the84install: one in a seed directory (plugins/org § "Seed containers and85CI"), and a relative-path one: listed in a marketplace added from a86local path, it loads at session start; in a git marketplace,87`/reload-plugins` loads it for that session alone, and88`CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1` for one `-p` run (plugins/loading,89plugins/org, read 2026-11-14).9091**A `ref` set to the full lowercase SHA of a commit on a branch or tag92holds a marketplace there**: a93`github` or `git` source then moves on neither a refresh nor an94auto-update, so an admin can pin a reviewed commit. Update Claude Code95on every machine first, since a client before v2.1.324 cannot load a96marketplace pinned so. A reserved name such as97`claude-plugins-official` refuses a SHA, and a plugin entry with its98own remote source still updates: pin that entry too, by its `sha`99(plugins/marketplace-reference, read 2026-11-14).100101## 2. Ship what runs102103**Nothing builds a plugin.** Claude Code's only install step is a Node.js104dependency install into the cached copy, and it runs only when the105plugin root holds both a `package.json` and a supported lockfile. Its106limits, each checked against the `plugins/loading` page on 2026-11-07:107108- the lockfile is `npm-shrinkwrap.json` or `package-lock.json` at109 `lockfileVersion` 2 or 3, or `bun.lock` at 2 or lower; `yarn.lock`,110 `pnpm-lock.yaml` and `bun.lockb` get no install111- every dependency is a registry package pinned exactly, fetched over112 `https` unless from the installing user's own default npm registry; a113 git, GitHub, folder, workspace or linked dependency gets no install114- frozen resolution: the lockfile's exact versions, and no install when115 `package.json` and the lockfile list different dependencies116- a separate install folder holding only a copy of the dependency list,117 so the plugin's `.npmrc`, `.env` and `bunfig.toml` are not read (so a118 registry or token set there cannot reach the install, an inference)119- `--ignore-scripts`, so nothing compiles, native modules included120- npm `overrides` or Bun `patchedDependencies` get no install121- 60 seconds, then it counts as failed122- "You can't turn the automatic install off"123124So a `.mcp.json` pointing at a gitignored `dist/` installs cleanly and125its server never starts. A plugin whose install fails or is skipped126still loads; `/plugin` and `claude plugin list` note the missing127`node_modules`. An update the user starts can retry an install that128failed or timed out, even at an unchanged version; one skipped for its129lockfile or a missing package manager stays skipped.130131Pick one way out:1321331. **Commit a bundle.** A single-file bundle in a plugin folder that134 holds no `package.json`, so no install runs, with the repo's test135 script regenerating it so a stale bundle shows as a diff. One session136 reached `✔ Connected` from a fresh clone this way, with an esbuild137 CommonJS bundle (observed once, 2.1.308, 2026-10-22).1382. **Ship JavaScript and an exact npm lockfile**, registry dependencies139 only, and let the install run. An npm lockfile reaches the most users;140 Claude Code runs that lockfile's package manager from the user's141 `PATH` and tries no other.1423. **Install from a `SessionStart` hook into `${CLAUDE_PLUGIN_DATA}`**,143 for what the install cannot provide: lifecycle scripts, Python, Yarn144 or pnpm, git dependencies. The `plugins/components` page has the hook.145146Then, whatever the way:147148- **Durable files go in `${CLAUDE_PLUGIN_DATA}`.** `${CLAUDE_PLUGIN_ROOT}`149 names a per-version cache directory and moves on every update.150- **Nothing outside the plugin folder is copied**, so a script reading151 `../shared` finds nothing in the cache. A symlink inside the plugin is152 kept, one to elsewhere in the marketplace is copied in its place, and153 one leading outside the marketplace is skipped. Installed from a local154 path, or from a `command` source in its default `copy` mode, a plugin155 keeps only the symlinks that resolve inside itself and skips the rest156 (plugins/host-marketplace, read 2026-11-15).157- **A component path that escapes the plugin is rejected**, whether158 `plugin.json` or a marketplace entry declares it, loaded in place or159 from the cache: a path outside the plugin as written, such as160 `../shared-utils`, or a symlink leading outside it, bar one to another161 plugin in the same marketplace. On macOS and Linux a path holding a162 backslash anywhere is rejected even inside the plugin, so a component163 declared with backslashes loads on Windows only: write forward164 slashes, `./commands/deploy.md`. Each shows as a165 `path escapes plugin directory` error, and the plugin loads without166 that component (plugins/loading, read 2026-11-15). Since 2.1.325,167 loading skips and `claude plugin validate` reports some unsafe paths168 and links in the plugin's folder169 (Claude Code `CHANGELOG.md` 2.1.325, read 2026-11-15).170- **Git LFS files arrive as pointer files.** No clone fetches LFS.171172## 3. Check each component against each surface173174A surface skips what it does not load, so a plugin can look complete in175Claude Code and partial in chat. The rules that bite:176177- **A local MCP server**, any command the app starts, `.mcpb` included,178 is ignored in chat, and loads in Cowork only when the session runs on179 the user's computer.180- **A remote `http` or `sse` server** is listed in chat on the plugin's181 **Connectors** tab and works once the user connects it there. Setting182 a plugin's availability adds no connector: an Owner also adds it in183 **Organization settings > Connectors**.184- **A server referencing `${user_config.*}`** is ignored in chat when the185 URL holds the reference, and in Cowork when a referenced option has no186 default, since Cowork never prompts. Only Claude Code prompts.187- **A top-level `bin/`** makes chat and Cowork refuse the whole plugin,188 and org sync reject it with `Plugin contains a top-level bin/189 directory` while syncing the rest. Keep executables in the plugin's190 scripts folder and call `${CLAUDE_PLUGIN_ROOT}/scripts/<name>`.191- **Agents and hooks** load in Cowork and Claude Code, not chat; LSP192 servers, output styles and themes load in Claude Code only.193- **A plugin's `settings`**, a root `settings.json` or the manifest's194 `settings` key, loads in Claude Code only, and only its `agent` key195 still works: 2.1.323 deprecated it, warning at startup, in `claude196 plugin list` and in `claude plugin validate`, and removed the197 `subagentStatusLine` setting (Claude Code `CHANGELOG.md`, read 2026-11-14).198 Each form still ran the plugin's agent as the main thread, its prompt199 and model (observed 2026-11-14, 2.1.325). code.claude.com no longer200 documents the component, so a page that covers it later wins. Build201 no new plugin on it: point users to their own `agent` setting or202 `--agent`, as the warning does.203204The full table is in205[references/surfaces-and-org-sync.md](references/surfaces-and-org-sync.md).206207**Chat runs a skill's scripts in claude.ai's code execution sandbox**,208so a script tested only on the author's machine is untested there. A209probe of a personal chat read Ubuntu 24.04.5 x86_64, root in210`/home/claude`, Python 3.13.18, poppler's `pdftotext` 24.02.0, a POSIX211locale with UTF-8 stdout, and `pypi.org` answering 200 (observed2122026-11-15); an organization's network setting may differ. What a213Windows author's own run misses:214215- **The host's tools are not the sandbox's.** Git Bash's `pdftotext` is216 xpdf 4.06 (observed 2026-11-15), whose `-v` exits 99 where poppler's217 exits 0, so `pdftotext -v || echo missing` calls it missing: probe218 with `command -v`, and the version with219 `pdftotext -v 2>&1 | head -n 1`. Python 3.14 and older write piped220 stdout on Windows in the ANSI code page, cp1252 here, unless221 `PYTHONUTF8=1` (observed 2026-11-15, Python 3.13); 3.15 made UTF-8222 the default (PEP 686).223- **Chat runs a script as `python3 -I`** (reported: an organization's224 plugin-repo session, 2026-10-27), and `-I` leaves the script's folder225 off `sys.path`: a script importing its sibling exited 1,226 `ModuleNotFoundError`, under `-I`, and ran without it (observed227 2026-11-15, Python 3.13).228- **Test it there**: zip the scripts, checks that build their own229 inputs and run each script by `sys.executable -I`, and a prompt asking230 for each tool's version, `locale` and `sys.stdout.encoding`, then231 every check against its stated result; upload it to a chat with code232 execution on. Read each result from the tool call's Response panel,233 not the reply, which dropped a line of one output before correcting234 itself (observed 2026-11-15). A probe stops first on a marker of the235 sandbox, which has `/mnt/user-data` where Git Bash has no `/mnt`, so236 pasted elsewhere it reports nothing as the sandbox's:237 `( test -d /mnt/user-data || { echo "not claude.ai's sandbox"; exit 1; }; echo "claude.ai's sandbox" )`.238 The user's `coding-bash.md` rule, where their config holds one, has239 the measurement; with none, this line is the whole of it.240241A Linux container built to the probe's values stands in locally, but a242pass there is not a pass in chat, which still decides a release. Beyond243that probe, nothing here was run in chat or Cowork: say so before244promising a behaviour there.245246## 4. Decide what `version` does247248Choose per release line, after step 1's route:249250- **Bump `version` on every release**: users stay on their cached copy251 until the string changes, and `claude plugin update` prints `<name> is252 already at the latest version (<version>).` for every push between.253- **Omit `version`** from both `plugin.json` and the marketplace entry:254 each commit is a new computed version, the commit SHA, which also255 names the cache directory (12 characters there, observed 2026-10-22).256 It still waits for an update or auto-update.257- **Never set it in both files.** `plugin.json` wins without warning at258 load, and `claude plugin validate` reports `Entry declares version259 "<a>" but <path>/plugin.json says "<b>"`.260261What follows from the choice:262263- `claude plugin validate --strict` fails a missing `version`; drop264 `--strict` where `version` is omitted on purpose.265- `claude plugin tag` needs a `version`, and checks `plugin.json` and266 the entry agree before it creates `<name>--v<version>`.267- `engines["claude-code"]` in `plugin.json` states the Claude Code268 versions the plugin supports: a client outside that range does not269 install, update or load it, and install and update pick the newest270 plugin version that fits271 (Claude Code `CHANGELOG.md` 2.1.323, read 2026-11-15). So a release272 that raises the floor leaves an older client on the newest version273 still in its range, an inference. No plugin page documents the key or274 the range's form (plugins/manifest-reference, read 2026-11-15): leave275 the form unstated rather than guess it; a page that covers it wins.276- An org-synced member gets claude.ai's version whatever the file says,277 and a local-path user gets the current files.278279## 5. Before an organization sync280281The sync is stricter than `marketplace add`, and two of its steps cannot282be undone. Check with the user, before they open **Sync from GitHub**:283284- **The repository is private or internal** on github.com and gitlab.com.285- **Each plugin source is `github`, `url`, `git-subdir`, or a path from286 `./`.** A bare name under `metadata.pluginRoot` is rejected as an287 unsupported source: write `./plugins/<name>`.288- **No plugin has a top-level `bin/`** (step 3).289- **The marketplace's label is its repository's `<owner>/<repo>`, and290 nothing changes it.** The dialog's "Marketplace name" field is a291 read-only echo of the repository picked above it, the Marketplaces292 tab's `⋯` menu offers no rename, and `marketplace.json` has no field293 for it: its `name` is the install id, not this label (user-observed on294 a Team plan, 2026-10-22 and 2026-11-02; no claude.com page covers it,295 `org-sync` and `admin` read in full on 2026-11-07; Enterprise is296 unseen). Name the repository with the label in297 mind; whether renaming it later relabels the marketplace, or breaks298 the sync, is untested.299300After it syncs:301302- **Never use Delete source to fix one plugin.** It "permanently deletes303 every plugin in that marketplace for every member".304- **A synced plugin cannot be reverted.** Fix it in the repository, push305 to the default branch, and **Re-sync**; meanwhile set its availability306 to **Not available**, and any Enterprise group's own setting too.307- **A plugin's `name` is permanent.** Change the label with `displayName`;308 a rename that cannot wait goes through `marketplace.json`'s `renames`.309- **A developer with both routes** gets the managed-settings copy; Claude310 Code reports the synced copy as not loaded.311312## 6. Test the install in a throwaway config313314Test what users get, not the working tree, and not in the user's own315config. Each Bash call is a fresh shell, so set `CLAUDE_CONFIG_DIR` on316every command, and use a scratch directory the session's tools can reach:317318```bash319git clone --branch <branch> <repo-url> <scratch>/clone # committed files only320mkdir <scratch>/config # empty: no plugins, settings or sign-in321CLAUDE_CONFIG_DIR=<scratch>/config claude plugin validate <scratch>/clone322CLAUDE_CONFIG_DIR=<scratch>/config claude plugin validate <scratch>/clone/<plugin-dir>323CLAUDE_CONFIG_DIR=<scratch>/config claude plugin marketplace add <scratch>/clone324CLAUDE_CONFIG_DIR=<scratch>/config claude plugin install <plugin>@<marketplace> --config <key>=<value>325cd <scratch> && CLAUDE_CONFIG_DIR=<scratch>/config claude mcp list326CLAUDE_CONFIG_DIR=<scratch>/config claude plugin details <plugin>@<marketplace>327```328329- **Validate each plugin directory too.** A marketplace run opens no330 skill, hook or MCP file of a plugin kept in another directory.331- **`validate`, `plugin list` and `details` do not check `.lsp.json`.**332 `claude plugin validate` doesn't read it, and an invalid entry skips333 the whole file at load. A copy of a plugin whose `.lsp.json` had334 `extensionToLanguage` emptied passed both validates, `claude plugin335 list` read it `✔ enabled`, and `details` still counted `LSP servers336 (1)` (2.1.319, 2026-11-07). `/plugin`'s **Errors** tab shows337 `Invalid LSP server config for ".lsp.json"`.338- **Pass `--config` for every required option.** The shell install never339 prompts for `userConfig`, and prints `userConfig options not yet set`340 when one is missing.341- **Run `claude mcp list` from the scratch directory**, outside the repo,342 so a project `.mcp.json` cannot answer for the plugin's server, which343 is listed as `plugin:<plugin>:<server>`.344- **`claude plugin details`** shows the component inventory and the345 always-on token cost the plugin adds to every session.346347That recipe ran twice with no sign-in (2.1.308, 2026-10-22). Added from a348local path, the clone loads in place with no dependency install, which349fits a committed bundle. **A plugin relying on step 2's dependency350install needs the copied route**: add the pushed branch as351`<owner>/<repo>#<branch>` instead, so the install runs in the cache.352That variant follows from the loading reference and was not run here.353354It is the plugin counterpart of the fresh-session `claude mcp list`355check in `claude-config-scoping.md`.356357## 7. Test the plugin's own skills358359Step 6 proves the plugin installs and its server connects, not that its360skills change what Claude does. `claude plugin eval`, Claude Code3612.1.269 or later, runs that:362363- **Cases live in the plugin's `evals/`**: a directory per case with a364 `prompt.md` or `case.yaml` and at least one grader. `claude plugin eval365 init` from the plugin root interviews the user and writes them.366- **Each case runs three times with the plugin and three without**, so367 the report's `Δ` is what the plugin added. Every run is a full368 `claude -p` child on the user's plan or bill: pass `--max-cost-usd`.369- **No real MCP server starts** unless asked. A tool answers from370 `evals/mocks/<server>/<tool>.md`, and a tool without one is not371 available; `--allow-real-servers` runs the real process, as the user,372 outside the run's sandbox.373- **The report stays local when Claude starts the run**; from the user's374 own shell, signed in to a claude.ai plan with artifacts, it publishes375 as a private artifact unless `--no-publish`. Never add376 `--publish-report` unasked.377- **A non-interactive run cannot answer the trust prompt** and exits 1:378 pass `--trust-plugin` only for a plugin the user would run.379- **A case granted Bash or PowerShell fails on native Windows**, which380 has no sandbox backend: each run is refused and scores 0, so run those381 suites under WSL2.382- **Gitignore each suite's `results/`**: `evals/results/` in the383 plugin's own `.gitignore`, or `/<plugins dir>/*/evals/results/`, such384 as `/plugins/*/evals/results/`, in a marketplace's root one, where a385 bare `evals/results/` matches only a root `evals/`, as a pattern with386 a slash before its end is relative to its `.gitignore` (git-scm.com387 `gitignore`, read 2026-11-14).388389The case format, graders, mocks and options are in390[references/plugin-eval.md](references/plugin-eval.md).391392## 8. Constraints393394- **Name the route before advising on `version` or updates.** The same395 advice is right on one route and a trap on the next.396- **Never test in the user's real config.** Install into a throwaway397 `CLAUDE_CONFIG_DIR`, from committed files.398- **Never promise chat or Cowork behaviour** from a Claude Code test.399- **Never recommend Delete source** to fix a synced plugin or its name.400- **The repository's name, which the org sync shows as the marketplace's401 label, and the plugin `name` are the user's to choose**,402 before the sync; ask rather than default.403- **Bound every eval run** with `--max-cost-usd`, and publish no report404 the user did not ask to publish.