What are Claude Code plugins?

What is a plugin?

Claude Code can be extended with several building blocks - skills, agent definitions, hooks, and MCP connections. A plugin is simply a bundle that packages some or all of those into one installable unit. Instead of every teammate manually copying skill files, pasting MCP configs, and wiring up hooks one at a time, they install the whole thing in a single step.

That is the entire idea. A plugin does not add a new kind of capability - it takes the capabilities Claude Code already supports and makes them portable, versioned, and shareable. Where a lone skill in your project is a personal tool, a plugin is that same skill (and its connections and guardrails) packaged so a team, or a whole community, can install it the same way every time.

Plugins are distributed through a marketplace: a Git repository or local folder that holds one or more plugins plus a catalog file listing them. You register the marketplace once, then install plugins from it - the two halves this article walks through.

One clarification worth making up front: plugins are a Claude Code feature. Because Claude Cowork runs on the same agentic architecture, the same plugins work there too - one plugin system, two surfaces, not two separate things.

The building blocks

To understand a plugin, understand the pieces it can carry. Each is a capability Claude Code supports on its own; a plugin is a container for one or more of them.

Plugins can also ship LSP servers for code intelligence, background monitors that watch logs or files, executables added to the shell path, and default settings. The mental model stays the same: whatever Claude Code can be taught to do, a plugin can carry and hand to the next person.

Plugins vs standalone config

You do not need a plugin to use skills or hooks. Claude Code reads them straight out of a .claude/ directory in your project. The choice is about sharing, not capability.

A good rule: start standalone in .claude/ while you iterate, then convert to a plugin once the thing is worth sharing. Plugin skills are namespaced - a plugin named forecast exposes its skill as /forecast:today - which is what keeps two plugins from colliding when they both ship a skill of the same name.

Marketplaces: the catalog

A marketplace is just a Git repo (or local folder) that holds one or more plugins plus a catalog file - .claude-plugin/marketplace.json - listing them. You keep all your plugins in one repo, register that repo once, and install any plugin from it.

Anthropic runs two public marketplaces you can add the same way: claude-plugins-official (a curated set) and claude-community (third-party submissions after review). A private repo works identically for a team's internal plugins.

How the repo is structured

All of a team's plugins live in one repo. At the root sits the catalog; each plugin gets its own folder with its own manifest.

One thing that trips people up: the folder .claude-plugin/ appears in two places. At the repo root it holds marketplace.json (the catalog of all plugins). Inside each plugin folder it holds that one plugin's plugin.json manifest. Same folder name, different file, different job depending on where it sits. Note the inverse rule too: only plugin.json goes inside .claude-plugin/ - skills/, hooks/, agents/, and .mcp.json live at the plugin root, never inside it.

The root catalog lists every plugin with a name, a source path, and a description:

The name field here (weather-marketplace) is what the @marketplace-name in the install command refers to - not the repo name. That is why the install command below reads @weather-marketplace.

A worked example

Take a single plugin, forecast. Each piece maps to one of the building blocks:

• Skill (skills/today/SKILL.md): fetch the forecast for a location, summarise the conditions, and flag notable changes.
• MCP connection (.mcp.json): link to a weather-data service so the skill can pull live conditions and forecasts.
• Hooks (hooks/hooks.json): require confirmation before a severe-weather alert is sent (a PostToolUse hook), and stop after a set number of failed API calls (a PreToolUse hook).

Bundled together, that is one installable plugin. Build a severe-alerts plugin and a climate-reports plugin the same way, list all three in the catalog, and the team pulls whichever they need from the one repo.

Installing: the two-step flow

Installing is always two distinct steps, and it helps to know they do different things:

• Step 1 - register the marketplace. This installs nothing. It tells Claude Code "here is a catalog of plugins, at this location," and Claude Code reads the marketplace.json there so it knows what is available. The registration lives in Claude Code's own settings on your machine, not in the repo. Point it at the folder that contains .claude-plugin/marketplace.json - the repo root, not a subfolder.
• Step 2 - install a specific plugin. Now Claude Code copies that one plugin onto your machine and activates it.

The two verbs, plainly: marketplace add points Claude Code at the catalog (do once); install actually grabs and activates a plugin from it (per plugin).

Either way, once installed the plugin's skill, connections, and guardrails become active at once. There is no separate "turn it on" step - once installed and enabled, its capabilities are simply there.

Source vs installed copy

This is the part that trips people up. There are two separate local locations, and they look different.

(a) The source repo - the editable version, either the Git repo or your local clone of it. This is where you make changes:

(b) The installed copy - when you run /plugin install, Claude Code does not run the source folder. It copies just that one plugin into its own cache, and that copy is what actually runs:

Two consequences worth remembering:

• Never edit the cached copy - changes there get overwritten. Always edit the source repo instead.
• Everything a plugin needs must live inside the plugin folder. Because it is copied to the cache, any file it references (say a transformation script) has to be inside that plugin folder. Paths pointing elsewhere in the repo break after install.

How updates work

Because the installed copy is a snapshot in the cache, updates to a custom marketplace do not happen automatically. The flow is one direction, source to cache, and only when someone pulls them:

• Edit the files in the source repo and push the changes.
• On each machine, refresh the catalog: /plugin marketplace update weather-marketplace.
• Re-run the install (or run /reload-plugins) so the cached copy is refreshed with the new version.

So the mental model is: the source repo is where you make changes, the cache is what Claude Code runs, and updates flow source to cache only when someone pulls them. One note on versioning: if a plugin's plugin.json sets a version, users receive updates only when you bump it; if it is omitted and the plugin is distributed via Git, the commit SHA is used and every commit counts as a new version.

Management commands

The commands you reach for most, run inside Claude Code:

To go deeper - authoring skills, wiring MCP servers, writing hooks, and building the subagents a plugin can carry - start from the pieces themselves: Agent Skills, Model Context Protocol, and the breakdown of how they fit together in Functions, MCP, and Skills.