Claude Code plugins are packages: a directory that can hold skills, subagents, hooks and MCP servers, installed together from a catalog called a marketplace. A skill is just one folder with a SKILL.md. This guide explains what a plugin bundles, how marketplaces are added and plugins installed, how plugin skills are namespaced, how to review one before you trust it, and when a single skill is the better choice.
Everything here is drawn from Anthropic's Claude Code documentation on plugins, marketplaces and skills, plus the directory's install data. The editorial team has not published a marketplace for this guide, so the walkthrough follows the documented commands rather than a test of our own.
What Claude Code plugins bundle
According to the plugin documentation, a plugin is "a directory of skills, agents, hooks, MCP servers, or other components" that Claude Code installs and loads as one unit. The optional manifest sits at .claude-plugin/plugin.json and gives the plugin its name, with fields for version, description and other metadata. The components are:
- Skills.
SKILL.mdinstructions Claude loads when relevant, which you can also run as a command. - Agents. Subagent definitions Claude can delegate to.
- Hooks. Commands Claude Code runs at lifecycle points, such as after every edit.
- MCP servers. Tool servers Claude Code connects to while the plugin is enabled.
- Hooks modules. JavaScript hooks that can also draw panes and add commands, which the documentation calls mods.
In the documentation's example, a plugin named my-plugin has skills/review/SKILL.md, agents/reviewer.md, hooks/hooks.json and .mcp.json alongside its manifest. The skill then runs as /my-plugin:review.
Plugin or single skill: which should you use?
Skills, subagents, hooks and MCP servers all work without a plugin. A skill saved in ~/.claude/skills/ is available in every project on your machine. The documentation's guidance is to use a plugin when you want several of these pieces packaged as one unit, when you want to install someone else's setup with one command, or when you want to give your own setup to teammates with versioned releases.
| Single skill | Plugin | |
|---|---|---|
| What it is | One folder with SKILL.md | A directory of skills, agents, hooks, MCP servers |
| Where it lives | ~/.claude/skills/ or .claude/skills/ | Installed under ~/.claude/plugins/ |
| Command name | /skill-name | /plugin-name:skill-name |
| Updates | You copy a new version | Pulled from the marketplace |
| Runs code at install or session start | Only if its scripts are invoked | Can, through hooks and MCP servers |
| Best for | One focused behavior | A shared, versioned toolkit |
The same SKILL.md format is used in both. The post on what Claude skills are covers the file itself, and how to create a Claude skill shows how to write one.
How marketplaces work
A marketplace is a repository or directory with a .claude-plugin/marketplace.json file that lists plugins and where to fetch each one. The documentation is explicit that it is a catalog, not a hosted store. The file requires a name, an owner and a plugins array, and each plugin entry needs a name and a source.
Sources can be a relative path inside the marketplace, a github repository, a git-subdir for a plugin that lives inside a larger repository, or a url, archive, npm or command source. You add a marketplace once, then install by name in the form plugin@marketplace.
Anthropic runs several marketplaces. Claude Code adds the official one, named claude-plugins-official, the first time you start an interactive terminal session, unless a managed policy blocks it. Community and demo marketplaces are not added automatically. Anthropic's website at claude.com/marketplace is a separate thing and is not a marketplace you add with /plugin marketplace add.
Claude Code accepts official and community marketplace names only for marketplaces sourced from github.com/anthropics/ repositories, so a third-party catalog cannot pose as an Anthropic one. Any marketplace published by a coworker or your organization counts as third-party.
Add a marketplace and install a plugin
The documented flow has two steps. Add the marketplace, then install a plugin from it. Inside a Claude Code session:
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
The anthropics/skills repository's README documents exactly those commands. Its marketplace is named anthropic-agent-skills and its marketplace.json lists plugins such as document-skills, example-skills and claude-api.
What you can type after /plugin marketplace add:
| Source | Example |
|---|---|
| GitHub repository | owner/repo, optionally with #ref to pin a branch or tag |
| Any git host | The full clone URL, optionally with #ref |
| Local directory or file | ./my-marketplace (start relative paths with ./) |
| Hosted file | The https:// address of a marketplace.json |
In a session, /plugin install name@marketplace does not install immediately. It opens the /plugin panel on the plugin's details so you can review it and pick a scope. You can also run /plugin with no name to browse the Discover tab. From a shell, claude plugin marketplace add and claude plugin install take the same arguments, which suits setup scripts.
Other commands from the documentation:
claude plugin listshows installed plugins with version, scope and status.claude plugin disable name@marketplaceandclaude plugin enableswitch a plugin off or on.claude plugin uninstall name@marketplaceremoves it, andclaude plugin marketplace remove nameremoves a marketplace along with the plugins installed from it./reload-pluginsapplies changes inside a running session.claude --plugin-dir <folder>loads a plugin from a folder for one session, with no marketplace needed. This is the route for developing your own.
Scopes, namespacing and updates
When you install, you choose where the plugin is enabled:
- User scope enables it for you in every project on that machine and records it in
~/.claude/settings.json. - Project scope enables it for everyone who works in the repository through the committed
.claude/settings.json. Collaborators still install it on their own machines. - Local scope enables it for you in that repository only.
Plugin skills are namespaced with the plugin name. A skill folder review inside my-plugin becomes /my-plugin:review. The skills documentation lists plugin skills in the same table as personal and project skills, and notes that when names collide, enterprise beats personal and personal beats project, while plugin skills carry their own namespace.
Updates depend on the marketplace. Auto-update is on by default for the official marketplaces, with two exceptions, and off by default for every other marketplace, including community, third-party and local ones. You can toggle it per marketplace on the Marketplaces tab of /plugin. Update one plugin from its details or with claude plugin update name@marketplace.
What to review before you install a plugin
Anthropic's security page opens with the point that matters most: a plugin can execute arbitrary code on your machine with your user privileges. It lists what an installed plugin can do:
- Hooks run as shell commands at lifecycle events, outside the sandbox.
- MCP and LSP servers start as processes Claude Code launches.
- A
bin/directory is added to thePATHof the shell Claude uses. - Skills, commands and agents enter context as instructions that steer what Claude does with its existing tools.
- With auto-update on, the files you reviewed can change later.
The documentation's review steps are practical. Check the marketplace's source with claude plugin marketplace list. Open the plugin's details pane and read the Will install section. Then read the files that section only summarizes: hooks/hooks.json, .mcp.json and everything in bin/. After installing, claude plugin details <name> prints the component inventory and an always-on token figure.
Cost is a second reason to be selective. An enabled plugin is part of every session. For each skill, agent or command Claude can invoke on its own, the name and description sit in context every turn, which uses tokens even when nothing from the plugin runs. Plugins in the official marketplace show a context cost estimate in the details pane.
Directory skills that come with a marketplace
Several skill collections in this directory ship a marketplace manifest, so you can add the whole repository as a plugin source:
| Repository | Marketplace command or plugin | Notes |
|---|---|---|
anthropics/skills | /plugin marketplace add anthropics/skills | README states most skills are Apache-2.0, with the document skills source-available |
obra/superpowers | /plugin install superpowers@claude-plugins-official or the superpowers-marketplace | MIT per the README; see the Superpowers guide |
nextlevelbuilder/ui-ux-pro-max-skill | /plugin marketplace add nextlevelbuilder/ui-ux-pro-max-skill | MIT per the README; see the ui-ux-pro-max guide |
affaan-m/ECC | /plugin install ecc@ecc after adding the repository | MIT per the README; see the ECC guide |
The directory's own install data for Claude Code lists the plugin marketplace route alongside the skills CLI, GitHub CLI and manual copy, and notes that installing a plugin loads every skill it bundles. To install only one skill from a large repository, use one of the other routes. The hooks and plugins topic collects skills that help you build plugins. Two to start with are mcp-integration, which explains how to bundle MCP servers in a plugin, and developing-claude-code-plugins, whose repository the directory shows as last updated in December 2025 and for which it records no licence.
A skill folder can also be turned into a plugin by adding .claude-plugin/plugin.json to it, according to the skills documentation, which lets a skill bundle agents and hooks with it.
Frequently asked questions
What is a Claude Code plugin?
A plugin is a directory of components that Claude Code installs and loads as one unit. It can hold skills, subagent definitions, hooks, MCP servers and other pieces, described by a manifest at .claude-plugin/plugin.json. Most plugins are distributed through a marketplace.
What is the difference between a plugin and a skill?
A skill is a single folder with a SKILL.md file. A plugin is a package that can contain several skills plus agents, hooks and MCP servers, with versioning and updates from a marketplace. Skills work on their own without any plugin, so use a plugin when you want the whole bundle or need to share one.
How do I add a plugin marketplace?
Run /plugin marketplace add followed by a GitHub owner/repo, a git URL, a local path or the https address of a marketplace.json file. From a shell the equivalent is claude plugin marketplace add. After that, install a plugin with /plugin install name@marketplace.
Are plugins from a marketplace safe?
Not automatically. Anthropic's documentation says a plugin can run code on your machine with your user privileges, through hooks, MCP servers and files in its bin folder, and that the marketplace name tells you who publishes the catalog rather than what each plugin does. Read the details pane and the plugin's source before installing.
How are plugin skills named?
Plugin skills are namespaced with the plugin name, so a skill called review in a plugin called my-plugin runs as /my-plugin:review. The namespace stops plugin skills from colliding with your own skills or with skills from other plugins.