SSD Nodes Learn Hosting plans →
Guides Matt ConnorBy Matt Connor

Claude Code plugins: what they are and cost

What a Claude Code plugin is, where it lives, how to install one, and what it really costs: nothing for the mechanism, tokens for what it puts in context.

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. The main components are skills, agents, hooks, MCP servers, LSP servers, and background monitors, and a plugin can also carry commands, output styles, themes, workflows, and a bin/ directory of executables. Installing a plugin adds all of its parts at once, under one name, and disabling it removes them the same way.

A plugin mostly gives the agent no ability it did not already have. Skills, agents, hooks, and MCP servers are all things you can write by hand in a .claude/ directory. The exceptions are language servers for code intelligence and mods, which Claude Code only loads from a plugin. For everything else 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 directory of skills, agents, hooks, MCP servers, or other components that Claude Code installs and loads as one unit. Its optional manifest names it and can add a version, a description, and other metadata. Distribution is not part of the plugin: a marketplace is a separate catalog that lists plugins and where to fetch each one.

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

Most marketplace plugins are copied into a local cache at ~/.claude/plugins/cache, with a separate directory for each installed version. Relative-path plugins in a marketplace you added from a local path load in place, and command-source plugins in link mode load through links to their source directory. When you update or uninstall a copied plugin, 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. Cleanup runs only while at least one plugin installation remains recorded; after you uninstall your last plugin, orphaned directories stay until you install another.

Because a copied plugin's 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/.

For a copied plugin, only the plugin's own directory is copied into the cache, apart from symlink targets elsewhere in the same marketplace, which are copied into place. A script that reads a path outside the plugin root, such as ../shared-utils, works while you develop with a local path and breaks when the plugin is copied into the cache, because those files were never copied. A component path declared that way in plugin.json fails sooner: Claude Code rejects any component path that escapes the plugin root, during development too, with a path escapes plugin directory error.

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, unless managed policy or CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL blocks it. Others you add yourself.

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

The marketplace 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. The old claude-code-plugins marketplace in anthropics/claude-code is deprecated; use claude-plugins-official for new installs. Existing plugins from that old marketplace update from the official repository, so you do not need to reinstall commit-commands just to change marketplaces.

After the install, read the summary line. Plugin is now active. means the components are loaded in this session. Run /reload-plugins to apply. means they were not activated during the install; the panel closes and Claude Code runs that reload for you. If the reload warns that it would re-read the conversation, it leaves the plugin pending, and you rerun it as /reload-plugins --force. Then confirm the plugin is really there: /plugin shows it under the Installed tab, typing / lists its skills as /plugin-name:skill-name, 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, which turns it on for everyone who clones the repository. It does not download it for them: each collaborator still installs it once on their own machine, for example with claude plugin install name@marketplace --scope project, unless its marketplace entry is a relative path or a seed directory already holds 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. On a machine where nobody has opened an interactive session yet, the official marketplace is not registered, so add it first.

claude plugin marketplace add anthropics/claude-plugins-official
claude plugin install commit-commands@claude-plugins-official --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, or run claude plugin marketplace add your-org/claude-plugins --scope project once and commit the file it writes. Claude Code registers the marketplace for each member 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. A marketplace is not required to share one either: you can send someone the folder or a .zip of it to load with --plugin-dir, though they get no updates until you send a new copy.

What does a Claude Code plugin cost?

The mechanism is free. As of November 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. Which of those two a plugin eats into depends on how you pay for the tool in the first place, and what Claude Code costs on each plan sets out the subscription tiers next to per-token API pricing. That cost arrives in three different ways, and they behave differently.

Standing context cost. Every enabled plugin puts the names and descriptions of its skills, agents, and commands that Claude can invoke on its own into your context, and that part is re-read on every turn of the session whether or not anything runs. Not every component costs tokens: a hook is run by the harness and adds nothing to the model's context. Before installing, the /plugin detail view shows a Will install section listing the commands, skills, agents, hooks, and MCP and LSP servers you are about to add. For a plugin in Anthropic's official marketplace it also shows a Context cost section with Every turn and When invoked estimates, as long as you open the plugin by its marketplace name or from the Marketplaces tab rather than from the Discover list. Read both. A plugin from your own or a third-party marketplace has no Context cost section, but you do not have to estimate by hand: claude plugin details name in your shell prints an Always-on token figure and a per-component breakdown for any loaded plugin, including one you pass with --plugin-dir, so you can clone a repository and run claude --plugin-dir ./that-plugin plugin details that-plugin before you install anything. That figure leaves out MCP servers. 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. Run /context in a session with the plugin enabled and read the MCP tools line to see what they add.

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. The body is the cheap part, though, and what the skill tells the agent to do need not be: the unlazy skill's Depth Tree method spends almost all of its tokens on the extra passes it forces before the agent is allowed to call a task done, not on the file you installed. 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, 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 exceptions are a plugin that provides an MCP server and a code intelligence plugin, whose language server gives Claude the LSP tool. For MCP it depends on tool search: if the tools are deferred, the cache survives, and 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 when a change to MCP tools or the LSP tool would break the cache, 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 marketplace-installed plugins you have not used in at least 14 days and 10 sessions under a Not used recently header, with a Last used line in the detail view. The header excludes managed and seed-directory plugins, and plugins with a theme, output style, monitor, or workflow; an LSP server counts as used when it delivers diagnostics or answers a code navigation request. When strictKnownMarketplaces is configured, neither the header nor the Last used: line appears. Those plugins still cost you startup time and context on every session. Disable or uninstall them. The cheaper habit is to be selective before you install: which of Matt Pocock's skills are worth installing works through a 27-skill collection and separates the few a solo developer needs from the ones that only pay off on a team.

A plugin runs with your permissions

Anthropic's own documentation is blunt about this: a plugin you install 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 stdio MCP servers are processes it starts, and a mod runs JavaScript inside Claude Code itself. Hooks, monitors, server processes, and mod processes run outside Claude Code's sandbox; its permission rules still apply to the tool calls Claude makes.

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. Other harnesses run into the same wall on the same rented box, which is why the DeepSeek Harness plugins worth installing are mostly spend caps, tool permission rules, and injection scanning rather than new capabilities.

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, and its background monitors do not load at all. Plugin-shipped agents are not allowed to declare hooks, MCP servers, or a permission mode. When marketplace plugins are copied into the cache, symlinks that point outside the marketplace are skipped, so a copied plugin cannot pull in arbitrary host files through those links.

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. What you reviewed can also change later: auto-update is on by default for Anthropic's official marketplaces except knowledge-work-plugins and first-party-plugins, and off for third-party ones added by source; where it is on, Claude Code updates the plugin's files in the background.

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. For a plugin in Anthropic's official marketplace, the /plugin detail view shows a Context cost estimate before you install; for any other plugin, claude plugin details name prints its always-on token cost once it is installed or loaded with --plugin-dir.

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, usually a version, and usually a marketplace to install it from, though it can also be shared as a folder or a .zip that people load with --plugin-dir. Write a standalone skill in .claude/ when it is for you and this project. A single-purpose skill such as Ponytail, which pushes the agent toward the smallest change that works is the clearest case of that: one file with one rule in it, right up until the day your team wants it too. 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 apply., Claude Code runs that reload when the panel closes, 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 when you type /. If it is someone else's plugin and it loads with no error, open its details pane on the Installed tab: a plugin that lists no skills there has none to offer. If the Errors tab says the plugin is not cached, its install directory is missing, so reinstall it from your shell with claude plugin install name@marketplace and run /reload-plugins.

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. In a session without an interactive terminal, changes to plugin MCP servers take effect in the next session.

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.

Was this article useful?