Claude Code plugins: what a plugin is, and how to install one

What a plugin holds

The directory is usually flat and readable. A manifest at .claude-plugin/plugin.json gives the plugin its name and can add a version and a description, and the rest of the folder holds components. Anthropic's own diagram walks one plugin holding a skill, an agent, a hook file and an MCP server, and shows what each piece becomes once the plugin loads.

Only the manifest's name is required, and a plugin without a manifest still loads. None of the components is required either, so a plugin can legitimately be three skills and nothing else.

One rule inside a plugin catches people out. Anthropic writes that Claude Code does not load a CLAUDE.md at the plugin root, and its own validator warns about one. Guidance that should reach every session in a plugin is written as a skill, and a rule that has to hold every time is written as a hook.

Plugins, skills, subagents and MCP servers

Every one of those components works without a plugin. A skill you save in ~/.claude/skills/ is available in every project on the machine, a subagent is a file in an agents directory, and an MCP server is a line in a configuration file. A plugin is the packaging when you want several of them to travel together, arrive with one command, and update from one place.

The naming is the part that reads as a contradiction until you see it once. A skill inside a plugin keeps a namespace: skills/review/SKILL.md in a plugin called my-plugin runs as /my-plugin:review. Your own skill named review sits at /review, and because the names are separate, both load. That is why a look at your slash menu can show what feels like two of the same thing.

A plugin skill also escapes the switch that turns other skills off. Anthropic documents that skillOverrides does not apply to plugin skills, so that setting cannot turn one off. A permission rule that names the skill can, and so can disabling or uninstalling the plugin.

Two neighbours are worth naming, because both get called a plugin. A skill folder with a .claude-plugin/plugin.json added to it loads as a plugin named <name>@skills-dir, so the boundary between "a skill" and "a plugin" can be one file. And an MCP server you add by hand is not a plugin even when a plugin also ships servers. Our guide to Claude Code subagents covers the agent half, and the MCP server guide covers adding a server by hand.

What a marketplace is

A marketplace is a repository or directory with a .claude-plugin/marketplace.json file that lists plugins and where to fetch each one. Anthropic describes it as a catalog rather than a hosted store, and the distinction is worth holding: nothing is served to you from a shop, the file points at the place each plugin actually lives.

Anthropic reserves some marketplace names for its own, and a marketplace's name places it in one of three tiers. Official marketplaces carry names such as claude-plugins-official, community marketplaces carry names such as claude-community, and Claude Code accepts those names only for marketplaces sourced from github.com/anthropics/ repositories. Everything else, including a marketplace your own organization publishes, is third-party. claude-code-plugins is Anthropic's demo marketplace, which is easy to mistake for the official one by its name.

Anthropic's security page is blunt about what a tier buys you. The name tells you who publishes the catalog, not what each plugin in it does, so the tier is not a review of the code you are about to run.

Claude Code adds the official marketplace the first time you start an interactive terminal session, unless a managed policy blocks it. It does not add the community or demo marketplaces on its own, which is why a plugin whose name ends in @claude-community needs the marketplace added first.

To add one, run /plugin marketplace add with a GitHub owner/repo, a full clone URL, a local path, or the https:// URL of a hosted marketplace.json. Add #ref to the end of a repository source to pin a branch or a tag. A bare name/name is read as a GitHub repository, so a relative path has to start with ./ or ../, and a URL without its scheme is rejected rather than guessed at.

If you want a first install to look at rather than a list to judge, Anthropic's own worked example is commit-commands from the official marketplace, which adds commands for committing, pushing and opening a pull request. It is one plugin, it is in the marketplace Claude Code already knows about, and its install shows you the details pane and the summary line this page describes before you point any of it at your own repository.

Removing a marketplace is heavier than it sounds. Claude Code uninstalls every plugin you installed from it and takes their entries out of your settings, and the panel names those plugins before it asks you to confirm.

Install a plugin, step by step

The commands below are the terminal ones. Anthropic also documents the same install in the desktop app, in VS Code, and from your shell, and the scope choice is the same in each.

1. Add the marketplace Run /plugin marketplace add with the repository, git URL or local path the plugin is published from. Skip this when the plugin is in Anthropic's official marketplace, which Claude Code adds the first time you start a terminal session.
2. Open the plugin and read it Run /plugin install with the plugin and its marketplace. The panel opens on the plugin's details, which list the commands, agents, skills, hooks and servers it will add, and for Anthropic's official marketplace an estimate of what it costs in context.
3. Pick a scope Choose user scope for every project on this machine, project scope for everyone who works in this repository, or local scope for you in this repository only.
4. Read the last line of the summary Plugin is now active means it is running. Run /reload-plugins to apply means the install landed but the session has not loaded it. The plugin couldn't be loaded has the reason in the Errors tab.
5. Confirm the skill is there Type / and look for the plugin's skills under its own name, in the form /plugin:skill. The Installed tab in /plugin and claude plugin list in your shell show the same plugin with its scope and status.

The three scopes, and which file records each

The scope decides who gets the plugin, and it is the answer to most of the "my teammate has it and I do not" questions below.

When the same plugin is set at more than one scope, local overrides project and project overrides user, key by key. A plugin whose author set defaultEnabled: false in its manifest or its marketplace entry installs and stays off until you enable it with claude plugin enable.

Project scope has a catch worth knowing before you rely on it. Committing the entry turns the plugin on for your collaborators, and it does not download the plugin to their machines. Each of them runs claude plugin install with the project scope once, and until they do, the plugin is listed in the Errors tab as enabled in project settings but not installed here.

One command for a marketplace you have not added

/plugin install, or claude plugin install from your shell, takes --marketplace with the source, so the add and the install are one line. It needs Claude Code v2.1.275 or later in a session, and v2.1.292 or later from your shell. In a session the source cannot contain spaces, and Claude Code asks you to confirm the source it resolved before adding it; from your shell it adds the marketplace without asking.

Three layers, and why a plugin can be installed and still be missing

An enabledPlugins entry becomes a plugin you can use in three stages, and a plugin that seems to have vanished has usually reached the second and not the third. Anthropic's own description of the stages is the clearest way to hold this.

• Declared in settings. enabledPlugins says which plugins should be on, and extraKnownMarketplaces says which marketplaces should exist.
• Fetched to disk. ~/.claude/plugins/ holds known_marketplaces.json, installed_plugins.json with each install's scope, path and version, and a cache/ folder with the plugin's own files.
• Loaded in the session. The running session loads plugins at startup or at the last /reload-plugins. Nothing you change on disk or in settings reaches this layer until one of those happens.

That last layer is why the answer to so many plugin problems is /reload-plugins. Anthropic's own update command ends with the instruction to restart, and a background update prompts you to reload, both for the same reason.

Every plugin has an id in the form <name>@<origin>, and the part after the @ tells you where Claude Code found it. A marketplace install ends in the marketplace's name. @inline means it was loaded for one session by a flag or an environment variable, @skills-dir means it grew out of a skill folder with a manifest, and @synced means it came from your claude.ai account.

A plugin installed, and its skills are not there

Start with three checks in the panel, in this order, before you change anything. Anthropic's troubleshooting page walks the same three.

• Installed and enabled. Open /plugin and the Installed tab, and confirm the plugin is listed and switched on. claude plugin list prints the same list with each plugin's version, scope and status.
• The Errors tab. Every entry there pairs a message with a line telling you what to do about it.
• A reload. If you installed the plugin during this session, run /reload-plugins. It prints Reloaded: with counts of plugins, skills, agents, hooks and servers, and adds the number of errors when something failed.

One version note is worth knowing, because it explains a whole class of old reports. Before Claude Code v2.1.246, the skill count in that reload summary included only a plugin's commands/ entries, so a reload could load a plugin's SKILL.md skills correctly and still print 0 skills. If a plugin looks fine and the count reads zero on an old build, update before you debug.

Then match the message you actually have.

A plugin that is installed, enabled and error-free and still shows no skills usually has none to show. Open its details pane in /plugin, which lists what the plugin contains, and check that the list is not empty.

Two smaller things sit behind less common reports. A plugin with dependencies installs them with it, and an uninstall leaves the ones it pulled in until you run claude plugin prune. And if a plugin you are building needs to be tried before it is published, --plugin-dir loads it from its folder for one session, with no marketplace in the way.

What a plugin costs before you use it

An enabled plugin is part of every session, not only the sessions where you use it. For each skill, agent and command that Claude can invoke on its own, the name and its description sit in Claude's context on every turn, so Claude knows the capability exists. The full instructions load only when the thing is used.

Anthropic gives you two places to read that number. Before you install, open the plugin from the Marketplaces tab in /plugin: a plugin in the official marketplace shows a context cost estimate with an every-turn figure and a when-invoked figure. After you install, claude plugin details prints an always-on line and per-component rows showing which skill or agent contributes most.

The Installed tab also has a Not used recently group, and each plugin's details carry a last-used line. Those two are the shortest path to the plugins that are paying context rent and returning nothing, and the switch is beside each one. Our guide to the context window covers what the rest of that budget is spent on.

Updates are automatic for some marketplaces and not others, which decides how much of this you have to think about. Anthropic turns auto-update on by default for the official marketplace names, apart from knowledge-work-plugins and first-party-plugins, and for marketplaces added from claude.ai. It is off by default for every other marketplace, including the community one, third-party ones, and local development ones.

There is no command that updates every plugin at once. One plugin updates with claude plugin update, and a whole marketplace's plugins update from its entry on the Marketplaces tab. The running session keeps the versions it already loaded, so an update lands either at the next reload or at the next session.

What a plugin can run as you

Anthropic states it without softening: a plugin you install can execute arbitrary code on your machine with your user privileges. What it can do is a list rather than a warning, and the list is the useful part. Hooks run as shell commands at lifecycle points. Monitors run as background shell commands that Claude Code starts on its own when the session starts, when you reload plugins, or the first time a named skill runs. A mod runs JavaScript inside Claude Code. MCP and LSP servers run as processes Claude Code starts. A plugin's bin/ directory is added to the Bash tool's path. Skills, commands and agents arrive as instructions that shape what Claude does with the tools it already has.

The boundary that matters most is between Claude's tool calls and a plugin's own code. Anthropic's permission rules and sandbox cover the calls Claude makes, so a call to a plugin's MCP tool and a Bash command running one of its executables both go through your rules. Hooks, monitors, servers and a mod's own processes run outside the sandbox, with your full permissions.

Installing a plugin also enables it, unless its manifest or its marketplace entry sets defaultEnabled: false. And with auto-update on, the files you reviewed can change on disk afterwards. Anthropic's advice follows from both: read the details pane before you install, and review again if a plugin you trusted starts behaving differently. Its page on plugin security covers what to look at, and how to remove a plugin you no longer trust.

For a team, the controls move one level up. Managed settings can allowlist or block marketplaces, force-install plugins, and turn off session-only loading, and a plugin installed that way shows at managed scope in the Installed tab where you cannot enable, disable or uninstall it yourself.

Where Omniscio fits

Omniscio is the desktop app we make for running Claude Code sessions. It has a plugin marketplace of its own, and the first thing worth saying about it is that it is a different thing from the one this page is about. An Omniscio plugin draws inside the app: it can add a sidebar view, menu entries and a webview UI, and it calls into Omniscio over a sandboxed bridge. A Claude Code plugin is a directory of skills, agents, hooks and MCP servers that Claude Code loads. The two live in separate places and neither installs the other.

What Omniscio does show is the part the terminal hides. Its Skills view lists skills that arrived with a Claude Code plugin alongside your own, and for a plugin skill it shows where the skill came from: the plugin's name, its version, the author, the marketplace it was distributed through, and links to that marketplace's repository and the plugin's own. That is the answer to the question a slash menu cannot answer, which is which plugin put this command here. Its Skill Overhead scan watches the same set and raises a card for skills that have gone unused, with an estimate of what each one costs in every chat.

Plugin skills are read-only in that view, because the plugin's publisher wrote them. Removing one deletes it from the plugin cache and the route back is reinstalling the plugin.

One interaction is worth knowing if you also add MCP servers by hand. An Omniscio session starts Claude Code so that it loads only the servers Omniscio set up for it, and that bounding is on by default as Stop sessions from loading unused background tools, in Settings → Performance, under Show advanced. So a server you add outside Omniscio does not reach the session until you add it in the MCP Servers view and switch it on, or you turn that setting off. The MCP server guide covers the same interaction from the other side.

The features page lists what else the app does, and the download page has the installers for Windows, macOS and Linux. If you are about to run several sessions with the same plugin set, our guide to running multiple Claude Code sessions covers the setup side of that.