How Do Claude Code Plugins Work?

How Do Claude Code Plugins Work?

Claude Code accumulated a lot of configuration surfaces over its first couple of years. Skills, subagents, hooks, MCP servers and a CLAUDE.md file each had their own place to live and their own way of being shared.

Plugins are the answer to that sprawl. A plugin is one installable bundle that can carry all of those pieces at once, and one command puts it on a machine.

That makes them the practical way to share a workflow across a team, and the practical way to pick up somebody else's without copying four files into four directories.

They also run code you did not write. A plugin can install hooks and MCP servers, which is a meaningful amount of trust to extend to a stranger's repository.

This guide covers what a plugin contains, how installing one actually works, how marketplaces fit in, and what to look at before you say yes.

What Is the Short Answer?

A Claude Code plugin is a directory of components distributed through a marketplace, installed with /plugin install <name>@<marketplace> in a session or claude plugin install <name>@<marketplace> from your shell.

Installing it adds that plugin's skills, agents, hooks, and MCP and LSP servers to Claude Code, at a scope you choose: just you, everyone in the repository, or you in this repository only.

Anthropic's official marketplace is registered for you the first time you start an interactive terminal session, so installing from it needs no setup. Anything else needs its marketplace added first.

Before you automate your workflow, make sure your site is working for you. Get a free SEO audit and see where you stand.

What Does a Plugin Actually Contain?

The point of the format is that it is a container, not a single kind of thing. Understanding what can be in the box tells you what a plugin can do to your session.

The Components

A plugin can ship skills, which appear as slash commands namespaced under the plugin, in the form /<plugin>:<skill>. Install the official commit-commands plugin and /commit-commands:commit shows up when you type a slash.

It can ship agents, which are subagents Claude can delegate to. It can ship hooks, which run on events such as a file edit.

It can ship MCP servers and LSP servers, which connect Claude to external tools and language intelligence. And it can declare dependencies on other plugins, which get installed alongside it at the same scope.

Hooks Are the Part That Matters

Of that list, hooks are the component with teeth. A hook is enforcement rather than instruction: a hook that blocks an edit actually blocks it, where a line in CLAUDE.md is a request Claude can overlook.

That is exactly why a plugin is worth more than a shared document to a team with real conventions, and exactly why you should read what one installs before accepting it.

What It Costs You in Context

Plugins are not free. Everything a plugin always loads sits in your context on every message you send.

For plugins in Anthropic's official marketplace, the details pane shows two token estimates: Every turn, which is what the plugin adds to each message, and When invoked, which is what its skills and agents add once Claude loads them.

For an installed plugin, claude plugin details <name> prints an Always-on line with the same figure plus a per-component breakdown, so you can see which skill is the expensive one.

How Do You Install a Claude Code Plugin?

1. Run the install command in a session. Type /plugin install commit-commands@claude-plugins-official. In a session this does not install immediately — it opens the /plugin panel on that plugin's details so you can read them first.
2. Read the details pane. It lists what the plugin will install, when it was last updated, and the context cost. This is the review step, and it is the only one that protects you.
3. Choose a scope. User scope enables it in every project on the machine. Project scope enables it for everyone working in the repository. Local scope enables it for you in that repository only.
4. Read the install summary. The last line tells you whether it is usable now. Plugin is now active. means no reload. Run /reload-plugins to activate. means it needs one, which Claude Code runs for you.
5. Confirm it loaded. Type / and look for the plugin's skills under its name, or run claude plugin list in your shell to see version, scope and status.

To browse rather than install by name, run /plugin with no arguments. The panel opens on the Discover tab, which lists plugins from every marketplace you have added.

From a setup script, use the shell form instead: claude plugin install formatter@your-org --scope project. It defaults to user scope, and plugins it installs load the next time Claude Code starts.

Where Each Scope Is Recorded

Scope is not a label, it is a settings file. User scope writes to enabledPlugins in ~/.claude/settings.json.

Project scope writes to .claude/settings.json, which you commit. Local scope writes to .claude/settings.local.json, which you do not.

When the same plugin is set at more than one, local beats project and project beats user.

One trap worth knowing: committing a project-scope entry turns the plugin on for your collaborators but does not download it to their machines. Each of them still runs the install once with --scope project.

Reporting on your tooling is easier than reporting on your traffic. Request your free SEO audit and get a clear picture.

How Do Marketplaces Work?

A marketplace is a catalog that tells Claude Code which plugins exist and where to fetch each one. You add it once, then install from it by name.

Adding One

Inside a session, /plugin marketplace add takes a GitHub repository as owner/repo, a full git clone URL on any host, a local directory or file path, or the https:// URL of a hosted marketplace.json. The same sources work with claude plugin marketplace add from your shell.

Append #ref to pin a branch or tag, as in your-org/plugins#v1.2.0. Start a local path with ./ or ../, because a bare name/name is read as a GitHub repository.

On recent versions you can skip the separate step and name the source inline: /plugin install deploy-helper --marketplace your-org/plugins. That one needs Claude Code v2.1.275 or later.

Removing a marketplace is not a passive act. It uninstalls every plugin you installed from it and strips their enabledPlugins entries from your settings.

Hosting Your Own

A marketplace is a directory containing a .claude-plugin/marketplace.json file. That file requires a name, an owner and a plugins array, and each entry in the array needs a name and a source.

A source can be a relative path inside the marketplace, a GitHub repository of its own, a subdirectory of a monorepo, a git URL, a zip archive over HTTPS, an npm package, or a command that produces the directory on the installing machine.

Two rules account for most failed installs from a new marketplace. Relative paths are written from the marketplace root, the directory containing .claude-plugin/, and a path containing .. is rejected outright.

And the entry name in marketplace.json has to match the name in the plugin's own plugin.json. When they differ, installing by the manifest name fails with a not-found error. Run claude plugin validate after every edit.

When Should You Reach for a Plugin?

The clearest case is a team with conventions it actually enforces. A plugin that ships your deployment checklist as a skill and your edit guardrails as hooks is reusable across every repository, which is where it compounds.

The second case is a capability you want in one command rather than four. Installing a plugin that brings an MCP server and the skills that drive it is considerably less work than wiring both yourself.

The third is organisational distribution. An administrator can pre-install and require a marketplace and its plugins through managed settings, which appear at Managed scope and cannot be disabled locally.

Limitations and Risks Worth Knowing About

Trust is the real limitation. A plugin can run hooks and MCP servers on your machine, so an unfamiliar marketplace deserves the same scrutiny as any other dependency you would add to a project.

Context cost is the quiet one. Several always-on plugins add up, and the Not used recently header on the Installed tab exists precisely because people forget what they installed.

Enabling or disabling a plugin can invalidate your prompt cache. When it would, Claude Code warns and leaves the change pending rather than applying it; /reload-plugins --force applies it anyway at the cost of one uncached request.

Auto-update is inconsistent by design. It is on by default for Anthropic's official marketplaces and for marketplaces added from claude.ai, and off by default for community, third-party and local ones. Assume a third-party plugin is stale unless you updated it.

Plugins do not follow you everywhere. A cloud session has no plugin browser and does not load the plugins on your own machine or the ones your repository's settings turn on. Non-interactive runs such as claude -p load installed plugins but cannot manage them.

And the two directions of sync are not symmetric. Plugins from your claude.ai account arrive automatically and show as <name>@synced, but plugins you install locally are never pushed back up to that account.

Not sure what your site looks like to search engines? Start with a free audit and find out.

Plugins vs Skills, MCP Servers and CLAUDE.md

These are not competing options so much as different distribution units for the same material.

A loose skill file is right for something only you use, in one repository, that you will rewrite next week. There is no reason to wrap it in a plugin.

A raw MCP server configuration is right when you want the connection and none of the surrounding workflow. Plenty of MCP servers are useful with no skills attached at all.

CLAUDE.md remains right for project context: conventions, architecture notes, the things Claude should know rather than the things it should run.

A plugin is right the moment more than one person needs the same bundle, or the moment you want a hook to enforce something rather than suggest it. If you are testing your own before publishing, start Claude Code with --plugin-dir and skip installing altogether.

Ready to see what your search presence is really doing? Claim your free SEO audit today.

Final Thoughts

Claude Code plugins solve a packaging problem rather than a capability one. Everything a plugin contains could be configured by hand; the plugin makes it one install, one scope decision and one update path.

The habits that matter are small. Read the details pane before you install, pick the narrowest scope that does the job, check claude plugin details when a session starts feeling heavy, and treat an unfamiliar marketplace as code rather than content.

Do that and the format mostly disappears into the background, which is what good packaging is supposed to do.

For a wider view of how Claude Code compares with the other assistant in this space, see our breakdown of Claude Code vs GitHub Copilot.