Blog
Claude Code plugins: how to install, build and share them
What a plugin bundles, how plugin marketplaces work, how to build a plugin from an empty folder, and how teams roll plugins out.
Alex Mercer
A Claude Code plugin is a directory that packages skills, subagents, hooks and MCP servers so Claude Code can install, enable and update them as one unit. Most plugins come from a marketplace, a catalog you register once with /plugin marketplace add, and you install one by name with /plugin install <plugin>@<marketplace>.
Anthropic's official marketplace is added for you the first time you start an interactive Claude Code session in a terminal, so you can browse it right away with /plugin. Plugin details come from Anthropic's plugin docs as of October 12, 2026. For the rest of Claude Code, start with our guide on how to use Claude Code.
What a Claude Code plugin bundles
A plugin is a folder of components, usually with a manifest at .claude-plugin/plugin.json that names it. Each component type has a default place in the folder:
Component | Default location | What you get |
|---|---|---|
Manifest |
| The plugin's name, version and description. Optional |
Skills |
| Skills Claude loads when relevant, run as |
Commands |
| The older, flat form of skills |
Agents |
| Subagents Claude can delegate to |
Hooks |
| Commands that run at lifecycle events, such as after every edit |
MCP servers |
| Tool servers that run while the plugin is enabled |
LSP servers |
| Language servers |
Executables |
| Files on the Bash tool's |
Plugins can also ship output styles, themes, monitors, workflows and default settings. A plugin that includes a hooks module (hooks written as JavaScript functions, which can also draw panes and add commands) is called a mod.
A CLAUDE.md at the plugin root isn't loaded as context. Instructions that should reach Claude belong in a skill.
When you need a plugin
Skills, subagents, hooks and MCP servers all work without a plugin. Anthropic's docs suggest keeping that standalone setup while it serves one project or one person, and making a plugin when you want to share it with teammates, install it in several projects or publish versioned releases.
The trade-off is cost. An enabled plugin is part of every session, not only the ones where you use it:
The name and description of every skill, agent and command Claude can invoke on its own sit in context on every turn. The full text loads only when it's used.
The plugin's MCP servers run alongside each session, and its hooks fire on their events.
Whatever the plugin runs, it runs as you.
For an installed plugin, claude plugin details <name> prints an Always-on line: the tokens the plugin adds to every session where it's enabled.
How the Claude Code plugin marketplace works
A plugin marketplace is a repository or directory with a .claude-plugin/marketplace.json file that lists plugins and where to fetch each one. It's a catalog, not a hosted store. You add it once, then install its plugins by name.
Claude Marketplace, the website at claude.com/marketplace, is a different thing. You browse plugins, connectors and partners there, but it isn't a marketplace you add with /plugin marketplace add. For a plugin listed there, the site's Claude Code button copies the install command.
Anthropic runs three general-purpose marketplaces:
Official | Community | Demo | |
|---|---|---|---|
Repository |
|
|
|
Name you install with |
|
|
|
What's in it | Plugins Anthropic maintains, plus plugins from partners and other authors | Third-party plugins | A few example plugins |
How you get it | Added the first time you start an interactive terminal session |
|
|
If an older tutorial tells you to add anthropics/claude-code, that's the demo marketplace, not the official one. Most of its plugins are also in the official marketplace under the same names, so install them from claude-plugins-official to avoid keeping two copies.
Every other marketplace is third-party, including one your company runs. Whatever the tier, a plugin you install can run code with your user privileges, so the review steps below apply to all of them.
Add a marketplace and install a plugin
Install from the official marketplace
In a terminal session, name the plugin and its marketplace. This example installs commit-commands, which adds commands for committing, pushing and opening pull requests:
Inside a session, this opens the plugin's details instead of installing right away. Read the Will install list (the commands, agents, skills, hooks, and MCP and LSP servers it adds), then pick a scope. Plugins in the official marketplace also show a Context cost estimate: the tokens added on every turn, and the tokens added when Claude loads its skills and agents.
The install summary tells you whether the plugin is active. If it says Run /reload-plugins to apply., Claude Code runs that reload for you. Then type / and look for the plugin's commands, in this case /commit-commands:commit.
To browse instead, run /plugin on its own. The Discover tab lists plugins from every marketplace you've added, Installed manages what you have, Marketplaces manages your sources, and Errors shows anything that failed to load.
Most plugins in the official marketplace come from partners and other authors. Anthropic maintains a smaller set of its own, such as commit-commands, code-review, feature-dev and the language server plugins for code intelligence. The catalog changes often, so Anthropic's marketplace docs don't list it; search the Discover tab, or browse Claude Marketplace on the web, which shows install counts and marks some plugins Anthropic verified.
Add another marketplace
To install from any other marketplace, add it first:
Source | What you type after |
|---|---|
GitHub repository |
|
Any git host | The full clone URL, scheme included, with an optional |
Local directory | A path such as |
Hosted file | The URL of the |
Claude Code reads a bare host/path or name/name as GitHub shorthand, so other hosts need the full URL and a relative local path must start with ./ or ../. The marketplace registers under the name field in its marketplace.json, not the repository name, and that name is what goes after the @ when you install.
On Claude Code v2.1.275 or later, you can add a marketplace and install from it in one step:
Private repositories work with the git credentials already on your machine. Claude Code never prompts for a password, so authenticate first: for HTTPS, a credential helper such as the one gh auth login sets up; for SSH, a known host and a key that works without a passphrase prompt.
Example: cubic's plugin
As an example, cubic's docs give two commands that install the plugin for cubic, our AI code reviewer, from inside Claude Code:
According to cubic's skills docs, the plugin includes cubic's skills, namespaced slash commands such as /cubic:run-review, and the connection to cubic's MCP server. To finish, run /mcp, choose cubic and complete the browser sign-in. Our Claude Code review guide follows the plugin from there to fixed findings. The skills themselves are covered in cubic's Skills and MCP launch post, and our guide to AI code review explains how AI review works and what it catches.
Choose an install scope
Scope | Who gets it | Where it's recorded |
|---|---|---|
User | You, in every project on this machine |
|
Project | Everyone who works in this repo |
|
Local | You, in this repo only |
|
When a plugin is set at several scopes, local overrides project and project overrides user. The terminal, the desktop app's local sessions and the VS Code extension on one computer read the same settings files, so a user-scope install in one shows up in the others.
A project-scope install turns the plugin on for collaborators but doesn't download it to their machines. Each collaborator runs claude plugin install <name>@<marketplace> --scope project once.
Other places you run Claude Code
In the desktop app's Code tab, in a local or SSH session, click + next to the prompt box, then Plugins and Add plugin.
In VS Code, type
/pluginsin the Claude Code panel to open Manage plugins.Cloud sessions, including claude.ai/code in the browser, have no plugin browser. They don't load the plugins installed on your machine or the ones your repo's
.claude/settings.jsonturns on.In scripts and CI,
/plugindoesn't run inclaude -p, butclaude plugin installworks from the shell. On a fresh machine, runclaude plugin marketplace add anthropics/claude-plugins-officialfirst, because the official marketplace is only added when someone opens an interactive session.
Manage and update plugins
Task | Inside a session | From your shell |
|---|---|---|
Browse and install |
|
|
List installed plugins |
|
|
Enable or disable |
|
|
Update one plugin | Installed tab, Update now |
|
Uninstall |
|
|
Apply changes |
| Start a new session |
List marketplaces |
|
|
Remove a marketplace |
|
|
Updates depend on the marketplace. Auto-update is on by default for Anthropic's official marketplace (and most of its other official names) and for marketplaces added from claude.ai. It's off for everything else, including the community marketplace, third-party marketplaces and local ones. You can turn it on or off per marketplace on the Marketplaces tab. A running session keeps the versions it loaded until you run /reload-plugins or start a new session.
There's no command that updates every plugin at once. Update marketplace on the Marketplaces tab refreshes one marketplace and updates the plugins you installed from it, and reports any it left for you to update yourself. Removing a marketplace uninstalls every plugin you installed from it.
To find plugins you could drop, check the Not used recently group on the Installed tab.
Build your own plugin
Create the folder and manifest
A plugin can be as small as one skill. Start with the folder:
Save this as my-first-plugin/.claude-plugin/plugin.json:
And this as my-first-plugin/skills/hello/SKILL.md:
Rules for the manifest:
nameis the only required field. Use kebab-case with no spaces. It prefixes every skill and agent the plugin provides, so this skill runs as/my-first-plugin:hello.The manifest itself is optional. Without one, Claude Code loads components from the default locations and takes the name from the marketplace entry, or from the folder name when you load the plugin with
--plugin-dir.versionholds users on a release. Setting it keeps users on that version until you change it, so if you set it, bump it with each release.Only
plugin.jsongoes in.claude-plugin/. Skills, agents and hooks saved inside that folder don't load. Put them at the plugin root.Avoid reserved names.
claude plugin validatereports an error for names that start withclaude-oranthropic-.Reference bundled files with
${CLAUDE_PLUGIN_ROOT}, for example in an MCP server'sargsor a hook command, so paths resolve wherever the plugin is installed.
Validate it and run it
claude plugin validate checks the manifest and the frontmatter of every skill, agent and command file, and prints ✔ Validation passed when everything is clean. Add --strict in CI to fail on warnings too. --plugin-dir loads the plugin for one session without installing it; repeat the flag to load several. After you edit the plugin's files, run /reload-plugins in the session.
If something doesn't show up, check the Errors tab in /plugin, then run claude plugin list. A common cause is a skills/ folder saved inside .claude-plugin/ instead of at the plugin root.
A plugin that loads can still fail to change what Claude does. claude plugin eval runs test cases with and without the plugin and scores the difference. For a guided build, Anthropic's plugin-dev plugin in the official marketplace adds /plugin-dev:create-plugin, which walks you through designing, creating and validating a plugin.
Convert an existing .claude/ setup
If you already have skills, agents, commands or hooks in a project's .claude/ folder, move them into a plugin instead of rewriting them:
Create
my-plugin/.claude-plugin/plugin.jsonwith a name, as above.Copy each of
.claude/skills,.claude/agentsand.claude/commandsthat exists intomy-plugin/, for example withcp -r .claude/skills my-plugin/.Create
my-plugin/hooks/hooks.jsonand paste in thehooksobject from your.claude/settings.jsonor.claude/settings.local.json. The format is the same.Start Claude Code with
claude --plugin-dir ./my-pluginand test each component under its new name. A skill that was/deployis now/my-plugin:deploy.
While the originals are still in .claude/, both copies load. Skills and agents don't collide, because the plugin's copies carry its prefix, but a hook defined in both places runs twice. Delete the originals once the plugin works.
For personal tools there's a shortcut: claude plugin init my-tool scaffolds a plugin in ~/.claude/skills/my-tool/ that loads in every session as my-tool@skills-dir, with no marketplace or install step.
To write the skills that go inside a plugin, see our guide to Claude Code skills. For the hooks a plugin can ship, see Claude Code hooks.
Claude Code plugins for teams
In the latest full week, Claude Code wrote 78.1% of the AI-written code that cubic reviewed, according to Bug Bench. That share covers code reviewed by cubic, not the whole market, and our guide to the best AI coding tools compares the agents themselves. When that much code comes from one agent, a shared plugin setup is how a team gives everyone the same skills, hooks and tools.
There are three levels, from lightest to strictest.
1. Share through the repository
Register your marketplace and enable plugins in the repo's committed .claude/settings.json. Running claude plugin marketplace add your-org/your-marketplace --scope project once writes the marketplace entry for you, and installing a plugin at project scope adds it to enabledPlugins. With example names, the result looks like this:
Teammates get the marketplace once they accept the workspace trust dialog for the folder. In an untrusted folder, Claude Code ignores these entries without a message. Plugins that the marketplace lists by a relative path then load from the marketplace copy. Plugins whose entry points somewhere else, such as their own GitHub repository, still need each person to run claude plugin install <name>@<marketplace> --scope project once.
2. Run a team marketplace
A marketplace is a folder with .claude-plugin/marketplace.json and, usually, the plugins themselves. The file needs a name, an owner and a plugins array, and each entry needs a name and a source. An example with one local plugin and one on GitHub:
A plugin's source can be a relative path inside the marketplace, a GitHub repository, a subdirectory of another repository (git-subdir), a git URL, a zip archive, an npm package, or a command that produces the plugin directory. Run claude plugin validate ./your-marketplace after every edit, and install from the marketplace on your own machine before you share it.
Host the marketplace on GitHub or another git host, as a hosted marketplace.json URL, or in a shared directory. People add it once with /plugin marketplace add your-org/your-marketplace and can pin a branch or tag with #<ref>. Auto-update is off by default for third-party marketplaces, so tell your team to turn it on, or set it centrally as below.
3. Enforce it with managed settings
Organizations can deliver the same keys through managed settings, which take precedence over every other scope. A plugin set to true in managed enabledPlugins is installed at the start of each user's next session, and disabling it at their own scope doesn't stop it from loading. Set a plugin to false there to block it at every scope and hide it from the marketplace listing. A managed marketplace entry can also set "autoUpdate": true.
Two more managed keys limit where plugins can come from:
strictKnownMarketplacesis an allowlist of marketplace sources. An entry such as{ "source": "github", "repo": "your-org/*" }covers every repository under your GitHub organization (Claude Code v2.1.223 or later). An empty list,[], blocks every marketplace, including Anthropic's official one.blockedMarketplacesis a blocklist.
If you set an allowlist, add { "source": "skills-dir" } to it, or the plugins people keep in their skills directories stop loading. Anthropic's organization plugin docs cover the rest, including update policy and auditing. For getting a team's agents to follow the same conventions beyond plugins, see how to configure coding agents that follow your team's standards.
Review a plugin before you install it
A plugin can run code on your machine and put instructions in front of Claude:
Hooks run shell commands at lifecycle events, with your full user permissions.
Stdio MCP servers and LSP servers run as processes that Claude Code starts on your machine.
bin/executables join thePATHof the Bash tool's shell.Skills, commands and agents enter Claude's context as instructions.
Claude Code's permission rules and sandbox cover the tool calls Claude makes, not the code a plugin runs on its own: hooks and MCP servers run outside the sandbox. Auto-update can also change a plugin's files after you've read them.
Before you install from a source you don't know:
Run
claude plugin marketplace listto see where each marketplace came from.Read the Will install list in the plugin's details in
/plugin.Open the plugin's source and read
hooks/hooks.json,.mcp.jsonand everything inbin/. The details pane shows that a hook exists, not what it runs.Clone the repository and run
claude --plugin-dir <plugin-directory> plugin details <plugin-name>to print the full component inventory without starting a session.
FAQ
What is the difference between a Claude Code plugin and a skill?
A skill is one capability: a folder with a SKILL.md that Claude follows. A plugin is a package that can hold many skills plus subagents, hooks and MCP servers, installed and updated as one unit. Plugin skills are namespaced, so a deploy skill in a plugin named tools runs as /tools:deploy.
Are Claude Code plugins safe?
A plugin runs with your user privileges whichever marketplace it comes from, and its hooks and MCP servers run outside Claude Code's sandbox. Check where it comes from, read its hooks and server configs before you install, and keep auto-update off for sources you haven't vetted. Organizations can limit sources with strictKnownMarketplaces in managed settings.
Where does Claude Code install plugins?
Claude Code keeps what it fetches and installs under ~/.claude/plugins/, with each installed copy in ~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/. Which plugins are enabled is recorded in your settings files: ~/.claude/settings.json for user scope, .claude/settings.json for project scope and .claude/settings.local.json for local scope.
Do plugins work in Claude Code on the web?
Cloud sessions, including claude.ai/code in the browser, don't load the plugins you installed locally or the plugins a repo's .claude/settings.json enables. Project skills committed to the repo's .claude/skills/ do load there. For plugins an organization distributes, see Anthropic's organization plugin docs.
