# Plugins package what already works

A plugin is not a new capability. It bundles skills, subagents, hooks and MCP servers into one installable, versioned unit, and an enabled plugin costs context every turn whether you use it or not.

## One unit instead of four

By now you have met four ways to extend Claude Code: skills, hooks, subagents and MCP servers. Each works on its own, in plain files, with no plugin involved.

A **plugin** adds nothing new to that list. It bundles those pieces, plus optionally a hooks module the docs call a "mod", into one installable unit. A file at `.claude-plugin/plugin.json` describes it.

So the honest question is not "should I use plugins". It is "do I have a set of things that belongs together and that someone else needs".

A plugin is for sharing or versioning a set. If you only need one skill in one project, a file in `.claude/skills/` is simpler and has nothing to update.

## What goes inside

The pieces keep their usual shape. A plugin can carry:

- skills, which are namespaced when installed, so a skill called `review` in a plugin called `acme` becomes `/acme:review`
- subagents
- hooks, in `hooks/hooks.json`
- MCP servers

The namespace is useful. Two teams can both ship a `review` skill and neither overwrites the other.

## Installing and trying

Type `/plugin` to open the manager. It has three tabs: Discover, Marketplaces and Installed. A **marketplace** is a catalog that lists plugins, so you add the catalog first and then pick from it.

For a plugin you are still writing, you do not need a marketplace at all. Start Claude Code with `--plugin-dir <dir or zip>` to load it from a folder, or `--plugin-url <zip url>` for a zip at a link. After editing, `/reload-plugins` picks up the changes. `claude plugin disable` switches one off.

```terminal
$ claude --plugin-dir ./acme-tools
* Loads the plugin from the folder
> /acme:review
* Runs the plugin's review skill
# The folder is the plugin. No catalog needed while you build it.
```

**Question:** A plugin named acme contains a skill named review. How do you call it?

- /review
- /acme:review
- /plugin review
- /acme review

**Answer:** /acme:review. Plugin skills are namespaced as /plugin-name:skill-name, which keeps them from clashing with other skills.


## The cost that is easy to miss

Installing a plugin feels free, and it is not.

An enabled plugin puts the names and descriptions of its invocable components into context on every turn. Its MCP servers and hooks run in every session, not only when you use the plugin. A plugin you installed for one afternoon keeps paying all of that until you disable it.

Two things help you see this. Plugins from Anthropic's official marketplace show a context cost estimate before you install them. And the Installed tab groups plugins you have not touched under "Not used recently", which is your cleanup list.

> **What a plugin's subagents cannot do**
Subagents shipped in a plugin ignore their `hooks`, `mcpServers` and `permissionMode` fields, for security. If a plugin subagent seems to be missing a hook you wrote, this is why. Put that behaviour in the plugin's own hooks instead.


## Sharing with a team

The path is: build and test the pieces as plain files, bundle them with a `plugin.json`, and publish them through a marketplace so others can install and update them from one place. The version lives with the plugin, which solves the problem that copied folders drift.

Before you share, test it. `claude plugin eval` runs test suites for plugins. In automated runs, load errors for plugins and their dependencies appear in the `plugin_errors` field of the `system/init` event, which makes a good gate in CI.

> **Audit what you carry**
Open `/plugin`, go to Installed, and read the "Not used recently" group. Disable what you do not miss. Then run a normal task and see whether anything was missing.


**Question:** Which statement about an enabled plugin is true?

- It costs nothing until you call it
- Its MCP servers and hooks run in every session
- It only loads when a skill matches
- It cannot be disabled once installed

**Answer:** Its MCP servers and hooks run in every session. An enabled plugin adds context every turn and runs its MCP servers and hooks in every session, used or not. claude plugin disable turns it off.