Documentation 2025-12-19 21:01 UTC to 2025-12-20 00:04 UTC

33| `--dangerously-skip-permissions` | Skip permission prompts (use with caution) | `claude --dangerously-skip-permissions` |33| `--dangerously-skip-permissions` | Skip permission prompts (use with caution) | `claude --dangerously-skip-permissions` |

34| `--debug` | Enable debug mode with optional category filtering (for example, `"api,hooks"` or `"!statsig,!file"`) | `claude --debug "api,mcp"` |34| `--debug` | Enable debug mode with optional category filtering (for example, `"api,hooks"` or `"!statsig,!file"`) | `claude --debug "api,mcp"` |

35| `--disallowedTools` | Tools that are removed from the model's context and cannot be used | `"Bash(git log:*)" "Bash(git diff:*)" "Edit"` |35| `--disallowedTools` | Tools that are removed from the model's context and cannot be used | `"Bash(git log:*)" "Bash(git diff:*)" "Edit"` |

36| `--enable-lsp-logging` | Enable verbose LSP logging for debugging language server issues. Logs are written to `~/.claude/debug/` | `claude --enable-lsp-logging` |

36| `--fallback-model` | Enable automatic fallback to specified model when default model is overloaded (print mode only) | `claude -p --fallback-model sonnet "query"` |37| `--fallback-model` | Enable automatic fallback to specified model when default model is overloaded (print mode only) | `claude -p --fallback-model sonnet "query"` |

37| `--fork-session` | When resuming, create a new session ID instead of reusing the original (use with `--resume` or `--continue`) | `claude --resume abc123 --fork-session` |38| `--fork-session` | When resuming, create a new session ID instead of reusing the original (use with `--resume` or `--continue`) | `claude --resume abc123 --fork-session` |

38| `--ide` | Automatically connect to IDE on startup if exactly one valid IDE is available | `claude --ide` |39| `--ide` | Automatically connect to IDE on startup if exactly one valid IDE is available | `claude --ide` |

1# Discover and install prebuilt plugins through marketplaces

2 

3> Find and install plugins from marketplaces to extend Claude Code with new commands, agents, and capabilities.

4 

5Plugins extend Claude Code with custom commands, agents, hooks, and MCP servers. Plugin marketplaces are catalogs that help you discover and install these extensions without building them yourself.

6 

7Looking to create and distribute your own marketplace? See [Create and distribute a plugin marketplace](/en/plugin-marketplaces).

8 

9## How marketplaces work

10 

11A marketplace is a catalog of plugins that someone else has created and shared. Using a marketplace is a two-step process:

12 

13<Steps>

14 <Step title="Add the marketplace">

15 This registers the catalog with Claude Code so you can browse what's available. No plugins are installed yet.

16 </Step>

17 

18 <Step title="Install individual plugins">

19 Browse the catalog and install the plugins you want.

20 </Step>

21</Steps>

22 

23Think of it like adding an app store: adding the store gives you access to browse its collection, but you still choose which apps to download individually.

24 

25## Official Anthropic marketplace

26 

27The official Anthropic marketplace (`claude-plugins-official`) is automatically installed when you start Claude Code. You can browse its plugins immediately by running `/plugin` and going to the **Discover** tab.

28 

29To install a plugin from the official marketplace:

30 

31```shell theme={null}

32/plugin install plugin-name@claude-plugins-official

33```

34 

35## Try it: add the demo marketplace

36 

37Anthropic also maintains a [demo plugins marketplace](https://github.com/anthropics/claude-code/tree/main/plugins) with example plugins that show what's possible with the plugin system. Unlike the official marketplace, you need to add this one manually.

38 

39<Steps>

40 <Step title="Add the marketplace">

41 From within Claude Code, run the `plugin marketplace add` command for the `anthropics/claude-code` marketplace:

42 

43 ```shell theme={null}

44 /plugin marketplace add anthropics/claude-code

45 ```

46 

47 This downloads the marketplace catalog and makes its plugins available to you.

48 </Step>

49 

50 <Step title="Browse available plugins">

51 Run `/plugin` to open the plugin manager. This opens a tabbed interface with four tabs you can cycle through using **Tab** (or **Shift+Tab** to go backward):

52 

53 * **Discover**: browse available plugins from all your marketplaces

54 * **Installed**: view and manage your installed plugins

55 * **Marketplaces**: add, remove, or update your added marketplaces

56 * **Errors**: view any plugin loading errors

57 

58 Go to the **Discover** tab to see plugins from the marketplace you just added.

59 </Step>

60 

61 <Step title="Install a plugin">

62 Select a plugin to view its details, then choose an installation scope:

63 

64 * **User scope**: install for yourself across all projects

65 * **Project scope**: install for all collaborators on this repository

66 * **Local scope**: install for yourself in this repository only

67 

68 For example, select **commit-commands** (a plugin that adds git workflow commands) and install it to your user scope.

69 

70 You can also install directly from the command line:

71 

72 ```shell theme={null}

73 /plugin install commit-commands@anthropics-claude-code

74 ```

75 

76 See [Configuration scopes](/en/settings#configuration-scopes) to learn more about scopes.

77 </Step>

78 

79 <Step title="Use your new plugin">

80 After installing, the plugin's commands are immediately available. Plugin commands are namespaced by the plugin name, so **commit-commands** provides commands like `/commit-commands:commit`.

81 

82 Try it out by making a change to a file and running:

83 

84 ```shell theme={null}

85 /commit-commands:commit

86 ```

87 

88 This stages your changes, generates a commit message, and creates the commit.

89 

90 Each plugin works differently. Check the plugin's description in the **Discover** tab or its homepage to learn what commands and capabilities it provides.

91 </Step>

92</Steps>

93 

94The rest of this guide covers all the ways you can add marketplaces, install plugins, and manage your configuration.

95 

96## Add marketplaces

97 

98Use the `/plugin marketplace add` command to add marketplaces from different sources.

99 

100<Tip>

101 **Shortcuts**: You can use `/plugin market` instead of `/plugin marketplace`, and `rm` instead of `remove`.

102</Tip>

103 

104* **GitHub repositories**: `owner/repo` format (for example, `anthropics/claude-code`)

105* **Git URLs**: any git repository URL (GitLab, Bitbucket, self-hosted)

106* **Local paths**: directories or direct paths to `marketplace.json` files

107* **Remote URLs**: direct URLs to hosted `marketplace.json` files

108 

109### Add from GitHub

110 

111Add a GitHub repository that contains a `.claude-plugin/marketplace.json` file using the `owner/repo` format—where `owner` is the GitHub username or organization and `repo` is the repository name.

112 

113For example, `anthropics/claude-code` refers to the `claude-code` repository owned by `anthropics`:

114 

115```shell theme={null}

116/plugin marketplace add anthropics/claude-code

117```

118 

119### Add from other Git hosts

120 

121Add any git repository by providing the full URL. This works with any Git host, including GitLab, Bitbucket, and self-hosted servers:

122 

123Using HTTPS:

124 

125```shell theme={null}

126/plugin marketplace add https://gitlab.com/company/plugins.git

127```

128 

129Using SSH:

130 

131```shell theme={null}

132/plugin marketplace add git@gitlab.com:company/plugins.git

133```

134 

135To add a specific branch or tag, append `#` followed by the ref:

136 

137```shell theme={null}

138/plugin marketplace add https://gitlab.com/company/plugins.git#v1.0.0

139```

140 

141### Add from local paths

142 

143Add a local directory that contains a `.claude-plugin/marketplace.json` file:

144 

145```shell theme={null}

146/plugin marketplace add ./my-marketplace

147```

148 

149You can also add a direct path to a `marketplace.json` file:

150 

151```shell theme={null}

152/plugin marketplace add ./path/to/marketplace.json

153```

154 

155Or add a remote `marketplace.json` file via URL:

156 

157```shell theme={null}

158/plugin marketplace add https://example.com/marketplace.json

159```

160 

161## Install plugins

162 

163Once you've added marketplaces, you can install plugins directly (installs to user scope by default):

164 

165```shell theme={null}

166/plugin install plugin-name@marketplace-name

167```

168 

169To choose a different [installation scope](/en/settings#configuration-scopes), use the interactive UI: run `/plugin`, go to the **Discover** tab, and press **Enter** on a plugin. You'll see options for:

170 

171* **User scope** (default): install for yourself across all projects

172* **Project scope**: install for all collaborators on this repository (adds to `.claude/settings.json`)

173* **Local scope**: install for yourself in this repository only (not shared with collaborators)

174 

175You may also see plugins with **managed** scope—these are installed by enterprise administrators via [managed settings](/en/settings#enterprise-managed-policy-settings) and cannot be modified.

176 

177Run `/plugin` and go to the **Installed** tab to see your plugins grouped by scope.

178 

179<Warning>

180 Make sure you trust a plugin before installing it. Anthropic does not control what MCP servers, files, or other software are included in plugins and cannot verify that they work as intended. Check each plugin's homepage for more information.

181</Warning>

182 

183## Manage installed plugins

184 

185Run `/plugin` and go to the **Installed** tab to view, enable, disable, or uninstall your plugins.

186 

187You can also manage plugins with direct commands.

188 

189Disable a plugin without uninstalling:

190 

191```shell theme={null}

192/plugin disable plugin-name@marketplace-name

193```

194 

195Re-enable a disabled plugin:

196 

197```shell theme={null}

198/plugin enable plugin-name@marketplace-name

199```

200 

201Completely remove a plugin:

202 

203```shell theme={null}

204/plugin uninstall plugin-name@marketplace-name

205```

206 

207The `--scope` option lets you target a specific scope with CLI commands:

208 

209```shell theme={null}

210claude plugin install formatter@your-org --scope project

211claude plugin uninstall formatter@your-org --scope project

212```

213 

214## Manage marketplaces

215 

216You can manage marketplaces through the interactive `/plugin` interface or with CLI commands.

217 

218### Use the interactive interface

219 

220Run `/plugin` and go to the **Marketplaces** tab to:

221 

222* View all your added marketplaces with their sources and status

223* Add new marketplaces

224* Update marketplace listings to fetch the latest plugins

225* Remove marketplaces you no longer need

226 

227### Use CLI commands

228 

229You can also manage marketplaces with direct commands.

230 

231List all configured marketplaces:

232 

233```shell theme={null}

234/plugin marketplace list

235```

236 

237Refresh plugin listings from a marketplace:

238 

239```shell theme={null}

240/plugin marketplace update marketplace-name

241```

242 

243Remove a marketplace:

244 

245```shell theme={null}

246/plugin marketplace remove marketplace-name

247```

248 

249<Warning>

250 Removing a marketplace will uninstall any plugins you installed from it.

251</Warning>

252 

253### Configure auto-updates

254 

255Claude Code can automatically update marketplaces and their installed plugins at startup. When auto-update is enabled for a marketplace, Claude Code refreshes the marketplace data and updates installed plugins to their latest versions. If any plugins were updated, you'll see a notification suggesting you restart Claude Code.

256 

257Toggle auto-update for individual marketplaces through the UI:

258 

2591. Run `/plugin` to open the plugin manager

2602. Select **Marketplaces**

2613. Choose a marketplace from the list

2624. Select **Enable auto-update** or **Disable auto-update**

263 

264Official Anthropic marketplaces have auto-update enabled by default. Third-party and local development marketplaces have auto-update disabled by default.

265 

266To disable all automatic updates entirely for both Claude Code and all plugins, set the `DISABLE_AUTOUPDATER` environment variable. See [Auto updates](/en/setup#auto-updates) for details.

267 

268## Configure team marketplaces

269 

270Team admins can set up automatic marketplace installation for projects by adding marketplace configuration to `.claude/settings.json`. When team members trust the repository folder, Claude Code prompts them to install these marketplaces and plugins.

271 

272For full configuration options including `extraKnownMarketplaces` and `enabledPlugins`, see [Plugin settings](/en/settings#plugin-settings).

273 

274## Troubleshooting

275 

276### /plugin command not recognized

277 

278If you see "unknown command" or the `/plugin` command doesn't appear:

279 

2801. **Check your version**: Run `claude --version`. Plugins require version 1.0.33 or later.

2812. **Update Claude Code**:

282 * **Homebrew**: `brew upgrade claude-code`

283 * **npm**: `npm update -g @anthropic-ai/claude-code`

284 * **Native installer**: Re-run the install command from [Setup](/en/setup)

2853. **Restart Claude Code**: After updating, restart your terminal and run `claude` again.

286 

287### Common issues

288 

289* **Marketplace not loading**: Verify the URL is accessible and that `.claude-plugin/marketplace.json` exists at the path

290* **Plugin installation failures**: Check that plugin source URLs are accessible and repositories are public (or you have access)

291* **Files not found after installation**: Plugins are copied to a cache, so paths referencing files outside the plugin directory won't work

292 

293For detailed troubleshooting with solutions, see [Troubleshooting](/en/plugin-marketplaces#troubleshooting) in the marketplace guide. For debugging tools, see [Debugging and development tools](/en/plugins-reference#debugging-and-development-tools).

294 

295## Next steps

296 

297* **Build your own plugins**: See [Plugins](/en/plugins) to create custom commands, agents, and hooks

298* **Create a marketplace**: See [Create a plugin marketplace](/en/plugin-marketplaces) to distribute plugins to your team or community

299* **Technical reference**: See [Plugins reference](/en/plugins-reference) for complete specifications

300 

301 

302---

303 

304> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt

55 --allowedTools "Bash,Read,Edit"55 --allowedTools "Bash,Read,Edit"

56```56```

57 57 

58### Run slash commands58### Create a commit

59 59 

60Run [slash commands](/en/slash-commands) non-interactively. This example generates a commit for staged changes using the `/commit` slash command:60This example reviews staged changes and creates a commit with an appropriate message:

61 61 

62```bash theme={null}62```bash theme={null}

63claude -p "/commit"63claude -p "Look at my staged changes and create an appropriate commit" \

64 --allowedTools "Bash(git diff:*),Bash(git log:*),Bash(git status:*),Bash(git commit:*)"

64```65```

65 66 

67<Note>

68 [Slash commands](/en/slash-commands) like `/commit` are only available in interactive mode. In `-p` mode, describe the task you want to accomplish instead.

69</Note>

70 

66### Customize the system prompt71### Customize the system prompt

67 72 

68Use `--append-system-prompt` to add instructions while keeping Claude Code's default behavior. This example pipes a PR diff to Claude and instructs it to review for security vulnerabilities:73Use `--append-system-prompt` to add instructions while keeping Claude Code's default behavior. This example pipes a PR diff to Claude and instructs it to review for security vulnerabilities:

1# Plugin marketplaces1# Create and distribute a plugin marketplace

2 2 

3> Create and manage plugin marketplaces to distribute Claude Code extensions across teams and communities.3> Build and host plugin marketplaces to distribute Claude Code extensions across teams and communities.

4 4 

5Plugin marketplaces are catalogs of available plugins that make it easy to discover, install, and manage Claude Code extensions. This guide shows you how to use existing marketplaces and create your own for team distribution.5A 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.

6 6 

7## Overview7Looking to install plugins from an existing marketplace? See [Discover and install prebuilt plugins](/en/discover-plugins).

8 

9A marketplace is a JSON file that lists available plugins and describes where to find them. Marketplaces provide:

10 

11* **Centralized discovery**: Browse plugins from multiple sources in one place

12* **Version management**: Track and update plugin versions automatically

13* **Automatic updates**: Keep plugins current with [per-marketplace auto-update settings](#auto-update-settings)

14* **Team distribution**: Share required plugins across your organization

15* **Flexible sources**: Support for git repositories, GitHub repos, local paths, and package managers

16 

17### Prerequisites

18 

19* Claude Code installed and running

20* Basic familiarity with JSON file format

21* For creating marketplaces: Git repository or local development environment

22 

23## Add and use marketplaces

24 

25Add marketplaces using the `/plugin marketplace` commands to access plugins from different sources:

26 

27### Add GitHub marketplaces

28 

29```shell Add a GitHub repository containing .claude-plugin/marketplace.json theme={null}

30/plugin marketplace add owner/repo

31```

32 

33### Add Git repositories

34 

35```shell Add any git repository theme={null}

36/plugin marketplace add https://gitlab.com/company/plugins.git

37```

38 

39### Add local marketplaces for development

40 

41```shell Add local directory containing .claude-plugin/marketplace.json theme={null}

42/plugin marketplace add ./my-marketplace

43```

44 

45```shell Add direct path to marketplace.json file theme={null}

46/plugin marketplace add ./path/to/marketplace.json

47```

48 

49```shell Add remote marketplace.json via URL theme={null}

50/plugin marketplace add https://url.of/marketplace.json

51```

52 8 

53### Install plugins from marketplaces9## Overview

54 

55Once you've added marketplaces, install plugins directly:

56 10 

57```shell Install from any known marketplace theme={null}11Creating and distributing a marketplace involves:

58/plugin install plugin-name@marketplace-name

59```

60 12 

61```shell Browse available plugins interactively theme={null}131. **Creating plugins**: build one or more plugins with commands, agents, hooks, MCP servers, or LSP servers. This guide assumes you already have plugins to distribute; see [Create plugins](/en/plugins) for details on how to create them.

62/plugin142. **Creating a marketplace file**: define a `marketplace.json` that lists your plugins and where to find them (see [Create the marketplace file](#create-the-marketplace-file)).

63```153. **Host the marketplace**: push to GitHub, GitLab, or another git host (see [Host and distribute marketplaces](#host-and-distribute-marketplaces)).

164. **Share with users**: users add your marketplace with `/plugin marketplace add` and install individual plugins (see [Discover and install plugins](/en/discover-plugins)).

64 17 

65### Verify marketplace installation18Once your marketplace is live, you can update it by pushing changes to your repository. Users refresh their local copy with `/plugin marketplace update`.

66 19 

67After adding a marketplace:20## Walkthrough: create a local marketplace

68 21 

691. **List marketplaces**: Run `/plugin marketplace list` to confirm it's added22This example creates a marketplace with one plugin: a `/review` command for code reviews. You'll create the directory structure, add a slash command, create the plugin manifest and marketplace catalog, then install and test it.

702. **Browse plugins**: Use `/plugin` to see available plugins from your marketplace

713. **Test installation**: Try installing a plugin to verify the marketplace works correctly

72 23 

73### Example plugin marketplace24<Steps>

25 <Step title="Create the directory structure">

26 ```bash theme={null}

27 mkdir -p my-marketplace/.claude-plugin

28 mkdir -p my-marketplace/plugins/review-plugin/.claude-plugin

29 mkdir -p my-marketplace/plugins/review-plugin/commands

30 ```

31 </Step>

74 32 

75Claude Code maintains a marketplace of [demo plugins](https://github.com/anthropics/claude-code/tree/main/plugins). These plugins are examples of what's possible with the plugin system.33 <Step title="Create the plugin command">

34 Create a Markdown file that defines what the `/review` command does.

76 35 

77```shell Add the marketplace theme={null}36 ```markdown my-marketplace/plugins/review-plugin/commands/review.md theme={null}

78/plugin marketplace add anthropics/claude-code37 Review the code I've selected or the recent changes for:

79```38 - Potential bugs or edge cases

39 - Security concerns

40 - Performance issues

41 - Readability improvements

80 42 

81## Configure team marketplaces43 Be concise and actionable.

44 ```

45 </Step>

82 46 

83Set up automatic marketplace installation for team projects by specifying required marketplaces in `.claude/settings.json`:47 <Step title="Create the plugin manifest">

48 Create a `plugin.json` file that describes the plugin. The manifest goes in the `.claude-plugin/` directory.

84 49 

85```json theme={null}50 ```json my-marketplace/plugins/review-plugin/.claude-plugin/plugin.json theme={null}

86{51 {

87 "extraKnownMarketplaces": {52 "name": "review-plugin",

88 "team-tools": {53 "description": "Adds a /review command for quick code reviews",

89 "source": {54 "version": "1.0.0"

90 "source": "github",

91 "repo": "your-org/claude-plugins"

92 }

93 },

94 "project-specific": {

95 "source": {

96 "source": "git",

97 "url": "https://git.company.com/project-plugins.git"

98 }

99 }

100 }55 }

101}56 ```

102```57 </Step>

103 

104When team members trust the repository folder, Claude Code automatically installs these marketplaces and any plugins specified in the `enabledPlugins` field.

105 

106## Enterprise marketplace restrictions

107 58 

108For organizations requiring strict control over plugin sources, enterprise administrators can restrict which plugin marketplaces users are allowed to add using the `strictKnownMarketplaces` setting in managed settings.59 <Step title="Create the marketplace file">

60 Create the marketplace catalog that lists your plugin.

109 61 

110**Managed settings file locations**:62 ```json my-marketplace/.claude-plugin/marketplace.json theme={null}

111 

112* **macOS**: `/Library/Application Support/ClaudeCode/managed-settings.json`

113* **Linux and WSL**: `/etc/claude-code/managed-settings.json`

114* **Windows**: `C:\ProgramData\ClaudeCode\managed-settings.json`

115 

116**Restriction behavior**:

117 

118When `strictKnownMarketplaces` is configured in managed settings:

119 

120* **Undefined** (default): No restrictions - users can add any marketplace

121* **Empty array `[]`**: Complete lockdown - users cannot add any new marketplaces

122* **List of sources**: Users can only add marketplaces that match the allowlist exactly

123 

124**Basic examples**:

125 

126Disable all marketplace additions:

127 

128```json theme={null}

129{

130 "strictKnownMarketplaces": []

131}

132```

133 

134Allow specific marketplaces only:

135 

136```json theme={null}

137{

138 "strictKnownMarketplaces": [

139 {

140 "source": "github",

141 "repo": "company/approved-plugins"

142 },

143 {63 {

144 "source": "github",64 "name": "my-plugins",

145 "repo": "company/security-tools",65 "owner": {

146 "ref": "v2.0"66 "name": "Your Name"

147 },67 },

68 "plugins": [

148 {69 {

149 "source": "url",70 "name": "review-plugin",

150 "url": "https://internal.company.com/plugins/marketplace.json"71 "source": "./plugins/review-plugin",

72 "description": "Adds a /review command for quick code reviews"

151 }73 }

152 ]74 ]

153}75 }

154```76 ```

77 </Step>

155 78 

156**Key characteristics**:79 <Step title="Add and install">

80 Add the marketplace and install the plugin.

157 81 

158* Enforced BEFORE network/filesystem operations82 ```shell theme={null}

159* Uses exact matching (including optional `ref` and `path` fields for git sources)83 /plugin marketplace add ./my-marketplace

160* Cannot be overridden by user or project settings84 /plugin install review-plugin@my-plugins

161* Only affects adding NEW marketplaces (previously installed marketplaces still work)85 ```

86 </Step>

162 87 

163See [strictKnownMarketplaces reference](/en/settings#strictknownmarketplaces) for complete configuration details, including all six supported source types, exact matching rules, and comparison with `extraKnownMarketplaces`.88 <Step title="Try it out">

89 Select some code in your editor and run your new command.

164 90 

165***91 ```shell theme={null}

92 /review

93 ```

94 </Step>

95</Steps>

166 96 

167## Create your own marketplace97To learn more about what plugins can do, including hooks, agents, MCP servers, and LSP servers, see [Plugins](/en/plugins).

168 98 

169Build and distribute custom plugin collections for your team or community.99<Note>

100 **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.

170 101 

171### Prerequisites for marketplace creation102 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.

103</Note>

172 104 

173* Git repository (GitHub, GitLab, or other git hosting)105## Create the marketplace file

174* Understanding of JSON file format

175* One or more plugins to distribute

176 106 

177### Create the marketplace file107Create `.claude-plugin/marketplace.json` in your repository root. This file defines your marketplace's name, owner information, and a list of plugins with their sources.

178 108 

179Create `.claude-plugin/marketplace.json` in your repository root:109Each plugin entry needs at minimum a `name` and `source` (where to fetch it from). See the [full schema](#marketplace-schema) below for all available fields.

180 110 

181```json theme={null}111```json theme={null}

182{112{

183 "name": "company-tools",113 "name": "company-tools",

184 "owner": {114 "owner": {

185 "name": "DevTools Team",115 "name": "DevTools Team",

186 "email": "devtools@company.com"116 "email": "devtools@example.com"

187 },117 },

188 "plugins": [118 "plugins": [

189 {119 {

207}137}

208```138```

209 139 

210### Marketplace schema140## Marketplace schema

211 141 

212#### Required fields142### Required fields

213 143 

214| Field | Type | Description |144| Field | Type | Description | Example |

215| :-------- | :----- | :--------------------------------------------- |145| :-------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------- |

216| `name` | string | Marketplace identifier (kebab-case, no spaces) |146| `name` | string | Marketplace identifier (kebab-case, no spaces). This is public-facing: users see it when installing plugins (for example, `/plugin install my-tool@your-marketplace`). | `"acme-tools"` |

217| `owner` | object | Marketplace maintainer information |147| `owner` | object | Marketplace maintainer information ([see fields below](#owner-fields)) | |

218| `plugins` | array | List of available plugins |148| `plugins` | array | List of available plugins | See below |

149 

150<Note>

151 **Reserved names**: The following marketplace names are reserved for official Anthropic use and cannot be used by third-party marketplaces: `claude-code-marketplace`, `claude-code-plugins`, `claude-plugins-official`, `anthropic-marketplace`, `anthropic-plugins`, `agent-skills`, `life-sciences`. Names that impersonate official marketplaces (like `official-claude-plugins` or `anthropic-tools-v2`) are also blocked.

152</Note>

153 

154### Owner fields

219 155 

220#### Optional metadata156| Field | Type | Required | Description |

157| :------ | :----- | :------- | :------------------------------- |

158| `name` | string | Yes | Name of the maintainer or team |

159| `email` | string | No | Contact email for the maintainer |

160 

161### Optional metadata

221 162 

222| Field | Type | Description |163| Field | Type | Description |

223| :--------------------- | :----- | :------------------------------------ |164| :--------------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

224| `metadata.description` | string | Brief marketplace description |165| `metadata.description` | string | Brief marketplace description |

225| `metadata.version` | string | Marketplace version |166| `metadata.version` | string | Marketplace version |

226| `metadata.pluginRoot` | string | Base path for relative plugin sources |167| `metadata.pluginRoot` | string | Base directory prepended to relative plugin source paths (for example, `"./plugins"` lets you write `"source": "formatter"` instead of `"source": "./plugins/formatter"`) |

227 168 

228### Plugin entries169## Plugin entries

229 170 

230<Note>171Each plugin entry in the `plugins` array describes a plugin and where to find it. You can include any field from the [plugin manifest schema](/en/plugins-reference#plugin-manifest-schema) (like `description`, `version`, `author`, `commands`, `hooks`, etc.), plus these marketplace-specific fields: `source`, `category`, `tags`, and `strict`.

231 Plugin entries are based on the *plugin manifest schema* (with all fields made

232 optional) plus marketplace-specific fields (`source`, `category`, `tags`,

233 `strict`), with `name` being required.

234</Note>

235 172 

236**Required fields:**173### Required fields

237 174 

238| Field | Type | Description |175| Field | Type | Description |

239| :------- | :------------- | :---------------------------------------- |176| :------- | :------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |

240| `name` | string | Plugin identifier (kebab-case, no spaces) |177| `name` | string | Plugin identifier (kebab-case, no spaces). This is public-facing: users see it when installing (for example, `/plugin install my-plugin@marketplace`). |

241| `source` | string\|object | Where to fetch the plugin from |178| `source` | string\|object | Where to fetch the plugin from (see [Plugin sources](#plugin-sources) below) |

242 179 

243#### Optional plugin fields180### Optional plugin fields

244 181 

245**Standard metadata fields:**182**Standard metadata fields:**

246 183 

247| Field | Type | Description |184| Field | Type | Description |

248| :------------ | :------ | :---------------------------------------------------------------- |185| :------------ | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

249| `description` | string | Brief plugin description |186| `description` | string | Brief plugin description |

250| `version` | string | Plugin version |187| `version` | string | Plugin version |

251| `author` | object | Plugin author information |188| `author` | object | Plugin author information (`name` required, `email` optional) |

252| `homepage` | string | Plugin homepage or documentation URL |189| `homepage` | string | Plugin homepage or documentation URL |

253| `repository` | string | Source code repository URL |190| `repository` | string | Source code repository URL |

254| `license` | string | SPDX license identifier (for example, MIT, Apache-2.0) |191| `license` | string | SPDX license identifier (for example, MIT, Apache-2.0) |

255| `keywords` | array | Tags for plugin discovery and categorization |192| `keywords` | array | Tags for plugin discovery and categorization |

256| `category` | string | Plugin category for organization |193| `category` | string | Plugin category for organization |

257| `tags` | array | Tags for searchability |194| `tags` | array | Tags for searchability |

258| `strict` | boolean | Require plugin.json in plugin folder (default: true) <sup>1</sup> |195| `strict` | boolean | Controls whether plugins need their own `plugin.json` file. When `true` (default), the plugin source must contain a `plugin.json`, and any fields you add here in the marketplace entry get merged with it. When `false`, the plugin doesn't need its own `plugin.json`; the marketplace entry itself defines everything about the plugin. Use `false` when you want to define simple plugins entirely in your marketplace file. |

259 196 

260**Component configuration fields:**197**Component configuration fields:**

261 198 

265| `agents` | string\|array | Custom paths to agent files |202| `agents` | string\|array | Custom paths to agent files |

266| `hooks` | string\|object | Custom hooks configuration or path to hooks file |203| `hooks` | string\|object | Custom hooks configuration or path to hooks file |

267| `mcpServers` | string\|object | MCP server configurations or path to MCP config |204| `mcpServers` | string\|object | MCP server configurations or path to MCP config |

205| `lspServers` | string\|object | LSP server configurations or path to LSP config |

268 206 

269*<sup>1 - When `strict: true` (default), the plugin must include a `plugin.json` manifest file, and marketplace fields supplement those values. When `strict: false`, the plugin.json is optional. If it's missing, the marketplace entry serves as the complete plugin manifest.</sup>*207## Plugin sources

270 208 

271### Plugin sources209### Relative paths

272 

273#### Relative paths

274 210 

275For plugins in the same repository:211For plugins in the same repository:

276 212 

281}217}

282```218```

283 219 

284#### GitHub repositories220### GitHub repositories

285 221 

286```json theme={null}222```json theme={null}

287{223{

293}229}

294```230```

295 231 

296#### Git repositories232### Git repositories

297 233 

298```json theme={null}234```json theme={null}

299{235{

305}241}

306```242```

307 243 

308#### Advanced plugin entries244### Advanced plugin entries

309 245 

310Plugin entries can override default component locations and provide additional metadata. Note that `${CLAUDE_PLUGIN_ROOT}` is an environment variable that resolves to the plugin's installation directory (for details see [Environment variables](/en/plugins-reference#environment-variables)):246This example shows a plugin entry using many of the optional fields, including custom paths for commands, agents, hooks, and MCP servers:

311 247 

312```json theme={null}248```json theme={null}

313{249{

320 "version": "2.1.0",256 "version": "2.1.0",

321 "author": {257 "author": {

322 "name": "Enterprise Team",258 "name": "Enterprise Team",

323 "email": "enterprise@company.com"259 "email": "enterprise@example.com"

324 },260 },

325 "homepage": "https://docs.company.com/plugins/enterprise-tools",261 "homepage": "https://docs.example.com/plugins/enterprise-tools",

326 "repository": "https://github.com/company/enterprise-plugin",262 "repository": "https://github.com/company/enterprise-plugin",

327 "license": "MIT",263 "license": "MIT",

328 "keywords": ["enterprise", "workflow", "automation"],264 "keywords": ["enterprise", "workflow", "automation"],

356}292}

357```293```

358 294 

359<Note>295Key things to notice:

360 **Schema relationship**: Plugin entries use the plugin manifest schema with

361 all fields made optional, plus marketplace-specific fields (`source`,

362 `strict`, `category`, `tags`). This means any field valid in a `plugin.json`

363 file can also be used in a marketplace entry. When `strict: false`, the

364 marketplace entry serves as the complete plugin manifest if no `plugin.json`

365 exists. When `strict: true` (default), marketplace fields supplement the

366 plugin's own manifest file.

367</Note>

368 296 

369***297* **`commands` and `agents`**: You can specify multiple directories or individual files. Paths are relative to the plugin root.

298* **`${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.

299* **`strict: false`**: Since this is set to false, the plugin doesn't need its own `plugin.json`. The marketplace entry defines everything.

370 300 

371## Host and distribute marketplaces301## Host and distribute marketplaces

372 302 

373Choose the best hosting strategy for your plugin distribution needs.

374 

375### Host on GitHub (recommended)303### Host on GitHub (recommended)

376 304 

377GitHub provides the easiest distribution method:305GitHub provides the easiest distribution method:

378 306 

3791. **Create a repository**: Set up a new repository for your marketplace3071. **Create a repository**: Set up a new repository for your marketplace

3802. **Add marketplace file**: Create `.claude-plugin/marketplace.json` with your plugin definitions3082. **Add marketplace file**: Create `.claude-plugin/marketplace.json` with your plugin definitions

3813. **Share with teams**: Team members add with `/plugin marketplace add owner/repo`3093. **Share with teams**: Users add your marketplace with `/plugin marketplace add owner/repo`

382 310 

383**Benefits**: Built-in version control, issue tracking, and team collaboration features.311**Benefits**: Built-in version control, issue tracking, and team collaboration features.

384 312 

385### Host on other git services313### Host on other git services

386 314 

387Any git hosting service works for marketplace distribution, using a URL to an arbitrary git repository.315Any git hosting service works, such as GitLab, Bitbucket, and self-hosted servers. Users add with the full repository URL:

388 

389For example, using GitLab:

390 316 

391```shell theme={null}317```shell theme={null}

392/plugin marketplace add https://gitlab.com/company/plugins.git318/plugin marketplace add https://gitlab.com/company/plugins.git

393```319```

394 320 

395### Use local marketplaces for development321### Test locally before distribution

396 322 

397Test your marketplace locally before distribution:323Test your marketplace locally before sharing:

398 324 

399```shell Add local marketplace for testing theme={null}325```shell theme={null}

400/plugin marketplace add ./my-local-marketplace326/plugin marketplace add ./my-local-marketplace

401```

402 

403```shell Test plugin installation theme={null}

404/plugin install test-plugin@my-local-marketplace327/plugin install test-plugin@my-local-marketplace

405```328```

406 329 

407## Manage marketplace operations330For the full range of add commands (GitHub, Git URLs, local paths, remote URLs), see [Add marketplaces](/en/discover-plugins#add-marketplaces).

408 331 

409### List known marketplaces332### Require marketplaces for your team

410 333 

411```shell List all configured marketplaces theme={null}334You can configure your repository so team members are automatically prompted to install your marketplace when they trust the project folder. Add your marketplace to `.claude/settings.json`:

412/plugin marketplace list

413```

414 335 

415Shows all configured marketplaces with their sources and status.336```json theme={null}

337{

338 "extraKnownMarketplaces": {

339 "company-tools": {

340 "source": {

341 "source": "github",

342 "repo": "your-org/claude-plugins"

343 }

344 }

345 }

346}

347```

416 348 

417### Update marketplace metadata349You can also specify which plugins should be enabled by default:

418 350 

419```shell Refresh marketplace metadata theme={null}351```json theme={null}

420/plugin marketplace update marketplace-name352{

353 "enabledPlugins": {

354 "code-formatter@company-tools": true,

355 "deployment-tools@company-tools": true

356 }

357}

421```358```

422 359 

423Refreshes plugin listings and metadata from the marketplace source.360For full configuration options, see [Plugin settings](/en/settings#plugin-settings).

424 361 

425### Remove a marketplace362### Enterprise marketplace restrictions

426 363 

427```shell Remove a marketplace theme={null}364For organizations requiring strict control over plugin sources, enterprise administrators can restrict which plugin marketplaces users are allowed to add using the [`strictKnownMarketplaces`](/en/settings#strictknownmarketplaces) setting in managed settings.

428/plugin marketplace remove marketplace-name365 

429```366When `strictKnownMarketplaces` is configured in managed settings, the restriction behavior depends on the value:

430 367 

431Removes the marketplace from your configuration.368| Value | Behavior |

369| ------------------- | ---------------------------------------------------------------- |

370| Undefined (default) | No restrictions. Users can add any marketplace |

371| Empty array `[]` | Complete lockdown. Users cannot add any new marketplaces |

372| List of sources | Users can only add marketplaces that match the allowlist exactly |

373 

374#### Common configurations

375 

376Disable all marketplace additions:

432 377 

433<Warning>378```json theme={null}

434 Removing a marketplace will uninstall any plugins you installed from it.379{

435</Warning>380 "strictKnownMarketplaces": []

381}

382```

436 383 

437***384Allow specific marketplaces only:

385 

386```json theme={null}

387{

388 "strictKnownMarketplaces": [

389 {

390 "source": "github",

391 "repo": "acme-corp/approved-plugins"

392 },

393 {

394 "source": "github",

395 "repo": "acme-corp/security-tools",

396 "ref": "v2.0"

397 },

398 {

399 "source": "url",

400 "url": "https://plugins.example.com/marketplace.json"

401 }

402 ]

403}

404```

438 405 

439## Auto-update settings406#### How restrictions work

440 407 

441Claude Code can automatically update marketplaces and their installed plugins at startup. This keeps your plugins current without manual intervention.408Restrictions are validated early in the plugin installation process, before any network requests or filesystem operations occur. This prevents unauthorized marketplace access attempts.

442 409 

443### How auto-update works410The allowlist uses exact matching. For a marketplace to be allowed, all specified fields must match exactly:

444 411 

445When auto-update is enabled for a marketplace:412* For GitHub sources: `repo` is required, and `ref` or `path` must also match if specified in the allowlist

413* For URL sources: the full URL must match exactly

446 414 

4471. **Marketplace refresh**: Claude Code pulls the latest marketplace data (git pull or re-download)415Because `strictKnownMarketplaces` is set in [managed settings](/en/settings#settings-file-locations), individual users and project configurations cannot override these restrictions.

4482. **Plugin updates**: Installed plugins from that marketplace are updated to their latest versions

4493. **Notification**: If any plugins were updated, you'll see a notification suggesting a restart

450 416 

451### Configure auto-update per marketplace417For complete configuration details including all supported source types and comparison with `extraKnownMarketplaces`, see the [strictKnownMarketplaces reference](/en/settings#strictknownmarketplaces).

452 418 

453Toggle auto-update for individual marketplaces through the UI:419## Validation and testing

454 420 

4551. Run `/plugin` to open the plugin manager421Test your marketplace before sharing.

4562. Select **Marketplaces**

4573. Choose a marketplace from the list

4584. Select **Enable auto-update** or **Disable auto-update**

459 422 

460<Note>423Validate your marketplace JSON syntax:

461 Official Anthropic marketplaces have auto-update enabled by default. You can disable this if you prefer manual updates.

462</Note>

463 424 

464### Auto-update behavior425```bash theme={null}

426claude plugin validate .

427```

465 428 

466| Marketplace type | Default behavior |429Or from within Claude Code:

467| :------------------------------ | :------------------- |

468| Official Anthropic marketplaces | Auto-update enabled |

469| Third-party marketplaces | Auto-update disabled |

470| Local development marketplaces | Auto-update disabled |

471 430 

472### Disable auto-update globally431```shell theme={null}

432/plugin validate .

433```

473 434 

474To disable all automatic updates (both Claude Code and plugins), set the `DISABLE_AUTOUPDATER` environment variable. See [Auto updates](/en/setup#auto-updates) for details.435Add the marketplace for testing:

475 436 

476When auto-updates are disabled globally:437```shell theme={null}

438/plugin marketplace add ./path/to/marketplace

439```

477 440 

478* No marketplaces or plugins will auto-update441Install a test plugin to verify everything works:

479* The auto-update toggle is hidden in the UI

480* You can still manually update using `/plugin marketplace update`

481 442 

482***443```shell theme={null}

444/plugin install test-plugin@marketplace-name

445```

483 446 

484## Troubleshooting marketplaces447For complete plugin testing workflows, see [Test your plugins locally](/en/plugins#test-your-plugins-locally). For technical troubleshooting, see [Plugins reference](/en/plugins-reference).

485 448 

486### Common marketplace issues449## Troubleshooting

487 450 

488#### Marketplace not loading451### Marketplace not loading

489 452 

490**Symptoms**: Can't add marketplace or see plugins from it453**Symptoms**: Can't add marketplace or see plugins from it

491 454 

493 456 

494* Verify the marketplace URL is accessible457* Verify the marketplace URL is accessible

495* Check that `.claude-plugin/marketplace.json` exists at the specified path458* Check that `.claude-plugin/marketplace.json` exists at the specified path

496* Ensure JSON syntax is valid using `claude plugin validate`459* Ensure JSON syntax is valid using `claude plugin validate` or `/plugin validate`

497* For private repositories, confirm you have access permissions460* For private repositories, confirm you have access permissions

498 461 

499#### Plugin installation failures462### Marketplace validation errors

463 

464Run `claude plugin validate .` or `/plugin validate .` from your marketplace directory to check for issues. Common errors:

465 

466| Error | Cause | Solution |

467| :------------------------------------------------ | :------------------------------ | :------------------------------------------------------------ |

468| `File not found: .claude-plugin/marketplace.json` | Missing manifest | Create `.claude-plugin/marketplace.json` with required fields |

469| `Invalid JSON syntax: Unexpected token...` | JSON syntax error | Check for missing commas, extra commas, or unquoted strings |

470| `Duplicate plugin name "x" found in marketplace` | Two plugins share the same name | Give each plugin a unique `name` value |

471| `plugins[0].source: Path traversal not allowed` | Source path contains `..` | Use paths relative to marketplace root without `..` |

472 

473**Warnings** (non-blocking):

474 

475* `Marketplace has no plugins defined`: add at least one plugin to the `plugins` array

476* `No marketplace description provided`: add `metadata.description` to help users understand your marketplace

477* `Plugin "x" uses npm source which is not yet fully implemented`: use `github` or local path sources instead

478 

479### Plugin installation failures

500 480 

501**Symptoms**: Marketplace appears but plugin installation fails481**Symptoms**: Marketplace appears but plugin installation fails

502 482 

507* For GitHub sources, ensure repositories are public or you have access487* For GitHub sources, ensure repositories are public or you have access

508* Test plugin sources manually by cloning/downloading488* Test plugin sources manually by cloning/downloading

509 489 

510### Validation and testing490### Files not found after installation

511 

512Test your marketplace before sharing:

513 

514```bash Validate marketplace JSON syntax theme={null}

515claude plugin validate .

516```

517 

518```shell Add marketplace for testing theme={null}

519/plugin marketplace add ./path/to/marketplace

520```

521 

522```shell Install test plugin theme={null}

523/plugin install test-plugin@marketplace-name

524```

525 

526For complete plugin testing workflows, see [Test your plugins locally](/en/plugins#test-your-plugins-locally). For technical troubleshooting, see [Plugins reference](/en/plugins-reference).

527 

528***

529 

530## Next steps

531 

532### For marketplace users

533 

534* **Discover community marketplaces**: Search GitHub for Claude Code plugin collections

535* **Contribute feedback**: Report issues and suggest improvements to marketplace maintainers

536* **Share useful marketplaces**: Help your team discover valuable plugin collections

537 491 

538### For marketplace creators492**Symptoms**: Plugin installs but references to files fail, especially files outside the plugin directory

539 493 

540* **Build plugin collections**: Create themed marketplace around specific use cases494**Cause**: Plugins are copied to a cache directory rather than used in-place. Paths that reference files outside the plugin's directory (such as `../shared-utils`) won't work because those files aren't copied.

541* **Establish versioning**: Implement clear versioning and update policies

542* **Community engagement**: Gather feedback and maintain active marketplace communities

543* **Documentation**: Provide clear README files explaining your marketplace contents

544 495 

545### For organizations496**Solutions**: See [Plugin caching and file resolution](/en/plugins-reference#plugin-caching-and-file-resolution) for workarounds including symlinks and directory restructuring.

546 497 

547* **Private marketplaces**: Set up internal marketplaces for proprietary tools498For additional debugging tools and common issues, see [Debugging and development tools](/en/plugins-reference#debugging-and-development-tools).

548* **Governance policies**: Establish guidelines for plugin approval and security review

549* **Training resources**: Help teams discover and adopt useful plugins effectively

550 499 

551## See also500## See also

552 501 

553* [Plugins](/en/plugins) - Installing and using plugins502* [Discover and install prebuilt plugins](/en/discover-plugins) - Installing plugins from existing marketplaces

503* [Plugins](/en/plugins) - Creating your own plugins

554* [Plugins reference](/en/plugins-reference) - Complete technical specifications and schemas504* [Plugins reference](/en/plugins-reference) - Complete technical specifications and schemas

555* [Plugin development](/en/plugins#develop-more-complex-plugins) - Creating your own plugins505* [Plugin settings](/en/settings#plugin-settings) - Plugin configuration options

556* [Settings](/en/settings#plugin-configuration) - Plugin configuration options506* [strictKnownMarketplaces reference](/en/settings#strictknownmarketplaces) - Enterprise marketplace restrictions

557* [strictKnownMarketplaces reference](/en/settings#strictknownmarketplaces) - Complete configuration reference for enterprise marketplace restrictions

558 507 

559 508 

560---509---

1# Plugins1# Create plugins

2 2 

3> Extend Claude Code with custom commands, agents, hooks, Skills, and MCP servers through the plugin system.3> Create custom plugins to extend Claude Code with slash commands, agents, hooks, Skills, and MCP servers.

4 

5Plugins let you extend Claude Code with custom functionality that can be shared across projects and teams. This guide covers creating your own plugins with slash commands, agents, Skills, hooks, and MCP servers.

6 

7Looking to install existing plugins? See [Discover and install plugins](/en/discover-plugins). For complete technical specifications, see [Plugins reference](/en/plugins-reference).

8 

9## When to use plugins vs standalone configuration

10 

11Claude Code supports two ways to add custom slash commands, agents, and hooks:

12 

13| Approach | Slash command names | Best for |

14| :---------------------------------------------------------- | :------------------- | :---------------------------------------------------------------------------------------------- |

15| **Standalone** (`.claude/` directory) | `/hello` | Personal workflows, project-specific customizations, quick experiments |

16| **Plugins** (directories with `.claude-plugin/plugin.json`) | `/plugin-name:hello` | Sharing with teammates, distributing to community, versioned releases, reusable across projects |

17 

18**Use standalone configuration when**:

19 

20* You're customizing Claude Code for a single project

21* The configuration is personal and doesn't need to be shared

22* You're experimenting with slash commands or hooks before packaging them

23* You want short slash command names like `/hello` or `/review`

24 

25**Use plugins when**:

26 

27* You want to share functionality with your team or community

28* You need the same slash commands/agents across multiple projects

29* You want version control and easy updates for your extensions

30* You're distributing through a marketplace

31* You're okay with namespaced slash commands like `/my-plugin:hello` (namespacing prevents conflicts between plugins)

4 32 

5<Tip>33<Tip>

6 For complete technical specifications and schemas, see [Plugins reference](/en/plugins-reference). For marketplace management, see [Plugin marketplaces](/en/plugin-marketplaces).34 Start with standalone configuration in `.claude/` for quick iteration, then [convert to a plugin](#convert-existing-configurations-to-plugins) when you're ready to share.

7</Tip>35</Tip>

8 36 

9Plugins let you extend Claude Code with custom functionality that can be shared across projects and teams. Install plugins from [marketplaces](/en/plugin-marketplaces) to add pre-built commands, agents, hooks, Skills, and MCP servers, or create your own to automate your workflows.

10 

11## Quickstart37## Quickstart

12 38 

13Let's create a simple greeting plugin to get you familiar with the plugin system. We'll build a working plugin that adds a custom command, test it locally, and understand the core concepts.39This quickstart walks you through creating a plugin with a custom slash command. You'll create a manifest (the configuration file that defines your plugin), add a slash command, and test it locally using the `--plugin-dir` flag.

14 40 

15### Prerequisites41### Prerequisites

16 42 

17* Claude Code installed on your machine43* Claude Code [installed and authenticated](/en/quickstart#step-1-install-claude-code)

18* Basic familiarity with command-line tools44* Claude Code version 1.0.33 or later (run `claude --version` to check)

45 

46<Note>

47 If you don't see the `/plugin` command, update Claude Code to the latest version. See [Troubleshooting](/en/troubleshooting) for upgrade instructions.

48</Note>

19 49 

20### Create your first plugin50### Create your first plugin

21 51 

22<Steps>52<Steps>

23 <Step title="Create the marketplace structure">

24 ```bash theme={null}

25 mkdir test-marketplace

26 cd test-marketplace

27 ```

28 </Step>

29 

30 <Step title="Create the plugin directory">53 <Step title="Create the plugin directory">

54 Every plugin lives in its own directory containing a manifest and your custom commands, agents, or hooks. Create one now:

55 

31 ```bash theme={null}56 ```bash theme={null}

32 mkdir my-first-plugin57 mkdir my-first-plugin

33 cd my-first-plugin

34 ```58 ```

35 </Step>59 </Step>

36 60 

37 <Step title="Create the plugin manifest">61 <Step title="Create the plugin manifest">

38 ```bash Create .claude-plugin/plugin.json theme={null}62 The manifest file at `.claude-plugin/plugin.json` defines your plugin's identity: its name, description, and version. Claude Code uses this metadata to display your plugin in the plugin manager.

39 mkdir .claude-plugin63 

40 cat > .claude-plugin/plugin.json << 'EOF'64 Create the `.claude-plugin` directory inside your plugin folder:

65 

66 ```bash theme={null}

67 mkdir my-first-plugin/.claude-plugin

68 ```

69 

70 Then create `my-first-plugin/.claude-plugin/plugin.json` with this content:

71 

72 ```json my-first-plugin/.claude-plugin/plugin.json theme={null}

41 {73 {

42 "name": "my-first-plugin",74 "name": "my-first-plugin",

43 "description": "A simple greeting plugin to learn the basics",75 "description": "A greeting plugin to learn the basics",

44 "version": "1.0.0",76 "version": "1.0.0",

45 "author": {77 "author": {

46 "name": "Your Name"78 "name": "Your Name"

47 }79 }

48 }80 }

49 EOF

50 ```81 ```

82 

83 | Field | Purpose |

84 | :------------ | :--------------------------------------------------------------------------------------------------------------------- |

85 | `name` | Unique identifier and slash command namespace. Slash commands are prefixed with this (e.g., `/my-first-plugin:hello`). |

86 | `description` | Shown in the plugin manager when browsing or installing plugins. |

87 | `version` | Track releases using [semantic versioning](/en/plugins-reference#version-management). |

88 | `author` | Optional. Helpful for attribution. |

89 

90 For additional fields like `homepage`, `repository`, and `license`, see the [full manifest schema](/en/plugins-reference#plugin-manifest-schema).

51 </Step>91 </Step>

52 92 

53 <Step title="Add a custom command">93 <Step title="Add a slash command">

54 ```bash Create commands/hello.md theme={null}94 Slash commands are Markdown files in the `commands/` directory. The filename becomes the slash command name, prefixed with the plugin's namespace (`hello.md` in a plugin named `my-first-plugin` creates `/my-first-plugin:hello`). The Markdown content tells Claude how to respond when someone runs the slash command.

55 mkdir commands95 

56 cat > commands/hello.md << 'EOF'96 Create a `commands` directory in your plugin folder:

97 

98 ```bash theme={null}

99 mkdir my-first-plugin/commands

100 ```

101 

102 Then create `my-first-plugin/commands/hello.md` with this content:

103 

104 ```markdown my-first-plugin/commands/hello.md theme={null}

57 ---105 ---

58 description: Greet the user with a personalized message106 description: Greet the user with a friendly message

59 ---107 ---

60 108 

61 # Hello Command109 # Hello Command

62 110 

63 Greet the user warmly and ask how you can help them today. Make the greeting personal and encouraging.111 Greet the user warmly and ask how you can help them today.

64 EOF

65 ```112 ```

66 </Step>113 </Step>

67 114 

68 <Step title="Create the marketplace manifest">115 <Step title="Test your plugin">

69 ```bash Create marketplace.json theme={null}116 Run Claude Code with the `--plugin-dir` flag to load your plugin:

70 cd ..

71 mkdir .claude-plugin

72 cat > .claude-plugin/marketplace.json << 'EOF'

73 {

74 "name": "test-marketplace",

75 "owner": {

76 "name": "Test User"

77 },

78 "plugins": [

79 {

80 "name": "my-first-plugin",

81 "source": "./my-first-plugin",

82 "description": "My first test plugin"

83 }

84 ]

85 }

86 EOF

87 ```

88 </Step>

89 117 

90 <Step title="Install and test your plugin">118 ```bash theme={null}

91 ```bash Start Claude Code from parent directory theme={null}119 claude --plugin-dir ./my-first-plugin

92 cd ..

93 claude

94 ```120 ```

95 121 

96 ```shell Add the test marketplace theme={null}122 Once Claude Code starts, try your new command:

97 /plugin marketplace add ./test-marketplace

98 ```

99 123 

100 ```shell Install your plugin theme={null}124 ```shell theme={null}

101 /plugin install my-first-plugin@test-marketplace125 /my-first-plugin:hello

102 ```126 ```

103 127 

104 Select "Install now". You'll then need to restart Claude Code in order to use the new plugin.128 You'll see Claude respond with a greeting. Run `/help` to see your command listed under the plugin namespace.

105 129 

106 ```shell Try your new command theme={null}130 <Note>

107 /hello131 **Why namespacing?** Plugin slash commands are always namespaced (like `/greet:hello`) to prevent conflicts when multiple plugins have commands with the same name.

108 ```

109 132 

110 You'll see Claude use your greeting command! Check `/help` to see your new command listed.133 To change the namespace prefix, update the `name` field in `plugin.json`.

134 </Note>

111 </Step>135 </Step>

112</Steps>

113 136 

114You've successfully created and tested a plugin with these key components:137 <Step title="Add slash command arguments">

115 138 Make your slash command dynamic by accepting user input. The `$ARGUMENTS` placeholder captures any text the user provides after the slash command.

116* **Plugin manifest** (`.claude-plugin/plugin.json`) - Describes your plugin's metadata

117* **Commands directory** (`commands/`) - Contains your custom slash commands

118* **Test marketplace** - Allows you to test your plugin locally

119 139 

120### Plugin structure overview140 Update your `hello.md` file:

121 141 

122Your plugin follows this basic structure:142 ```markdown my-first-plugin/commands/hello.md theme={null}

143 ---

144 description: Greet the user with a personalized message

145 ---

123 146 

124```147 # Hello Command

125my-first-plugin/

126├── .claude-plugin/

127│ └── plugin.json # Plugin metadata

128├── commands/ # Custom slash commands (optional)

129│ └── hello.md

130├── agents/ # Custom agents (optional)

131│ └── helper.md

132├── skills/ # Agent Skills (optional)

133│ └── my-skill/

134│ └── SKILL.md

135└── hooks/ # Event handlers (optional)

136 └── hooks.json

137```

138 148 

139**Additional components you can add:**149 Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.

150 ```

140 151 

141* **Commands**: Create markdown files in `commands/` directory152 Restart Claude Code to pick up the changes, then try the command with your name:

142* **Agents**: Create agent definitions in `agents/` directory

143* **Skills**: Create `SKILL.md` files in `skills/` directory

144* **Hooks**: Create `hooks/hooks.json` for event handling

145* **MCP servers**: Create `.mcp.json` for external tool integration

146 153 

147<Note>154 ```shell theme={null}

148 **Next steps**: Ready to add more features? Jump to [Develop more complex plugins](#develop-more-complex-plugins) to add agents, hooks, and MCP servers. For complete technical specifications of all plugin components, see [Plugins reference](/en/plugins-reference).155 /my-first-plugin:hello Alex

149</Note>156 ```

150 157 

151***158 Claude will greet you by name. For more argument options like `$1`, `$2` for individual parameters, see [Slash commands](/en/slash-commands).

159 </Step>

160</Steps>

152 161 

153## Install and manage plugins162You've successfully created and tested a plugin with these key components:

154 163 

155Learn how to discover, install, and manage plugins to extend your Claude Code capabilities.164* **Plugin manifest** (`.claude-plugin/plugin.json`): describes your plugin's metadata

165* **Commands directory** (`commands/`): contains your custom slash commands

166* **Command arguments** (`$ARGUMENTS`): captures user input for dynamic behavior

156 167 

157### Prerequisites168<Tip>

169 The `--plugin-dir` flag is useful for development and testing. When you're ready to share your plugin with others, see [Create and distribute a plugin marketplace](/en/plugin-marketplaces).

170</Tip>

158 171 

159* Claude Code installed and running172## Plugin structure overview

160* Basic familiarity with command-line interfaces

161 173 

162### Add marketplaces174You've created a plugin with a slash command, but plugins can include much more: custom agents, Skills, hooks, MCP servers, and LSP servers.

163 175 

164Marketplaces are catalogs of available plugins. Add them to discover and install plugins:176<Warning>

177 **Common mistake**: Don't put `commands/`, `agents/`, `skills/`, or `hooks/` inside the `.claude-plugin/` directory. Only `plugin.json` goes inside `.claude-plugin/`. All other directories must be at the plugin root level.

178</Warning>

165 179 

166```shell Add a marketplace theme={null}180| Directory | Location | Purpose |

167/plugin marketplace add your-org/claude-plugins181| :---------------- | :---------- | :---------------------------------------------- |

168```182| `.claude-plugin/` | Plugin root | Contains only `plugin.json` manifest (required) |

183| `commands/` | Plugin root | Slash commands as Markdown files |

184| `agents/` | Plugin root | Custom agent definitions |

185| `skills/` | Plugin root | Agent Skills with `SKILL.md` files |

186| `hooks/` | Plugin root | Event handlers in `hooks.json` |

187| `.mcp.json` | Plugin root | MCP server configurations |

188| `.lsp.json` | Plugin root | LSP server configurations for code intelligence |

169 189 

170```shell Browse available plugins theme={null}190<Note>

171/plugin191 **Next steps**: Ready to add more features? Jump to [Develop more complex plugins](#develop-more-complex-plugins) to add agents, hooks, MCP servers, and LSP servers. For complete technical specifications of all plugin components, see [Plugins reference](/en/plugins-reference).

172```192</Note>

173 193 

174For detailed marketplace management including Git repositories, local development, and team distribution, see [Plugin marketplaces](/en/plugin-marketplaces).194## Develop more complex plugins

175 195 

176### Install plugins196Once you're comfortable with basic plugins, you can create more sophisticated extensions.

177 197 

178#### Via interactive menu (recommended for discovery)198### Add Skills to your plugin

179 199 

180```shell Open the plugin management interface theme={null}200Plugins can include [Agent Skills](/en/skills) to extend Claude's capabilities. Skills are model-invoked; Claude autonomously uses them based on the task context.

181/plugin

182```

183 201 

184Select "Browse Plugins" to see available options with descriptions, features, and installation options.202To add Skills to your plugin, create a `skills/` directory at your plugin root and add Skill folders with `SKILL.md` files. Plugin Skills are automatically available when the plugin is installed.

185 203 

186#### Via direct commands (for quick installation)204For complete Skill authoring guidance, see [Agent Skills](/en/skills).

187 205 

188```shell Install a specific plugin theme={null}206### Add LSP servers to your plugin

189/plugin install formatter@your-org

190```

191 207 

192```shell Enable a disabled plugin theme={null}208<Tip>

193/plugin enable plugin-name@marketplace-name209 For common languages like TypeScript, Python, and Rust, install the pre-built LSP plugins from the official marketplace. Create custom LSP plugins only when you need support for languages not already covered.

194```210</Tip>

195 211 

196```shell Disable without uninstalling theme={null}212LSP (Language Server Protocol) plugins give Claude real-time code intelligence. If you need to support a language that doesn't have an official LSP plugin, you can create your own by adding an `.lsp.json` file to your plugin:

197/plugin disable plugin-name@marketplace-name

198```

199 213 

200```shell Completely remove a plugin theme={null}214```json .lsp.json theme={null}

201/plugin uninstall plugin-name@marketplace-name215{

216 "go": {

217 "command": "gopls",

218 "args": ["serve"],

219 "extensionToLanguage": {

220 ".go": "go"

221 }

222 }

223}

202```224```

203 225 

204### Installation scopes226Users installing your plugin must have the language server binary installed on their machine.

205 227 

206Plugins can be installed at different scopes to control their availability and sharing:228For complete LSP configuration options, see [LSP servers](/en/plugins-reference#lsp-servers).

207 229 

208| Scope | Location | Behavior |230### Organize complex plugins

209| :-------- | :---------------------------- | :-------------------------------------- |

210| `user` | `~/.claude/settings.json` | Available across all projects (default) |

211| `project` | `.claude/settings.json` | Shared with team via version control |

212| `local` | `.claude/settings.local.json` | Project-specific, gitignored |

213 

214**When to use each scope:**

215 231 

216* **User scope** (default): For plugins you want available in all your projects232For plugins with many components, organize your directory structure by functionality. For complete directory layouts and organization patterns, see [Plugin directory structure](/en/plugins-reference#plugin-directory-structure).

217* **Project scope**: For plugins your team should share (committed to git)

218* **Local scope**: For personal plugins in a specific project (not shared)

219 233 

220```shell Install to user scope (default) theme={null}234### Test your plugins locally

221claude plugin install formatter@your-org

222```

223 235 

224```shell Install to project scope (shared with team) theme={null}236Use the `--plugin-dir` flag to test plugins during development. This loads your plugin directly without requiring installation.

225claude plugin install formatter@your-org --scope project

226```

227 237 

228```shell Install to local scope (gitignored) theme={null}238```bash theme={null}

229claude plugin install formatter@your-org --scope local239claude --plugin-dir ./my-plugin