Home Docs Claude Code CLI 22 Oct 2026

One change · claude-code

Marketplace reference changedplugins/marketplace-reference

Nearest release: v2.1.307, published 3 hours before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.

Upstream edited this page at 22 Oct 2026 00:13 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 22 Oct 2026 18:07 UTC.

Upstream edited 22 Oct 2026 00:13 UTC

Recorded here 22 Oct 2026 18:07 UTC

Lines+32added

Lines−32removed

From line 12 where the diff opens

First seen 25 Sep 2026 this site's first read of the page

Recorded edits19to this page, all time

The whole hunk

from line 12, old and new numbered

lines

from line 12

1212>

1313> These cases are covered on other pages:

1414>

15> * **Building or hosting a marketplace**: see [Create a marketplace](/docs/en/plugins/create-marketplace) and [Host and maintain a marketplace](/docs/en/plugins/host-marketplace)

16> * **Allowlist and blocklist recipes**: see [Manage plugins for your organization](/docs/en/plugins/org)

15> * **Building or hosting a marketplace**: see [Create a marketplace](/docs/en/plugins/create-marketplace.md) and [Host and maintain a marketplace](/docs/en/plugins/host-marketplace.md)

16> * **Allowlist and blocklist recipes**: see [Manage plugins for your organization](/docs/en/plugins/org.md)

1717

1818Find the section for what you're writing or reading:

1919

from line 49

4949

5050When a registered marketplace stops loading because its name imitates an official one, `claude plugin list` and `/plugin` report `Claude Code refuses the marketplace name "<name>"`. The message tells you to remove the marketplace. Removing it also uninstalls its plugins and deletes their data, options, and secrets. This named refusal message requires Claude Code v2.1.282 or later.

5151

52If a settings file declares the marketplace inline, the message tells you to rename its entry before you remove the old name. For the steps, see [Claude Code refuses the marketplace name](/docs/en/errors#claude-code-refuses-the-marketplace-name). The message lists them in Claude Code v2.1.292 or later.

52If a settings file declares the marketplace inline, the message tells you to rename its entry before you remove the old name. For the steps, see [Claude Code refuses the marketplace name](/docs/en/errors.md#claude-code-refuses-the-marketplace-name). The message lists them in Claude Code v2.1.292 or later.

5353

5454## Top-level fields

5555

from line 57

5757

5858| Field | Type | Description |

5959| :- | :- | :- |

60| `name` | string | Marketplace identifier: letters, digits, `.`, `_`, and `-`, starting with a letter or digit, and no `..`. `claude plugin validate` fails any other name, because Claude Code [can't install plugins from a marketplace that uses one](/docs/en/plugins/troubleshooting#cannot-install-plugins-from-a-marketplace-with-this-name). Users type the name after `@` in a [plugin id](/docs/en/plugins/loading#find-where-a-plugin-came-from) such as `my-plugin@my-marketplace` when they install a plugin. See [Reserved names](#reserved-names) |

60| `name` | string | Marketplace identifier: letters, digits, `.`, `_`, and `-`, starting with a letter or digit, and no `..`. `claude plugin validate` fails any other name, because Claude Code [can't install plugins from a marketplace that uses one](/docs/en/plugins/troubleshooting.md#cannot-install-plugins-from-a-marketplace-with-this-name). Users type the name after `@` in a [plugin id](/docs/en/plugins/loading.md#find-where-a-plugin-came-from) such as `my-plugin@my-marketplace` when they install a plugin. See [Reserved names](#reserved-names) |

6161| `owner` | object | Maintainer information. `name` is required; `email` and `url` are optional |

6262| `plugins` | array | [Plugin entries](#plugin-entries). Each entry is validated on its own, so one invalid entry doesn't fail the marketplace |

6363| `$schema` | string | JSON Schema URL for editor autocomplete. Ignored at load time |

from line 65

6565| `version` | string | Marketplace manifest version |

6666| `metadata.description`, `metadata.version` | string | Alternate location for `description` and `version` |

6767| `metadata.pluginRoot` | string | Directory that bare plugin source names resolve under. See [Relative path plugin source](#relative-path-plugin-source). Requires Claude Code v2.1.239 or later |

68| `forceRemoveDeletedPlugins` | boolean | When `true`, a plugin you remove from `plugins` is uninstalled on users' machines. See [Host and maintain a marketplace](/docs/en/plugins/host-marketplace) |

69| `allowCrossMarketplaceDependenciesOn` | array of strings | Marketplace names whose plugins may be installed as dependencies of this marketplace's plugins. When you install a plugin, only the list in that plugin's own marketplace applies, for its whole dependency chain. See [Plugin dependencies](/docs/en/plugins/dependencies) |

70| `renames` | object | Map from a former plugin `name` to its current name, or to `null` for a plugin you removed. See [Host and maintain a marketplace](/docs/en/plugins/host-marketplace) |

70| `renames` | object | Map from a former plugin `name` to its current name, or to `null` for a plugin you removed. See [Host and maintain a marketplace](/docs/en/plugins/host-marketplace.md) |

7171

7272## Plugin entries

7373

7474Each object in the top-level `plugins` array of `marketplace.json` names a plugin and says where to fetch it. `name` and `source` are required.

7575

76Apart from the [directory listing fields](/docs/en/plugins/manifest-reference#directory-listing-fields), an entry also accepts every [`plugin.json` field](/docs/en/plugins/manifest-reference), such as `description`, `version`, `author`, `commands`, and `hooks`. For when those fields apply, see [How an entry combines with plugin.json](#entry-and-plugin-json).

76Apart from the [directory listing fields](/docs/en/plugins/manifest-reference.md#directory-listing-fields), an entry also accepts every [`plugin.json` field](/docs/en/plugins/manifest-reference), such as `description`, `version`, `author`, `commands`, and `hooks`. For when those fields apply, see [How an entry combines with plugin.json](#entry-and-plugin-json).

7777

7878The table lists the entry's own fields and the manifest fields whose meaning changes in an entry.

7979

from line 82

8282| `name` | string | Plugin identifier: letters, digits, `.`, `_`, and `-`, starting with a letter or digit. `claude plugin validate` fails other names, which Claude Code can't install. Users type it before `@` when they install, even when the plugin's own `plugin.json` sets a different `name` |

8383| `source` | string or object | Where to fetch the plugin. See [Plugin sources](#plugin-sources) |

8484| `description` | string | Shown in [`/plugin`](/docs/en/plugins/install) listings and details |

85| `version` | string | Version string for the plugin. When `plugin.json` also sets `version`, `plugin.json` takes precedence and `claude plugin validate` warns. See [Plugin loading reference](/docs/en/plugins/loading) |

8686| `category` | string | Free-form category for organizing the catalog |

8787| `tags` | array of strings | Free-form tags for search |

8888| `strict` | boolean | Default `true`. Whether `plugin.json` is the definitive source for the plugin's components. See [Strict mode](#strict-mode) |

89| `relevance` | object | Signals that tell Claude Code when to suggest the plugin. See [Recommend plugins for your org](/docs/en/plugins/relevance) |

90| `dependencies` | array | Plugins that must be enabled for this one to work. Each item is `"name"`, `"name@marketplace"`, or an object. See [Plugin dependencies](/docs/en/plugins/dependencies) |

89| `relevance` | object | Signals that tell Claude Code when to suggest the plugin. See [Recommend plugins for your org](/docs/en/plugins/relevance.md) |

90| `dependencies` | array | Plugins that must be enabled for this one to work. Each item is `"name"`, `"name@marketplace"`, or an object. See [Plugin dependencies](/docs/en/plugins/dependencies.md) |

9191| `defaultEnabled` | boolean | Default `true`. Whether the plugin starts enabled when the user hasn't set it in [`enabledPlugins`](/docs/en/settings-reference#enabledplugins). The entry value takes precedence over `plugin.json` |

9292| `displayName` | string | Human-readable name shown in the UI. When neither the entry nor the plugin's `plugin.json` sets one, users see the plugin's `name` |

9393| `metadata` | object | Free-form object for your own fields. Claude Code doesn't read it. Requires Claude Code v2.1.222 or later |

9494| `headers` | object | HTTP headers Claude Code sends when it downloads this entry's [archive](#archive-plugin-source). A header set here replaces a header of the same name from the marketplace source's [`headers`](#fields-by-type). Requires Claude Code v2.1.238 or later |

95| `headersHelper` | string | Command that prints this entry's archive-download headers as one JSON object, for a credential that expires. The entry must also set [`"strict": false`](#strict-mode). Requires Claude Code v2.1.238 or later. See [Authenticate archive downloads](/docs/en/plugins/host-marketplace#authenticate-archive-downloads) |

9696

9797### How an entry combines with plugin.json

9898

from line 121

122122| :- | :- | :- | :- |

123123| any | absent | any | The entry is the manifest |

124| `true`, the default | present | any | `plugin.json` is the authority. Claude Code appends the entry's component fields to it, except `hooks`, whose matchers [replace the manifest's per event](/docs/en/plugins/manifest-reference#how-entry-fields-combine-with-plugin-json) |

127127

from line 150

150150* **`ref`**: a branch or tag. Defaults to the repository's default branch.

151151* **`sha`**: a full 40-character lowercase commit SHA. When you set both `ref` and `sha`, Claude Code checks out `sha`. On most git hosts, including GitHub, GitLab, and Bitbucket, this means installation succeeds even if the branch or tag named by `ref` has since been deleted upstream, as long as the commit is still reachable from the repository. Some servers, such as AWS CodeCommit, don't support fetching commits by SHA. On those servers the `ref` must still exist and the pinned commit must be reachable from it.

152152

153For how each type is fetched, cached, and versioned, see [Plugin loading reference](/docs/en/plugins/loading).

153For how each type is fetched, cached, and versioned, see [Plugin loading reference](/docs/en/plugins/loading.md).

154154

155155### Relative path plugin source

156156

from line 232

232232* `version`: a version, a semver range, or a dist-tag, used when `package` is a package name with no version appended. Omit it to fetch `latest`

233233* `registry`: a registry URL for a package that isn't on the default registry

234234

235Claude Code fetches the package with your npm client. The package's install scripts, such as `preinstall` or `postinstall`, never run, and its dependencies aren't installed during the fetch. If the package has a supported lockfile beside its `package.json`, Claude Code installs those [Node.js package dependencies](/docs/en/plugins/loading#node-js-package-dependencies) in a separate step, also with scripts disabled.

235Claude Code fetches the package with your npm client. The package's install scripts, such as `preinstall` or `postinstall`, never run, and its dependencies aren't installed during the fetch. If the package has a supported lockfile beside its `package.json`, Claude Code installs those [Node.js package dependencies](/docs/en/plugins/loading.md#node-js-package-dependencies) in a separate step, also with scripts disabled.

236236

237237Claude Code checks the `package` value before fetching anything. A refused value fails the install with a message that names the value and the reason. The refused values include:

238238

from line 256

256256

257257### archive plugin source

258258

259`url` must use `https://` and can't point at a loopback, link-local, or cloud-metadata host. For the size, timeout, redirect, and extraction limits on the download, see [Stay within the download limits for hosted files](/docs/en/plugins/host-marketplace#stay-within-the-download-limits-for-hosted-files).

259`url` must use `https://` and can't point at a loopback, link-local, or cloud-metadata host. For the size, timeout, redirect, and extraction limits on the download, see [Stay within the download limits for hosted files](/docs/en/plugins/host-marketplace.md#stay-within-the-download-limits-for-hosted-files).

260260

261261The plugin root may be at the top of the zip or one directory down.

262262

from line 275

275275

276276### command plugin source

277277

278Use a `command` source when a tool installed on the user's machine produces the plugin directory, such as an IDE that renders its plugin for the toolchain the user has selected. Claude Code runs the command when the user installs or updates the plugin, and [again once per session](/docs/en/plugins/loading#when-a-command-source-re-runs), so users get the tool's changed output without reinstalling.

278Use a `command` source when a tool installed on the user's machine produces the plugin directory, such as an IDE that renders its plugin for the toolchain the user has selected. Claude Code runs the command when the user installs or updates the plugin, and [again once per session](/docs/en/plugins/loading.md#when-a-command-source-re-runs), so users get the tool's changed output without reinstalling.

279279

280280A `command` source takes these fields:

281281

from line 294

294294}

295295```

296296

297For how users accept the command, see [Install from your shell](/docs/en/plugins/install#install-from-your-shell). For what users see after you change it, see [Change the command of a command source](/docs/en/plugins/host-marketplace#change-the-command-of-a-command-source). Administrators turn command sources off with [`disableCommandPluginSources`](/docs/en/settings-reference#disablecommandpluginsources).

297For how users accept the command, see [Install from your shell](/docs/en/plugins/install.md#install-from-your-shell). For what users see after you change it, see [Change the command of a command source](/docs/en/plugins/host-marketplace.md#change-the-command-of-a-command-source). Administrators turn command sources off with [`disableCommandPluginSources`](/docs/en/settings-reference#disablecommandpluginsources).

298298

299299#### What the command must do

300300

from line 317

317317

318318`mode` decides whether Claude Code copies the printed directory or uses it in place:

319319

320* **`copy`**: Claude Code copies the directory into the plugin cache and derives the [plugin version](/docs/en/plugins/loading#how-claude-code-computes-the-version) from a hash of the copied files. Your tool can delete or rewrite the directory after the command exits. A re-run that produces identical files counts as up to date.

320* **`copy`**: Claude Code copies the directory into the plugin cache and derives the [plugin version](/docs/en/plugins/loading.md#how-claude-code-computes-the-version) from a hash of the copied files. Your tool can delete or rewrite the directory after the command exits. A re-run that produces identical files counts as up to date.

321321* **`link`**: Claude Code fills the plugin's cache entry with a link to each top-level entry of the printed directory and loads the files in place. Nothing is copied, file contents aren't hashed, and the size limits don't apply. Use it for a directory too large to copy, such as a rendered SDK export.

322322

323323A link-mode plugin has these requirements:

from line 325

325325* **Keep the directory in place**: Claude Code loads the plugin through the links at every startup, so the printed directory must stay where it is for as long as the plugin stays installed.

326326* **Print a different path to signal new content**: the version comes from the printed directory's real path and its top-level entries, not from the files inside them.

327327* **Keep top-level symlinks inside the directory**: the install fails if a top-level entry is a symlink that points outside the printed directory.

328* **Include `node_modules`**: Claude Code skips the [Node.js package dependency install](/docs/en/plugins/loading#node-js-package-dependencies) for a link-mode plugin, so print a directory that already contains the packages the plugin needs.

328* **Include `node_modules`**: Claude Code skips the [Node.js package dependency install](/docs/en/plugins/loading.md#node-js-package-dependencies) for a link-mode plugin, so print a directory that already contains the packages the plugin needs.

329329* **Sessions started inside the directory**: a session started in the printed directory or anywhere below it doesn't load the plugin.

330330* **Not on Windows**: Claude Code refuses to install a link-mode plugin on Windows. Declare `"mode": "copy"` there.

331331

from line 356

359| `skills-dir` | none | Not produced | Fails to load: `Unsupported marketplace source type` | Allows [skills-directory plugins](/docs/en/plugins/org#keep-skills-directory-plugins-loading). See [Source values valid only in policy lists](#source-values-valid-only-in-policy-lists) | Stops skills-directory plugins from loading |

359| `skills-dir` | none | Not produced | Fails to load: `Unsupported marketplace source type` | Allows [skills-directory plugins](/docs/en/plugins/org.md#keep-skills-directory-plugins-loading). See [Source values valid only in policy lists](#source-values-valid-only-in-policy-lists) | Stops skills-directory plugins from loading |

362362

from line 366

366366

367367| Field | Types | Description |

368368| :- | :- | :- |

369| `url` | `url` | Link to the `marketplace.json` file. Claude Code downloads only that file, so the marketplace's plugins can't use [relative-path sources](#relative-path-plugin-source). See [Stay within the download limits for hosted files](/docs/en/plugins/host-marketplace#stay-within-the-download-limits-for-hosted-files) for the size, timeout, and redirect limits |

369| `url` | `url` | Link to the `marketplace.json` file. Claude Code downloads only that file, so the marketplace's plugins can't use [relative-path sources](#relative-path-plugin-source). See [Stay within the download limits for hosted files](/docs/en/plugins/host-marketplace.md#stay-within-the-download-limits-for-hosted-files) for the size, timeout, and redirect limits |

370370| `url` | `git` | The git repository to clone |

371371| `headers` | `url` | Map of HTTP headers Claude Code sends with the fetch, for authenticated hosts |

372| `headersHelper` | `url` | Command that prints headers whose values are too short-lived to list in `headers`. Requires Claude Code v2.1.238 or later. See [Authenticate archive downloads](/docs/en/plugins/host-marketplace#authenticate-archive-downloads) |

373373| `repo` | `github` | In `marketplace add` and `extraKnownMarketplaces`, `repo` must name one repository. `marketplace add` rejects `owner/*` as not a valid `owner/repo` shorthand; in `extraKnownMarketplaces` Claude Code takes it literally and the clone fails |

374374| `ref` | `github`, `git` | Branch or tag. Defaults to the repository's default branch |

375375| `path` | `github`, `git` | The marketplace file's path inside the repository. Defaults to `.claude-plugin/marketplace.json` |

from line 376

376376| `path` | `file` | The marketplace file itself. Claude Code reads it in place and takes the directory two levels up as the marketplace root, so keep the file at `<root>/.claude-plugin/marketplace.json` |

377377| `path` | `directory` | The marketplace root, the directory that contains `.claude-plugin/marketplace.json` |

378378| `sparsePaths` | `github`, `git` | Array of directories for a sparse checkout, such as `[".claude-plugin", "plugins"]`. `claude plugin marketplace add --sparse` sets it |

379| `skipLfs` | `github`, `git` | Accepted and has no effect. See [Keep plugin files out of Git LFS](/docs/en/plugins/host-marketplace#keep-plugin-files-out-of-git-lfs) |

379| `skipLfs` | `github`, `git` | Accepted and has no effect. See [Keep plugin files out of Git LFS](/docs/en/plugins/host-marketplace.md#keep-plugin-files-out-of-git-lfs) |

380380| `name` | `settings` | Must equal the `extraKnownMarketplaces` key and can't be a [reserved name](#reserved-names) |

381381| `plugins` | `settings` | The inline catalog, with no hosted file. Each item takes `name`, `source`, `description`, `version`, `strict`, `headers`, and `headersHelper`. Write each item's `source` as an object type, because a relative path has no repository to resolve against |

382382

from line 385

385385`hostPattern`, `pathPattern`, `skills-dir`, and the `owner/*` form of `repo` are valid only in the two policy lists, `strictKnownMarketplaces` and `blockedMarketplaces`:

386386

387387* **`hostPattern` and `pathPattern`**: regular expressions Claude Code tests against a source before it fetches from it.

388* **`skills-dir`**: not a source. If you set `strictKnownMarketplaces` without a `{"source": "skills-dir"}` entry, [skills-directory plugins](/docs/en/plugins/org#keep-skills-directory-plugins-loading) stop loading. If you lock any customization type with [`strictPluginOnlyCustomization`](/docs/en/settings-reference#strictpluginonlycustomization), they stop loading whether or not the entry is present.

388* **`skills-dir`**: not a source. If you set `strictKnownMarketplaces` without a `{"source": "skills-dir"}` entry, [skills-directory plugins](/docs/en/plugins/org.md#keep-skills-directory-plugins-loading) stop loading. If you lock any customization type with [`strictPluginOnlyCustomization`](/docs/en/settings-reference#strictpluginonlycustomization), they stop loading whether or not the entry is present.

389389* **`owner/*`**: as a `github` `repo` value, matches every repository under exactly that GitHub owner. Requires Claude Code v2.1.223 or later.

390390

391For match order, exact-`ref` semantics, and recipes, see [Manage plugins for your organization](/docs/en/plugins/org).

391For match order, exact-`ref` semantics, and recipes, see [Manage plugins for your organization](/docs/en/plugins/org.md).

392392

393393### Source objects in settings

394394

from line 421

421421

422422## Validation messages

423423

424`claude plugin validate <path>` takes the marketplace root or the marketplace file itself. It prints errors and warnings. For exit codes and `--strict`, see [plugin validate](/docs/en/plugins/cli-reference#plugin-validate).

425425

426426A message names a plugin entry by its index, written as `plugins.1.source` or `plugins[1].source`.

427427

from line 483

483483

484484`claude plugin validate` doesn't report every failure. An entry `hooks` written as a file path or array passes validation, and the error appears only when the plugin loads, as [Hooks in an entry](#hooks-in-an-entry) describes. Errors fetching a `source` also appear only after install, not in validation.

485485

486[`claude plugin list`](/docs/en/plugins/cli-reference) shows a plugin that failed to load with its error, and [Troubleshoot plugins](/docs/en/plugins/troubleshooting) covers the load-time strings.

486[`claude plugin list`](/docs/en/plugins/cli-reference) shows a plugin that failed to load with its error, and [Troubleshoot plugins](/docs/en/plugins/troubleshooting.md) covers the load-time strings.

487487

488488## Next steps

489489

490* [Create a marketplace](/docs/en/plugins/create-marketplace): build a marketplace from these fields and install from it locally

491* [Host and maintain a marketplace](/docs/en/plugins/host-marketplace): where to put the file and how users receive changes

492* [Plugin manifest reference](/docs/en/plugins/manifest-reference): the `plugin.json` fields an entry can override

493* [Manage plugins for your organization](/docs/en/plugins/org): allowlist and blocklist recipes that use these source values

490* [Create a marketplace](/docs/en/plugins/create-marketplace.md): build a marketplace from these fields and install from it locally

491* [Host and maintain a marketplace](/docs/en/plugins/host-marketplace.md): where to put the file and how users receive changes

492* [Plugin manifest reference](/docs/en/plugins/manifest-reference.md): the `plugin.json` fields an entry can override

493* [Manage plugins for your organization](/docs/en/plugins/org.md): allowlist and blocklist recipes that use these source values

494494

This page’s history 19 edits

22 Oct 2026 +32 −32 · this one
22 Oct 2026 +2 −2
11 Oct 2026 +8 −10
11 Oct 2026 +3 −1
10 Oct 2026 +1 −0
9 Oct 2026 +1 −1

The page’s own history →

Where it came from

The captureclaude-code
Upstream pagecode.claude.com

Around it

Every changethe ledger
That day22 Oct 2026