Claude Code plugins: what they are and cost

What a Claude Code plugin is

A Claude Code plugin is one directory of components that Claude Code loads and manages as a single unit. Those components are skills, agents, hooks, MCP servers, LSP servers, and background monitors. Installing a plugin adds all of its parts at once, under one name, and disabling it removes them the same way.

A plugin gives the agent no ability it did not already have. Every part inside a plugin is something you can write by hand in a .claude/ directory. The plugin is the packaging layer: a way to version those parts, hand them to fifteen people, and update them later without asking everyone to copy files. That is the whole idea, and most confusion about plugins comes from expecting them to be a new kind of capability.

The optional manifest at .claude-plugin/plugin.json names the plugin, and that name becomes a namespace. A skill in a plugin called commit-commands is invoked as /commit-commands:commit, so two plugins can each ship a skill called commit without one shadowing the other. Plugin agents are scoped the same way in the @-mention list, as plugin-name:agent-name.

Plugin, skill, MCP server, or rules file

These four words get used as if they compete. They do not, and the boundary is worth stating once.

• A skill is one unit of instruction that Claude loads when the task calls for it. See what an Agent Skill actually is.
• An MCP server is a separate process that exposes tools to the agent over a protocol, often a network service you run yourself.
• A rules file such as CLAUDE.md is project context that is read at session start and applies to everything.
• A plugin is a container that can hold skills, agents, hooks, and MCP server definitions together, plus a version number and a distribution channel.

So the question a plugin answers is not "what can the agent do". It is "how do I ship this to my team and update it next month". If you are choosing between the first three, the comparison of skills, MCP servers and rules files covers that decision in detail. If the MCP part is what you care about, running your own MCP servers on a VPS covers the hosting side.

Where plugins live and what is inside one

A plugin installed from a marketplace is copied into a local cache at ~/.claude/plugins/cache rather than run from wherever it was cloned. Each installed version gets its own directory. When you update or uninstall, the old version directory is marked orphaned and deleted about two weeks later, so a session that already loaded the old version keeps working instead of failing mid-task.

Because the path changes on every update, a plugin must never hardcode its own location. Hooks and MCP configs inside a plugin use ${CLAUDE_PLUGIN_ROOT}, which resolves to the current install directory. State that must survive an update goes in ${CLAUDE_PLUGIN_DATA}, which resolves to a stable directory under ~/.claude/plugins/data/.

Only the plugin's own directory is copied into the cache, which has a consequence people hit late. A path that points outside the plugin root, such as ../shared-utils, works while you develop with a local path and breaks after installation, because those files were never copied.

The layout looks like this.

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── code-review/
│       └── SKILL.md
├── agents/
├── hooks/
│   └── hooks.json
├── .mcp.json
└── bin/

Only plugin.json goes inside .claude-plugin/. Everything else sits at the plugin root. Putting skills/ or hooks/ inside .claude-plugin/ is the most common reason a plugin installs cleanly and then does nothing at all: Claude Code looks for those directories at the root, finds none, and loads a plugin with no components.

The manifest itself is small.

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

How to install a Claude Code plugin

Installing is two steps, and the first one installs nothing. You add a marketplace, which is a catalog of plugins, then you install individual plugins from it. Anthropic's official marketplace, claude-plugins-official, is registered for you the first time you start Claude Code interactively. Others you add yourself.

/plugin marketplace add anthropics/claude-code
/plugin install commit-commands@claude-code-plugins

Note that the repository is anthropics/claude-code while the marketplace is named claude-code-plugins. The name comes from the catalog file inside the repository, not from the repository path, so read the marketplace name off the Marketplaces tab of /plugin before you type an install command.

After the install, read the summary line. Plugin is now active. means the components are loaded in this session. Run /reload-plugins to activate. means they are not, and you need to run that command. If /reload-plugins warns that it would re-read the conversation, rerun it as /reload-plugins --force. Then confirm the plugin is really there: /plugin shows it under the Installed tab, /help lists its skills under Custom commands, and anything that failed to load shows up under the Errors tab with the reason.

Installing asks for a scope, and the scope decides who gets the plugin. User scope is you, in every project. Project scope writes the plugin into the repository's .claude/settings.json under enabledPlugins, so everyone who clones the repository is offered it. Local scope is you, in this repository only.

For a script, a Dockerfile, or any session where an interactive panel is not available, use the shell form instead. It installs to user scope unless you pass --scope.

claude plugin install commit-commands@claude-code-plugins --scope project
claude plugin list

claude plugin install runs outside a session, so a session that is already open will not see the new plugin until you run /reload-plugins or start a new session.

Managing what you have is the same pattern in both places. /plugin list prints what is installed, and accepts --enabled or --disabled. /plugin disable name@marketplace turns a plugin off without removing it, /plugin enable turns it back on, and /plugin uninstall removes it. The slash-command forms open the plugin panel to apply the change, which is why the claude plugin ... shell equivalents are the ones to use in scripts.

To hand a marketplace to a whole team, put it in the project's .claude/settings.json. Members are prompted to install it once they trust the repository folder.

{
  "extraKnownMarketplaces": {
    "my-team-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

While you are building your own plugin, skip the marketplace entirely. claude --plugin-dir ./my-plugin loads a directory for that session, /reload-plugins picks up your edits without a restart, and claude plugin validate ./my-plugin checks the manifest, the skill and agent frontmatter, and hooks/hooks.json before anyone else sees it.

What does a Claude Code plugin cost?

The mechanism is free. As of August 2026 there is no charge to add a marketplace, install a plugin, or keep one enabled. The official and community marketplaces are public git repositories, and a plugin is a directory of text files.

What a plugin costs is tokens, and tokens are what your subscription usage or your API bill actually measures. That cost arrives in three different ways, and they behave differently.

Standing context cost. What a plugin contributes sits in your context and is re-read on every turn of the session. Before installing, the /plugin detail view shows a Context cost estimate in tokens plus a Will install section listing the commands, skills, agents, hooks, and MCP and LSP servers you are about to add. Read both. Plugins from local or custom marketplaces may not supply that data, in which case you are estimating by hand. A plugin that bundles an MCP server is usually the heaviest, because tool definitions are large, though on models that support MCP tool search those definitions are deferred until a tool is needed.

Invocation cost. Running a plugin's skill appends its instructions to the conversation, so you pay for the skill body only when it is used. An agent is different. A subagent runs its own conversation with its own system prompt and its own cache, starting with no cache hits, so a plugin whose workflow spawns agents costs considerably more than its context estimate suggests.

Cache cost. Enabling or disabling a plugin mid-session can force the next request to reprocess your whole conversation. Skills, commands, agents, hooks, LSP servers, monitors and themes never do this: what they add is appended after the existing history, so the next request pays for the new content and still reads everything before it from cache. The exception is a plugin that provides an MCP server. If its tools are deferred by tool search, the cache survives. If they load into the prompt prefix, the next request re-reads the entire conversation as uncached input. That is exactly why /reload-plugins warns and refuses in that case until you pass --force.

You can watch this rather than guess at it. Every API response reports cache_read_input_tokens and cache_creation_input_tokens, and a custom statusline showing live token usage puts both in front of you. A healthy session reads far more than it creates. If creation stays high turn after turn, something in your prefix is changing every turn. For the wider picture of what is filling the window, see how to manage the Claude Code context window and what those token counts actually mean.

One piece of housekeeping pays for itself. The Installed tab groups plugins you have not used in at least two weeks under a Not used recently header, with a Last used line in the detail view. Those plugins still cost you startup time and context on every session. Disable or uninstall them.

A plugin runs with your permissions

Anthropic's own documentation is blunt about this: plugins and marketplaces are highly trusted components that can execute arbitrary code on your machine with your user privileges. That is not a hypothetical. A plugin's hooks run shell commands on session events, including before and after tool calls. Its bin/ directory is added to the Bash tool's PATH while the plugin is enabled. Its MCP servers are processes it starts. Nothing here is sandboxed away from your user account.

On a laptop that risk is bounded by what your desktop user can reach. On a server it usually is not. The account running the agent often holds SSH keys, deploy tokens, a cloud CLI session, and access to the Docker socket, so "arbitrary code as your user" means the machine. If Claude Code runs on a VPS, read how to run Claude Code safely on a VPS before you install anything, and how to keep credentials out of reach of an agent before you install a plugin that talks to an external service.

Some guardrails do exist, and it helps to know which. A project-scope plugin comes from the repository rather than from you, so it loads only after you trust the workspace, its MCP servers still need per-server approval, its LSP servers wait for that trust, and its background monitors do not load at all. Plugin-shipped agents are not allowed to declare hooks, MCP servers, or a permission mode. Marketplace plugins are copied into the cache with symlinks that point outside the marketplace skipped, so a plugin cannot pull in arbitrary host files.

None of that replaces reading what you install. Check the Will install list, prefer plugins whose source you can open and read, keep your team's plugins in a marketplace repository you control, and run claude plugin validate on anything you write yourself.

FAQ

Do Claude Code plugins cost extra money?

No. There is no fee for the plugin system, for adding a marketplace, or for installing a plugin. The cost is token usage, billed against your plan or your API spend like any other context. A plugin adds standing context on every turn, adds more when one of its skills or agents is invoked, and can force one expensive uncached turn if it provides an MCP server whose tools load into the prompt prefix. The /plugin detail view shows a Context cost estimate before you install.

What is the difference between a plugin and a skill?

A skill is a single unit of instruction. A plugin is a package that can contain skills, agents, hooks, MCP servers, LSP servers, and monitors, with a name, a version, and a marketplace to install it from. Write a standalone skill in .claude/ when it is for you and this project. Turn it into a plugin when other people need it and it needs to be updated over time. Plugin skills are namespaced, so a skill inside a plugin is invoked as /plugin-name:skill-name rather than /skill-name.

My plugin installed but its skills do not appear. What is wrong?

Check the install summary first. If it said Run /reload-plugins to activate., the components are not loaded yet, and if the reload warns that it will re-read the conversation, rerun it as /reload-plugins --force. If it loaded but shows nothing, open /plugin and read the Errors tab. The most common structural mistake is putting skills/, agents/, or hooks/ inside .claude-plugin/, where Claude Code does not look for them. Remember that plugin skills are namespaced, so you are looking for /plugin-name:skill-name in the Custom commands tab of /help. As a last resort, rm -rf ~/.claude/plugins/cache, restart, and reinstall.

Can I install plugins without the interactive panel?

Yes. Use the shell command claude plugin install name@marketplace, which installs to user scope unless you pass --scope project or --scope local. It works in scripts, images, and non-interactive environments where the /plugin panel is unavailable. Because it runs outside a session, a session that is already open needs /reload-plugins before the plugin takes effect.

Is it safe to install a plugin from a marketplace I found on GitHub?

Treat it the way you would treat running that repository's install script as yourself, because that is close to what it is. A plugin can run shell commands through hooks, add executables to the Bash tool's PATH, and start MCP servers, all with your user's privileges. Anthropic does not control or verify third-party plugin contents. Install from sources you can read, review the Will install list before confirming, and be stricter on a server than on a laptop, since the account there usually holds keys and tokens worth stealing.