Claude Code Plugins: How They Bundle Skills, Commands, Agents, Hooks and MCP Servers

A Claude Code plugin is a directory that packages skills, subagents, hooks, MCP servers and a few other component types so Claude Code installs and loads them as one unit. You usually get plugins from a marketplace, which is a git repository or URL with a .claude-plugin/marketplace.json catalog. Run /plugin in a session to browse and install, or claude plugin install <name>@<marketplace> from your shell. If you only need one skill in one place, a plain SKILL.md folder is simpler than a plugin.

This guide covers the plugin layout and manifest, marketplaces, install and management commands, team distribution, and what to review before you install anything.

What a plugin contains

A plugin is a folder of components with an optional manifest. Every component works on its own outside a plugin; the plugin is the package that lets you install, version, enable and remove them together.

Component	Default location in the plugin	What you get
Manifest	.claude-plugin/plugin.json	Name, version, description, and optional settings
Skills	skills/<name>/SKILL.md	Skills Claude loads on demand, run as /<plugin>:<skill>
Commands	commands/*.md	Flat command files; the docs recommend skills/ for new plugins
Agents	agents/*.md	Subagents Claude can delegate to
Hooks	hooks/hooks.json	Commands that run on 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 for code intelligence
Executables	bin/	Files on the Bash tool’s PATH while the plugin is enabled

There are more types, including output styles, themes, monitors and workflows. The official plugin manifest reference lists them all.

Everything in a plugin is namespaced under the plugin’s name. A review skill inside acme-tools runs as /acme-tools:review, and an agent reviewer appears as acme-tools:reviewer. That is why plugin skills never collide with your personal or project skills of the same name.

Plugin folder layout

Only plugin.json goes inside .claude-plugin/. Every other directory sits at the plugin root. Putting skills/ inside .claude-plugin/ is the most common layout mistake.

acme-tools/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── review/
│       └── SKILL.md
├── agents/
│   └── security-reviewer.md
├── hooks/
│   └── hooks.json
├── scripts/
│   └── format.sh
└── .mcp.json

The plugin.json manifest

The manifest is optional. Without one, Claude Code loads whatever it finds in the default locations and takes the name from the marketplace entry, or from the folder name when you load the plugin with --plugin-dir. Write one when you want metadata, a version, or components outside the default folders.

name is the only required field. A typical manifest:

{
  "name": "acme-tools",
  "version": "1.2.0",
  "description": "Code review, security review, and formatting hooks for Acme services",
  "author": { "name": "Acme Platform Team", "email": "[email protected]" },
  "repository": "https://github.com/acme/acme-tools",
  "license": "MIT",
  "keywords": ["review", "security"]
}

Fields worth knowing:

• name: kebab-case, no spaces, @ or :. Names that pass as Anthropic’s own, such as anything starting with claude- or anthropic-, fail validation.
• version: setting it pins users to that version until you change it. Bump it on every release, or leave it out so updates track git commits. Do not set it in both plugin.json and the marketplace entry.
• defaultEnabled: defaults to true. Set false for a plugin that should install switched off.
• userConfig: values Claude Code prompts for when the plugin is enabled, such as an API endpoint. Mark tokens "sensitive": true so they go to the system credential store instead of settings.json.
• dependencies: other plugins that must be enabled for this one to work.
• Component keys (skills, commands, agents, hooks, mcpServers): point at non-default paths. Paths must start with ./ and stay inside the plugin. skills adds to the default skills/ scan, while commands and agents replace their default folders.

Scripts that hooks and MCP servers run should be referenced through ${CLAUDE_PLUGIN_ROOT}, which resolves to the installed copy. That directory changes on every update, so persistent state such as node_modules or caches belongs in ${CLAUDE_PLUGIN_DATA}.

A plugin hooks file wraps its events in a top-level "hooks" key:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/format.sh" }
        ]
      }
    ]
  }
}

Check your work with the validator, and test without installing by loading the folder for one session:

claude plugin validate ./acme-tools          # add --strict in CI to fail on warnings
claude --plugin-dir ./acme-tools             # loads the plugin for this session only

After editing files during a session, run /reload-plugins to pick up the changes. For the authoring side of each component, see skill-authoring, subagent-design, hooks-automation and mcp-server-builder.

Plugin marketplaces and marketplace.json

A marketplace is a catalog, not a hosted store. It is a directory or repository with .claude-plugin/marketplace.json that lists plugins and where to fetch each one. Claude Code adds Anthropic’s official marketplace, claude-plugins-official, the first time you start an interactive terminal session. Every other marketplace you add yourself.

The file needs a name, an owner, and a plugins array. Each entry needs a name and a source:

{
  "name": "acme",
  "owner": { "name": "Acme Platform Team" },
  "plugins": [
    {
      "name": "acme-tools",
      "source": "./plugins/acme-tools",
      "description": "Code review, security review, and formatting hooks"
    },
    {
      "name": "deploy-helper",
      "source": { "source": "github", "repo": "acme/deploy-helper" }
    }
  ]
}

Rules that prevent most failed installs:

• Relative paths start at the marketplace root, the directory that contains .claude-plugin/, and cannot use ...
• Keep the entry name and the manifest name the same. The entry name is what people install (acme-tools@acme); the manifest name is the skill prefix. When they differ, installs fail with a “not found in marketplace” error.
• Pick the right source type. Besides relative paths and github, an entry can use git-subdir for a folder in a monorepo, url for a git repository on any host, archive for a zip over HTTPS, npm, or command.
• Avoid reserved names. Names such as claude-plugins-official are reserved for Anthropic’s marketplaces and are refused when added.

Run claude plugin validate ./my-marketplace after every edit. plugin-marketplace-publisher scaffolds and checks both files.

How to install a Claude Code plugin

In a session, add the marketplace once, then install from it:

/plugin marketplace add acme/acme-claude
/plugin install acme-tools@acme

In a session, /plugin install does not install immediately. It opens the plugin’s details so you can review the Will install list (commands, agents, skills, hooks, MCP and LSP servers) and choose a scope. Run /plugin with no arguments to browse the Discover tab instead.

/plugin marketplace add accepts several source forms:

Source	Example
GitHub repository	acme/acme-claude, or acme/acme-claude#v1.2.0 to pin a tag
Any git host	https://gitlab.example.com/team/plugins.git
Local directory	./my-marketplace (start relative paths with ./)
Hosted file	https://plugins.example.com/marketplace.json

Private repositories work with the git credentials already on your machine. Claude Code never prompts for a password, so authenticate first (for GitHub, gh auth login).

Install scopes

Scope	Who gets it	Written to
User	You, in every project	~/.claude/settings.json
Project	Everyone working in the repository	.claude/settings.json (committed)
Local	You, in this repository only	.claude/settings.local.json

When the same plugin is set at several scopes, local overrides project, which overrides user.

The claude plugin CLI

The main /plugin actions are also available from your shell, which suits setup scripts and non-interactive runs where /plugin is unavailable:

claude plugin marketplace add acme/acme-claude
claude plugin install acme-tools@acme --scope project
claude plugin list                      # version, scope, and status
claude plugin details acme-tools        # component inventory and token cost
claude plugin disable acme-tools@acme
claude plugin enable acme-tools@acme
claude plugin update acme-tools@acme
claude plugin uninstall acme-tools@acme --scope project
claude plugin marketplace update acme
claude plugin marketplace remove acme   # also uninstalls its plugins

Plugins installed from the shell load in your next session, or after /reload-plugins in an open one. Run claude plugin --help to see which subcommands your version has.

Enabling, disabling, and updating

Disabling keeps a plugin installed but stops it loading. Use the Installed tab in /plugin (press Space on a plugin to toggle it) or claude plugin disable. The same tab groups plugins you have not used recently, which are good candidates to turn off.

Auto-update is on by default for Anthropic’s official marketplace and off for third-party marketplaces, including your company’s. Turn it on per marketplace from the Marketplaces tab, or update deliberately with claude plugin update.

An enabled plugin costs something in every session. The name and description of each skill and agent Claude can invoke on its own sit in context on every turn, its MCP servers run, and its hooks fire. The Always-on line in claude plugin details <name> shows that per-session token cost.

Distributing plugins to a team through settings

To make a marketplace part of a repository rather than a README step, run this once from the repo and commit the result:

claude plugin marketplace add acme/acme-claude --scope project

That writes an extraKnownMarketplaces entry to .claude/settings.json. Add the plugins the project expects under enabledPlugins:

{
  "extraKnownMarketplaces": {
    "acme": { "source": { "source": "github", "repo": "acme/acme-claude" } }
  },
  "enabledPlugins": { "acme-tools@acme": true }
}

Two behaviors to plan for:

• Folder trust comes first. Claude Code registers a project’s marketplace only after the contributor accepts the workspace trust dialog for that folder. In an untrusted folder the entry is ignored silently.
• External sources still need an install. A plugin listed by relative path loads from the marketplace copy once the marketplace is registered. A plugin whose entry points at its own repository does not install from settings alone; each contributor sees an “enabled in project settings but isn’t installed” message until they run claude plugin install <name>@<marketplace> --scope project.

For fleet-wide control, administrators can set the same keys in managed settings, plus strictKnownMarketplaces to allowlist marketplace sources. The team sharing guide covers versioning and review for shared skills.

When to ship a plain skill vs a plugin

Situation	Use
One skill for yourself	Plain skill in ~/.claude/skills/
Skills tied to one repository	Plain skills committed in .claude/skills/
The same skills copied into a third repository	Plugin
Skills that need a hook, agent, or MCP server alongside them	Plugin
Versioned releases that teammates update on their own schedule	Plugin
A skill that should work on claude.ai and the API too	Plain skill, kept portable

A plain skill has no manifest, no marketplace, and no install step for anyone who clones the repo. A plugin earns its overhead when several components must travel together, or when one toolkit needs to reach many repositories with explicit versions. Personal vs project skills helps with the first two rows, and Skills vs commands, subagents and MCP explains what each component is for.

Security review before installing a plugin

A plugin runs code with your user privileges. Hooks, monitors, MCP servers and LSP servers run outside Claude Code’s sandbox, and permission rules apply only to Claude’s own tool calls. Skills and agents enter context as instructions that shape what Claude does with the tools it has. The marketplace name tells you who publishes the catalog, not what each plugin does.

Before installing:

1. Check the source. claude plugin marketplace list prints where each marketplace came from.
2. Read the Will install list in the /plugin details pane.
3. Read the files that execute. The pane shows that a hook exists, not what it runs. Open hooks/hooks.json, .mcp.json, and every file in bin/.
4. Inventory a local clone without starting a session: claude --plugin-dir <plugin-dir> plugin details <name>.
5. Decide on updates. With auto-update on, the files you reviewed can change in the background. Leaving it off for third-party marketplaces lets you re-review before each update.

The skill safety guide lists red flags in skill content, and permissions-policy helps tighten what Claude’s tool calls can do.

Next steps

• Install single skills without a plugin: How to install Claude Code skills
• Share with your team: Share skills with your team
• Turn old command files into plugin-ready skills: command-to-skill-migration
• Publish a marketplace: plugin-marketplace-publisher
• Browse the claude-code category