Marketplace reference changedplugins/marketplace-reference

A whole new page. There's nothing to diff it against, so here is what it says.

# Marketplace reference

> Complete reference for marketplace.json fields, plugin entries, and the plugin and marketplace source objects, with where each is valid.

`marketplace.json` is the file that defines a plugin marketplace. It contains the marketplace's name, its owner, and one entry per plugin. Each entry's plugin source says where Claude Code fetches that plugin from.

A marketplace source is a separate object that says where Claude Code fetches the marketplace file itself. You write one in settings, or Claude Code builds one when you run `claude plugin marketplace add`.

This reference is for marketplace maintainers who need an exact field name or value, and for administrators who need to know which `source` values are valid in [`extraKnownMarketplaces`](/docs/en/settings-reference#extraknownmarketplaces), [`strictKnownMarketplaces`](/docs/en/settings-reference#strictknownmarketplaces), and [`blockedMarketplaces`](/docs/en/plugins/org#restrict-what-users-can-install).

<Note>
  These cases are covered on other pages:

  * **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)
  * **Allowlist and blocklist recipes**: see [Manage plugins for your organization](/docs/en/plugins/org)
</Note>

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

* **The marketplace file**: [Top-level fields](#top-level-fields) and [Plugin entries](#plugin-entries)
* **An entry's `source`**: [Plugin sources](#plugin-sources)
* **A `source` object in settings**: [Marketplace sources](#marketplace-sources)
* **Output from [`claude plugin validate <path>`](/docs/en/plugins/cli-reference)**: [Validation messages](#validation-messages), which maps each message to the field it names

## Marketplace file

Save the marketplace file at `.claude-plugin/marketplace.json` in your marketplace's directory. If you keep the file somewhere else in the repository, users have to declare the marketplace in [`extraKnownMarketplaces`](/docs/en/settings-reference#extraknownmarketplaces) with `path` set on its source, because `claude plugin marketplace add` has no option for it.

The directory that contains `.claude-plugin/` is called the marketplace root, and every relative plugin source resolves from it, not from `.claude-plugin/`.

Each user registers one marketplace per `name`, so a user can't have two marketplaces with the same name registered at once.

Claude Code ignores an unknown top-level key or plugin-entry key rather than rejecting it, so a typo loads silently. `claude plugin validate` reports each unknown key as a warning.

### Reserved names

You can't give your marketplace any of the following names:

* **Official marketplace names**: `claude-code-marketplace`, `claude-code-plugins`, `claude-plugins-official`, `anthropic-marketplace`, `anthropic-plugins`, `agent-skills`, `anthropic-agent-skills`, `life-sciences`, `knowledge-work-plugins`, `claude-for-legal`, `claude-for-financial-services`, `financial-services-plugins`, `first-party-plugins`, and `claude-tag-plugins`. Reserved unless the marketplace comes from a `github` or `git` [marketplace source](#marketplace-sources) under `github.com/anthropics/`.
* **Community marketplace names**: `claude-community`, `claude-plugins-community`, and `healthcare`. Reserved under the same rule as the official names.
* **Plugin directory names**: `anthropic-plugin-directory` and `claude-plugin-directory`. Reserved under the same rule as the official names.
* **Names that impersonate an official marketplace**: names such as `official-claude-plugins` or `claude-plugins-v2`, and any name containing a non-ASCII character. The error is `Marketplace name impersonates an official Anthropic/Claude marketplace`. A control or bidirectional-formatting character in a name also reports `Marketplace name cannot contain control or bidirectional-formatting characters`.
* <span id="reserved-name-spellings" />**Another spelling of a reserved name**: a name that differs from a reserved name only by a trailing dot, or by a symbol other than an underscore in place of a hyphen, so `claude.code.plugins` counts as `claude-code-plugins`. `claude plugin validate` accepts such a name; adding the marketplace fails with [`is another spelling of "<reserved>", a reserved marketplace name`](/docs/en/errors#marketplace-name-is-another-spelling-of-a-reserved-name), and a marketplace already registered under one stops loading. This check requires Claude Code v2.1.280 or later.
* **Names Claude Code uses for plugins that don't come from a marketplace**: `inline` for plugins loaded with [`--plugin-dir`](/docs/en/cli-reference), `builtin` for built-in plugins, `skills-dir` for plugins auto-loaded from [`.claude/skills/`](/docs/en/skills), and `synced` for plugins synced from your claude.ai account. `claude-plugin-test` is also reserved. `skills-dir` also appears as `{"source": "skills-dir"}` in `strictKnownMarketplaces` and `blockedMarketplaces`, described under [Source values valid only in policy lists](#source-values-valid-only-in-policy-lists).
* **`npm`, `pip`, `uv`, `cargo`, `github`, and `gh`**: reserved in any casing. This check requires Claude Code v2.1.275 or later.
* **Names starting with `claudeai-`**: reserved for marketplaces hosted on claude.ai. `claude plugin marketplace add` refuses any other marketplace that uses one with `Cannot add marketplace "<name>": names starting with "claudeai-" are reserved for marketplaces hosted on claude.ai`.

## Top-level fields

The table lists every key Claude Code reads from `marketplace.json`. `name`, `owner`, and `plugins` are required.

| Field                                      | Type             | Description                                                                                                                                                                                                                                                            |
| :----------------------------------------- | :--------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                                     | string           | Marketplace identifier. No spaces, control characters, or bidirectional-formatting characters, no `/` or `\`, no `..`, and not `.`. See [Reserved names](#reserved-names). Users type it after `@` when they install a plugin                                          |
| `owner`                                    | object           | Maintainer information. `name` is required; `email` and `url` are optional                                                                                                                                                                                             |
| `plugins`                                  | array            | [Plugin entries](#plugin-entries). Each entry is validated on its own, so one invalid entry doesn't fail the marketplace                                                                                                                                               |
| `$schema`                                  | string           | JSON Schema URL for editor autocomplete. Ignored at load time                                                                                                                                                                                                          |
| `description`                              | string           | Marketplace description shown to users. `claude plugin validate` warns when it's missing                                                                                                                                                                               |
| `version`                                  | string           | Marketplace manifest version                                                                                                                                                                                                                                           |
| `metadata.description`, `metadata.version` | string           | Alternate location for `description` and `version`                                                                                                                                                                                                                     |
| `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                                                                                                         |
| `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)                                                                                                                 |
| `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) |
| `renames`                                  | object           | Map from a former plugin `name` to its current name, or to `null` for a plugin you removed. Requires Claude Code v2.1.193 or later. See [Host and maintain a marketplace](/docs/en/plugins/host-marketplace)                                                                |

## Plugin entries

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

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).

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

| Field            | Type             | Description                                                                                                                                                                                                                                                                                                       |
| :--------------- | :--------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`           | string           | Plugin identifier, with no spaces, control characters, or bidirectional-formatting characters. Users type it before `@` when they install, even when the plugin's own `plugin.json` sets a different `name`                                                                                                       |
| `source`         | string or object | Where to fetch the plugin. See [Plugin sources](#plugin-sources)                                                                                                                                                                                                                                                  |
| `description`    | string           | Shown in [`/plugin`](/docs/en/plugins/install) listings and details                                                                                                                                                                                                                                                    |
| `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)                                                                                                                     |
| `category`       | string           | Free-form category for organizing the catalog                                                                                                                                                                                                                                                                     |
| `tags`           | array of strings | Free-form tags for search                                                                                                                                                                                                                                                                                         |
| `strict`         | boolean          | Default `true`. Whether `plugin.json` is the definitive source for the plugin's components. See [Strict mode](#strict-mode)                                                                                                                                                                                       |
| `relevance`      | object           | Signals that tell Claude Code when to suggest the plugin. See [Recommend plugins for your org](/docs/en/plugins/relevance)                                                                                                                                                                                             |
| `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)                                                                                                                                                 |
| `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`                                                                                                                   |
| `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`                                                                                                                                                                                |
| `metadata`       | object           | Free-form object for your own fields. Claude Code doesn't read it. Requires Claude Code v2.1.222 or later                                                                                                                                                                                                         |
| `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                                                          |
| `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) |

<h3 id="entry-and-plugin-json">
  How an entry combines with plugin.json
</h3>

The entry's fields apply differently to a fetched plugin that has its own `.claude-plugin/plugin.json` and to one that doesn't:

* **No `plugin.json`**: the entry is the manifest regardless of `strict`. Every manifest field in the entry applies, including [`mcpServers`, `lspServers`, `userConfig`, and `channels`](/docs/en/plugins/manifest-reference).
* **`plugin.json` present**: `plugin.json` is the manifest. [Strict mode](#strict-mode) decides whether the entry's six component fields, `commands`, `agents`, `skills`, `hooks`, `outputStyles`, and `themes`, are combined with it or rejected as a conflict. Entry `mcpServers`, `lspServers`, `userConfig`, and `channels` don't apply. Declare them in `plugin.json`.

#### Hooks in an entry

Write entry `hooks` as an inline object that maps hook event names to matcher arrays. If you write a file path or an array instead, `claude plugin validate` passes it. Those hooks never run, and Claude Code reports a `not yet supported in a marketplace entry` error for the plugin. Put file-based hooks in the plugin's own [`hooks/hooks.json`](/docs/en/plugins/components) or `plugin.json`.

#### Display fields

Both the entry and the plugin's own `plugin.json` can set the display fields `displayName`, `description`, `author`, `homepage`, `repository`, `license`, and `keywords`. Users see these values in plugin listings and details, before and after install:

* For a field you set on the entry, users see the entry's value, even when `plugin.json` sets a different one.
* For a field the entry leaves unset, users see the `plugin.json` value.

Before install, Claude Code can read `plugin.json` only for entries with a [relative-path source](#relative-path-plugin-source), whose plugin files are inside the marketplace itself. For an entry with any other source type, users see only the entry's own fields until they install the plugin.

### Strict mode

`strict` decides what happens when the fetched plugin has its own `plugin.json` and the entry also declares any of the [component fields](#entry-and-plugin-json): `commands`, `agents`, `skills`, `hooks`, `outputStyles`, or `themes`. With `strict: true`, the default, Claude Code appends the entry's component fields to `plugin.json`, except `hooks`, whose matchers replace the manifest's per event. With `strict: false`, an entry that declares any component field is a conflict, and the plugin fails to load. The table shows each combination of `strict`, `plugin.json`, and the entry's component fields.

| `strict`            | `plugin.json` | Entry component fields | Result                                                                                                                                                                                                                              |
| :------------------ | :------------ | :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| any                 | absent        | any                    | The entry is the manifest                                                                                                                                                                                                           |
| `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) |
| `false`             | present       | none                   | `plugin.json` is the manifest, as with `true`                                                                                                                                                                                       |
| `false`             | present       | one or more            | Conflict. The plugin fails to load with `Plugin <name> has conflicting manifests: both plugin.json and marketplace entry specify components`                                                                                        |

## Plugin sources

A plugin entry's `source` says where Claude Code fetches that one plugin from. It's either a relative path string or an object whose own `source` key names the type, so an entry looks like `"source": { "source": "github", "repo": "your-org/formatter" }`.

The table lists each plugin source type and its fields.

| Type          | Fields                           | Notes                                                                                                                                                                                                                          |
| :------------ | :------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Relative path | the string itself                | A directory inside the marketplace, resolved from the marketplace root. Must start with `./`, unless you write a [bare name under `metadata.pluginRoot`](#relative-path-plugin-source). `"."` on its own means the root itself |
| `github`      | `repo`, `ref`, `sha`             | GitHub repository in `owner/repo` form                                                                                                                                                                                         |
| `url`         | `url`, `ref`, `sha`              | Any git repository by URL                                                                                                                                                                                                      |
| `git-subdir`  | `url`, `path`, `ref`, `sha`      | One subdirectory of a git repository, fetched with a sparse partial clone                                                                                                                                                      |
| `npm`         | `package`, `version`, `registry` | npm package, fetched with your npm client and unpacked without running install scripts                                                                                                                                         |
| `archive`     | `url`, `sha256`                  | Zip archive over HTTPS. Requires Claude Code v2.1.224 or later                                                                                                                                                                 |
| `command`     | `command`, `timeout`, `mode`     | Directory printed by a command Claude Code runs on the user's machine. Requires Claude Code v2.1.229 or later                                                                                                                  |

The names `url` and `github` are also [marketplace source](#marketplace-sources) types, where `url` means a direct link to a `marketplace.json` file rather than a git repository. `git` exists only as a marketplace source, and `npm` exists as both. `git-subdir`, `archive`, and `command` exist only as plugin sources.

Use a relative path for a plugin in a subdirectory of the marketplace repository itself. Use `git-subdir` for a subdirectory of some other repository.

`github`, `url`, and `git-subdir` sources share the `ref` and `sha` fields:

* **`ref`**: a branch or tag. Defaults to the repository's default branch.
* **`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.

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

### Relative path plugin source

The path resolves from the marketplace root. `./plugins/formatter` is `<root>/plugins/formatter` even though the marketplace file is in `<root>/.claude-plugin/`.

A path containing `..` fails validation. On macOS and Linux, Claude Code refuses an entry path that contains a backslash anywhere after the leading `./`, so write the path with forward slashes.

```json theme={null}
{ "name": "formatter", "source": "./plugins/formatter" }
```

A relative path resolves only when Claude Code has the marketplace's files, so check the [marketplace source](#marketplace-sources) type:

* **`github`, `git`, `file`, and `directory`**: Claude Code has the marketplace's files.
* **`url`**: Claude Code fetches only `marketplace.json`, so relative paths can't resolve. Give each plugin an object source instead, such as `github` or `git-subdir`.
* **`settings`**: relative paths are rejected outright.

#### Bare names under pluginRoot

A bare name is a single directory name with no `/`, such as `"formatter"`. To write bare names instead of `./` paths, set [`metadata.pluginRoot`](#top-level-fields) to the directory they resolve under. With `"pluginRoot": "./plugins"`, `"source": "formatter"` resolves to `./plugins/formatter`. Requires Claude Code v2.1.239 or later.

`metadata.pluginRoot` has these limits:

* It must itself be a relative path inside the marketplace.
* It has no effect on a source that already starts with `./`.
* A source that contains a `/`, such as `team-a/formatter`, isn't a bare name and still needs the `./` prefix, even when `metadata.pluginRoot` is set.

### github plugin source

`repo` takes `owner/repo`. `ref` and `sha` are optional.

```json theme={null}
{
  "name": "formatter",
  "source": {
    "source": "github",
    "repo": "your-org/formatter",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}
```

### url plugin source

`url` is a full git URL: `https://`, `http://`, `file://`, or `git@`. A `.git` suffix isn't required, so Azure DevOps and AWS CodeCommit URLs work as written. This type doesn't take `owner/repo` shorthand.

```json theme={null}
{
  "name": "formatter",
  "source": {
    "source": "url",
    "url": "https://gitlab.example.com/your-group/formatter.git",
    "ref": "main"
  }
}
```

### git-subdir plugin source

`url` accepts a full git URL or GitHub `owner/repo` shorthand. `path` is the subdirectory that holds the plugin, and Claude Code downloads only that subdirectory.

```json theme={null}
{
  "name": "formatter",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/your-org/monorepo.git",
    "path": "tools/formatter"
  }
}
```

### npm plugin source

An `npm` source takes these fields:

* `package`: a package name, or a scoped name such as `@your-org/formatter`
* `version`: a version or range
* `registry`: a registry URL for a package that isn't on the default registry

Claude 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.

```json theme={null}
{
  "name": "formatter",
  "source": {
    "source": "npm",
    "package": "@your-org/formatter",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}
```

### archive plugin source

`url` must use `https://` and can't point at a loopback, link-local, or cloud-metadata host.

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

`sha256` is the archive's digest as 64 hex characters, uppercase or lowercase. When you set it, Claude Code refuses a download that doesn't match.

```json theme={null}
{
  "name": "formatter",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/formatter-2.0.0.zip",
    "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1"
  }
}
```

### command plugin source

Use 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.

A `command` source takes these fields:

* `command`: a shell command that prints the plugin directory's absolute path as one line and exits 0. Claude Code shows users the whole string for review before it runs. Write it as printable ASCII, at most 500 characters, with no run of four or more spaces.
* `timeout`: a whole number of seconds from 1 to 600. Defaults to 60.
* `mode`: `copy`, the default, or `link`. See [Copy mode and link mode](#copy-mode-and-link-mode).

```json theme={null}
{
  "name": "formatter",
  "source": {
    "source": "command",
    "command": "my-tool claude-plugin-path",
    "timeout": 120
  }
}
```

For 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).

#### What the command must do

Write the command to meet these requirements:

* **Shell and working directory**: Claude Code runs the command through `sh`, or through `cmd.exe` on Windows, from the user's home directory. Give an absolute path or a command on `PATH`.
* **Output**: print exactly one line on stdout, the absolute path of the plugin directory, and exit 0 within `timeout` seconds.
* **Directory contents**: the directory holds the complete plugin by the time the command exits. The path can differ from one run to the next.

#### Output that fails the install or update

The install or update fails when the command exits non-zero, runs longer than `timeout`, or prints anything other than one absolute path. It also fails when the printed directory is one of these:

* **No plugin content**: the printed directory has no plugin content at its top level, such as a `.claude-plugin/` directory or a `skills/`, `commands/`, `agents/`, or `hooks/` directory.
* **The session's own directory**: the printed directory is the one Claude Code was started in, or one of its parents.

Cut at 300 lines. The page has the rest.

No line in this hunk matches that.