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

.claude-plugin/plugin.json

The plugin's name, version and description. Optional

Skills

skills/<name>/SKILL.md

Skills Claude loads when relevant, run as /plugin-name:skill-name

Commands

commands/*.md

The older, flat form of skills

Agents

agents/*.md

Subagents Claude can delegate to

Hooks

hooks/hooks.json

Commands that run at lifecycle events, such as after every edit

MCP servers

.mcp.json

Tool servers that run while the plugin is enabled

LSP servers

.lsp.json

Language servers

Executables

bin/

Files on the Bash tool's PATH while the plugin is enabled

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

anthropics/claude-plugins-official

anthropics/claude-plugins-community

anthropics/claude-code

Name you install with

claude-plugins-official

claude-community

claude-code-plugins

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

/plugin marketplace add anthropics/claude-plugins-community

/plugin marketplace add anthropics/claude-code

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 /plugin marketplace add

GitHub repository

owner/repo, such as your-org/plugins, or your-org/plugins#v1.2.0 to pin a tag

Any git host

The full clone URL, scheme included, with an optional #ref

Local directory

A path such as ./my-marketplace

Hosted file

The URL of the marketplace.json file

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:

/plugin install deploy-helper --marketplace
/plugin install deploy-helper --marketplace
/plugin install deploy-helper --marketplace

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

~/.claude/settings.json

Project

Everyone who works in this repo

.claude/settings.json, which you commit

Local

You, in this repo only

.claude/settings.local.json

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 /plugins in 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.json turns on.

  • In scripts and CI, /plugin doesn't run in claude -p, but claude plugin install works from the shell. On a fresh machine, run claude plugin marketplace add anthropics/claude-plugins-official first, 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

/plugin, Discover tab

claude plugin install <plugin>@<marketplace>

List installed plugins

/plugin, Installed tab

claude plugin list

Enable or disable

/plugin enable, /plugin disable

claude plugin enable <plugin>@<marketplace>, claude plugin disable <plugin>@<marketplace>

Update one plugin

Installed tab, Update now

claude plugin update <plugin>@<marketplace>

Uninstall

/plugin uninstall <plugin>@<marketplace>

claude plugin uninstall <plugin>@<marketplace>

Apply changes

/reload-plugins

Start a new session

List marketplaces

/plugin marketplace list

claude plugin marketplace list

Remove a marketplace

/plugin marketplace remove <name>

claude plugin marketplace remove <name>

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:

mkdir -p
mkdir -p
mkdir -p

Save this as my-first-plugin/.claude-plugin/plugin.json:

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}
{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}
{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

And this as my-first-plugin/skills/hello/SKILL.md:




Rules for the manifest:

  • name is 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.

  • version holds 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.json goes 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 validate reports an error for names that start with claude- or anthropic-.

  • Reference bundled files with ${CLAUDE_PLUGIN_ROOT}, for example in an MCP server's args or a hook command, so paths resolve wherever the plugin is installed.

Validate it and run it

claude plugin validate ./my-first-plugin
claude --plugin-dir

claude plugin validate ./my-first-plugin
claude --plugin-dir

claude plugin validate ./my-first-plugin
claude --plugin-dir

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:

  1. Create my-plugin/.claude-plugin/plugin.json with a name, as above.

  2. Copy each of .claude/skills, .claude/agents and .claude/commands that exists into my-plugin/, for example with cp -r .claude/skills my-plugin/.

  3. Create my-plugin/hooks/hooks.json and paste in the hooks object from your .claude/settings.json or .claude/settings.local.json. The format is the same.

  4. Start Claude Code with claude --plugin-dir ./my-plugin and test each component under its new name. A skill that was /deploy is 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:

{
  "extraKnownMarketplaces": {
    "your-marketplace": {
      "source": { "source": "github", "repo": "your-org/your-marketplace" }
    }
  },
  "enabledPlugins": {
    "code-formatter@your-marketplace": true
  }
}
{
  "extraKnownMarketplaces": {
    "your-marketplace": {
      "source": { "source": "github", "repo": "your-org/your-marketplace" }
    }
  },
  "enabledPlugins": {
    "code-formatter@your-marketplace": true
  }
}
{
  "extraKnownMarketplaces": {
    "your-marketplace": {
      "source": { "source": "github", "repo": "your-org/your-marketplace" }
    }
  },
  "enabledPlugins": {
    "code-formatter@your-marketplace": true
  }
}

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:

{
  "name": "your-marketplace",
  "owner": { "name": "Platform team" },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/code-formatter",
      "description": "Formats files after every edit"
    },
    {
      "name": "deploy-helper",
      "source": { "source": "github", "repo": "your-org/deploy-helper" },
      "description": "Deploy and rollback commands"
    }
  ]
}
{
  "name": "your-marketplace",
  "owner": { "name": "Platform team" },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/code-formatter",
      "description": "Formats files after every edit"
    },
    {
      "name": "deploy-helper",
      "source": { "source": "github", "repo": "your-org/deploy-helper" },
      "description": "Deploy and rollback commands"
    }
  ]
}
{
  "name": "your-marketplace",
  "owner": { "name": "Platform team" },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/code-formatter",
      "description": "Formats files after every edit"
    },
    {
      "name": "deploy-helper",
      "source": { "source": "github", "repo": "your-org/deploy-helper" },
      "description": "Deploy and rollback commands"
    }
  ]
}

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:

  • strictKnownMarketplaces is 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.

  • blockedMarketplaces is 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 the PATH of 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:

  1. Run claude plugin marketplace list to see where each marketplace came from.

  2. Read the Will install list in the plugin's details in /plugin.

  3. Open the plugin's source and read hooks/hooks.json, .mcp.json and everything in bin/. The details pane shows that a hook exists, not what it runs.

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

Table of contents