Skip to content

Plugins overview

What a Claude Code plugin is, how marketplaces and install scopes fit together, and when a plugin is worth it over a standalone skill or server.

A plugin is a folder that bundles several Claude Code extensions together so they install, update and switch off as one thing. Inside you can have skills, subagents, hooks, MCP servers and a JavaScript hooks module, plus a small manifest that names the bundle. Most people get plugins from a marketplace, but you can also point Claude Code at a folder on disk or write your own.

If you just want to see one working, open a terminal session, run /plugin, and pick something from the Discover tab. The rest of this page explains what you are actually installing.

Note: A Claude Code plugin is not the same thing as the Claude Code extension for VS Code or the JetBrains IDE plugin. Those put Claude Code inside your editor; see /docs/vs-code and /docs/jetbrains. Plugins for claude.ai chat and Cowork use the same format but load a different set of components.

What is inside a plugin

Picture a plugin called release-kit:

release-kit/
├── .claude-plugin/
│   └── plugin.json          # manifest: name, version, description
├── skills/
│   └── changelog/SKILL.md   # becomes /release-kit:changelog
├── agents/
│   └── release-auditor.md   # a subagent Claude can hand work to
├── hooks/
│   └── hooks.json           # commands that fire on lifecycle events
└── .mcp.json                # an MCP server that gives Claude extra tools

Each part does something different once the plugin loads:

ComponentWhere it livesWhat you get
Manifest.claude-plugin/plugin.jsonThe plugin's name (used as a namespace), plus optional version, description and other metadata
Skillsskills/<name>/SKILL.mdInstructions Claude pulls in when relevant, also runnable as /<plugin>:<skill>
Agentsagents/*.mdSubagent definitions Claude can delegate to
Hookshooks/hooks.jsonShell commands run at lifecycle points, such as after each file edit
Hooks moduleJavaScript functionsHooks written as code that can also draw panes and register commands. A plugin with one is called a mod
MCP servers.mcp.jsonTool servers that connect while the plugin is enabled

The manifest is optional in a strict sense, but almost every real plugin has one. Plugin components walks through every component type with an example.

Do you actually need a plugin?

Every component above works perfectly well without a plugin. A skill saved under ~/.claude/skills/ is available in all your projects. A hook in your settings file fires just the same. See /docs/skills, /docs/sub-agents, /docs/hooks-guide and /docs/mcp for the standalone versions.

Reach for a plugin when packaging is the point:

  • Installing: you want someone else's setup in one command, with updates arriving from their marketplace.
  • Sharing: you want teammates to get the same five skills and two hooks without copying files around.
  • Reuse: you want the same bundle in many repositories.
  • Releases: you want versioned, published releases others can pin.

My rule of thumb: if it is one skill for me, it stays in ~/.claude/skills/. The moment a second person needs it, it becomes a plugin.

The cost of an enabled plugin

An enabled plugin is present in every session, not just the ones where you call it. Before installing, know what that means:

  • Context: the name and description of each skill, agent and command that Claude may invoke by itself sits in Claude's context on every turn, so Claude knows it exists. Those tokens count toward usage and eat into the context window even when nothing from the plugin runs. Full skill or agent bodies load only when used. MCP tools follow the tool search behaviour.
  • Processes: the plugin's MCP servers start alongside each session, and its hooks fire on their events.
  • Permissions: everything the plugin runs, it runs as you. Read /docs/plugins/security first.

You can check the footprint at three points:

  1. Before installing: open the plugin from the Marketplaces tab of /plugin. Plugins in Anthropic's official marketplace show a Context cost estimate.
  2. After installing: /docs/plugins/measure explains how to read the numbers, and the Installed tab groups idle plugins under Not used recently.
  3. Pausing without removing: disable it from /plugin or with claude plugin disable in your shell. See /docs/plugins/install.

Marketplaces

A marketplace is a git repository or folder containing .claude-plugin/marketplace.json, which lists plugins and where to fetch each one. It is a catalogue, not a hosted shop. You add a marketplace once, then install by plugin@marketplace, for example commit-commands@claude-plugins-official.

Anthropic's official marketplace, claude-plugins-official, is added automatically the first time you start an interactive terminal session, unless your organisation's managed policy blocks it. The community and demo marketplaces are not added for you. /docs/plugins/anthropic-marketplaces explains the difference.

Note: "Claude Marketplace" at claude.com/marketplace is a website for browsing plugins, connectors and partners. It is not something you add with /plugin marketplace add.

The path is always the same: a marketplace lists a plugin, you install that plugin, Claude Code loads its components. While building your own you can skip the marketplace and load straight from a folder with --plugin-dir, covered in /docs/plugins/create.

Three layers before a skill appears

For an installed plugin's skill to show up in /, the plugin has to clear three layers:

  1. Settings list the marketplaces you have added and which plugins are enabled.
  2. Disk: ~/.claude/plugins/ holds what Claude Code has fetched.
  3. Session: plugins load at startup or when you run /reload-plugins.

When something is installed but missing, it is stuck at one of these. /docs/plugins/loading covers the precedence rules and file locations.

Trust tiers

A marketplace's name puts it in one of three tiers. The official and community names are only honoured for marketplaces that come from github.com/anthropics/ repositories.

TierExamplesWho runs it
Officialclaude-plugins-official, the demo marketplace claude-code-pluginsAnthropic
Communityclaude-communityAnthropic-hosted, community-submitted
Third-partyYour company's marketplace, a colleague's repoAnyone else

Whatever the tier, an installed plugin can execute code with your user privileges. The security page has a checklist. Organisations can allowlist or block marketplaces, force-install plugins and disable session-only loading through managed settings; see /docs/plugins/org.

Install scopes

When you install, you choose who the plugin is switched on for:

  • User: you, in every project on this machine.
  • Project: everyone in this repository, via the committed .claude/settings.json. Each collaborator still installs it on their own machine.
  • Local: you, in this repository only.

The terminal, the desktop app's local sessions and the VS Code extension share the same settings files, so a user-scope install in one shows up in all three. Cloud sessions, including claude.ai/code, do not load plugins from your local settings. /docs/plugins/install has the details.

Where to go next