6 6
7> Build and host plugin marketplaces to distribute Claude Code extensions across teams and communities.7> Build and host plugin marketplaces to distribute Claude Code extensions across teams and communities.
8 8
9A plugin marketplace is a catalog that lets you distribute plugins to others. Marketplaces provide centralized discovery, version tracking, automatic updates, and support for multiple source types (git repositories, local paths, and more). This guide shows you how to create your own marketplace to share plugins with your team or community.9A **plugin marketplace** is a catalog that lets you distribute plugins to others. Marketplaces provide centralized discovery, version tracking, automatic updates, and support for multiple source types (git repositories, local paths, and more). This guide shows you how to create your own marketplace to share plugins with your team or community.
10 10
11Looking to install plugins from an existing marketplace? See [Discover and install prebuilt plugins](/en/discover-plugins).11Looking to install plugins from an existing marketplace? See [Discover and install prebuilt plugins](/en/discover-plugins).
12 12
108<Note>108<Note>
109 **How plugins are installed**: When users install a plugin, Claude Code copies the plugin directory to a cache location. This means plugins can't reference files outside their directory using paths like `../shared-utils`, because those files won't be copied.109 **How plugins are installed**: When users install a plugin, Claude Code copies the plugin directory to a cache location. This means plugins can't reference files outside their directory using paths like `../shared-utils`, because those files won't be copied.
110 110
111 If you need to share files across plugins, use symlinks (which are followed during copying) or restructure your marketplace so the shared directory is inside the plugin source path. See [Plugin caching and file resolution](/en/plugins-reference#plugin-caching-and-file-resolution) for details.111 If you need to share files across plugins, use symlinks (which are followed during copying). See [Plugin caching and file resolution](/en/plugins-reference#plugin-caching-and-file-resolution) for details.
112</Note>112</Note>
113 113
114## Create the marketplace file114## Create the marketplace file
191**Standard metadata fields:**191**Standard metadata fields:**
192 192
193| Field | Type | Description |193| Field | Type | Description |
194| :------------ | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |194| :------------ | :------ | :-------------------------------------------------------------------------------------------------------------------------------- |
195| `description` | string | Brief plugin description |195| `description` | string | Brief plugin description |
196| `version` | string | Plugin version |196| `version` | string | Plugin version |
197| `author` | object | Plugin author information (`name` required, `email` optional) |197| `author` | object | Plugin author information (`name` required, `email` optional) |
201| `keywords` | array | Tags for plugin discovery and categorization |201| `keywords` | array | Tags for plugin discovery and categorization |
202| `category` | string | Plugin category for organization |202| `category` | string | Plugin category for organization |
203| `tags` | array | Tags for searchability |203| `tags` | array | Tags for searchability |
204| `strict` | boolean | When true (default), marketplace component fields merge with plugin.json. When false, the marketplace entry defines the plugin entirely, and plugin.json must not also declare components. |204| `strict` | boolean | Controls whether `plugin.json` is the authority for component definitions (default: true). See [Strict mode](#strict-mode) below. |
205 205
206**Component configuration fields:**206**Component configuration fields:**
207 207
215 215
216## Plugin sources216## Plugin sources
217 217
218Plugin sources tell Claude Code where to fetch each individual plugin listed in your marketplace. These are set in the `source` field of each plugin entry in `marketplace.json`.
219
220Once a plugin is cloned or copied into the local machine, it is copied into the local versioned plugin cache at `~/.claude/plugins/cache`.
221
222| Source | Type | Fields | Notes |
223| ------------- | ------------------------------- | ------------------------------------- | ----------------------------------------------------------------- |
224| Relative path | `string` (e.g. `"./my-plugin"`) | — | Local directory within the marketplace repo. Must start with `./` |
225| `github` | object | `repo`, `ref?`, `sha?` | |
226| `url` | object | `url` (must end .git), `ref?`, `sha?` | Git URL source |
227| `npm` | object | `package`, `version?`, `registry?` | Installed via `npm install` |
228| `pip` | object | `package`, `version?`, `registry?` | Installed via pip |
229
230<Note>
231 **Marketplace sources vs plugin sources**: These are different concepts that control different things.
232
233 * **Marketplace source** — where to fetch the `marketplace.json` catalog itself. Set when users run `/plugin marketplace add` or in `extraKnownMarketplaces` settings. Supports `ref` (branch/tag) but not `sha`.
234 * **Plugin source** — where to fetch an individual plugin listed in the marketplace. Set in the `source` field of each plugin entry inside `marketplace.json`. Supports both `ref` (branch/tag) and `sha` (exact commit).
235
236 For example, a marketplace hosted at `acme-corp/plugin-catalog` (marketplace source) can list a plugin fetched from `acme-corp/code-formatter` (plugin source). The marketplace source and plugin source point to different repositories and are pinned independently.
237</Note>
238
218### Relative paths239### Relative paths
219 240
220For plugins in the same repository:241For plugins in the same repository:
349 370
350* **`commands` and `agents`**: You can specify multiple directories or individual files. Paths are relative to the plugin root.371* **`commands` and `agents`**: You can specify multiple directories or individual files. Paths are relative to the plugin root.
351* **`${CLAUDE_PLUGIN_ROOT}`**: Use this variable in hooks and MCP server configs to reference files within the plugin's installation directory. This is necessary because plugins are copied to a cache location when installed.372* **`${CLAUDE_PLUGIN_ROOT}`**: Use this variable in hooks and MCP server configs to reference files within the plugin's installation directory. This is necessary because plugins are copied to a cache location when installed.
352* **`strict: false`**: Since this is set to false, the plugin doesn't need its own `plugin.json`. The marketplace entry defines everything.373* **`strict: false`**: Since this is set to false, the plugin doesn't need its own `plugin.json`. The marketplace entry defines everything. See [Strict mode](#strict-mode) below.
374
375### Strict mode
376
377The `strict` field controls whether `plugin.json` is the authority for component definitions (commands, agents, hooks, skills, MCP servers, output styles).
378
379| Value | Behavior |
380| :--------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |
381| `true` (default) | `plugin.json` is the authority. The marketplace entry can supplement it with additional components, and both sources are merged. |
382| `false` | The marketplace entry is the entire definition. If the plugin also has a `plugin.json` that declares components, that's a conflict and the plugin fails to load. |
383
384**When to use each mode:**
385
386* **`strict: true`**: the plugin has its own `plugin.json` and manages its own components. The marketplace entry can add extra commands or hooks on top. This is the default and works for most plugins.
387* **`strict: false`**: the marketplace operator wants full control. The plugin repo provides raw files, and the marketplace entry defines which of those files are exposed as commands, agents, hooks, etc. Useful when the marketplace restructures or curates a plugin's components differently than the plugin author intended.
353 388
354## Host and distribute marketplaces389## Host and distribute marketplaces
355 390
505 540
506For complete configuration details including all supported source types and comparison with `extraKnownMarketplaces`, see the [strictKnownMarketplaces reference](/en/settings#strictknownmarketplaces).541For complete configuration details including all supported source types and comparison with `extraKnownMarketplaces`, see the [strictKnownMarketplaces reference](/en/settings#strictknownmarketplaces).
507 542
543### Version resolution and release channels
544
545Plugin versions determine cache paths and update detection. You can specify the version in the plugin manifest (`plugin.json`) or in the marketplace entry (`marketplace.json`).
546
547<Warning>
548 When possible, avoid setting the version in both places. The plugin manifest always wins silently, which can cause the marketplace version to be ignored. For relative-path plugins, set the version in the marketplace entry. For all other plugin sources, set it in the plugin manifest.
549</Warning>
550
551#### Set up release channels
552
553To support "stable" and "latest" release channels for your plugins, you can set up two marketplaces that point to different refs or SHAs of the same repo. You can then assign the two marketplaces to different user groups through [managed settings](/en/settings#settings-files).
554
555<Warning>
556 The plugin's `plugin.json` must declare a different `version` at each pinned ref or commit. If two refs or commits have the same manifest version, Claude Code treats them as identical and skips the update.
557</Warning>
558
559##### Example
560
561```json theme={null}
562{
563 "name": "stable-tools",
564 "plugins": [
565 {
566 "name": "code-formatter",
567 "source": {
568 "source": "github",
569 "repo": "acme-corp/code-formatter",
570 "ref": "stable"
571 }
572 }
573 ]
574}
575```
576
577```json theme={null}
578{
579 "name": "latest-tools",
580 "plugins": [
581 {
582 "name": "code-formatter",
583 "source": {
584 "source": "github",
585 "repo": "acme-corp/code-formatter",
586 "ref": "latest"
587 }
588 }
589 ]
590}
591```
592
593##### Assign channels to user groups
594
595Assign each marketplace to the appropriate user group through managed settings. For example, the stable group receives:
596
597```json theme={null}
598{
599 "extraKnownMarketplaces": {
600 "stable-tools": {
601 "source": {
602 "source": "github",
603 "repo": "acme-corp/stable-tools"
604 }
605 }
606 }
607}
608```
609
610The early-access group receives `latest-tools` instead:
611
612```json theme={null}
613{
614 "extraKnownMarketplaces": {
615 "latest-tools": {
616 "source": {
617 "source": "github",
618 "repo": "acme-corp/latest-tools"
619 }
620 }
621 }
622}
623```
624
508## Validation and testing625## Validation and testing
509 626
510Test your marketplace before sharing.627Test your marketplace before sharing.
