A plugin installs skills, subagents, hooks, and MCP servers as one bundle. You pick one from a marketplace with /plugin and choose its scope when you install it. This guide covers the install steps and cautions, based on the official docs.
From actually using it
When I reworked this site, I worked in Claude Code with the superpowers, frontend-design, and playwright plugins installed. At session start, superpowers used a SessionStart hook to put its skill-usage rules into the conversation automatically, so the brainstorming skill ran on the very first request. That was when it became clear that one plugin brings both skills and hooks.
What a plugin does
A plugin is a unit that bundles components such as skills, agents, hooks, and MCP servers into one directory so they install together. Its name and version go in .claude-plugin/plugin.json.
Skills, subagents, hooks, and MCP servers can each be set up and used without a plugin. A plugin bundles them so you can get someone else's setup with one command, or hand your own setup to a team.
A skill inside a plugin appears as /plugin-name:skill-name. For example, the commit skill in the commit-commands plugin is /commit-commands:commit.
Install steps
The first time you start an interactive session in the terminal, Claude Code automatically registers Anthropic's official marketplace (claude-plugins-official). You do not need to add a marketplace separately for official plugins.
Running /plugin install inside a session does not install right away. It opens the plugin's detail screen. You check what will be added, choose a scope, and then install.
/plugin install commit-commands@claude-plugins-official
Choosing an install scope
- user: only you, in all projects on this computer. Recorded in ~/.claude/settings.json.
- project: turned on for everyone who works in this repository. Recorded in .claude/settings.json, which you commit. Teammates still need to install it once on their own computers.
- local: only you, in this repository. Recorded in .claude/settings.local.json.
- If the same plugin appears in more than one scope, local wins over project, and project wins over user.
Managing and checking plugins
Run /plugin and press Tab to reach the Installed tab, where you can enable, disable, update, and remove plugins. From the shell, you can also use claude plugin list, claude plugin disable <name>, and claude plugin uninstall <name>.
If an install does not show up right away, run /reload-plugins. Auto-update is on by default for official marketplace plugins, but for a running session it takes effect from the next session. Other marketplaces have it off by default.
When a plugin is the wrong fit, and the cost
- If you only need one setting, it is simpler to put it directly in a folder like ~/.claude/skills/ without a plugin.
- For plugins you have turned on, skill names and descriptions go into context on every turn, even in sessions that do not use them. Turn off the ones you do not use.
- A plugin can run code with your permissions through hooks and MCP servers. For a marketplace you do not know, read the component list on the detail screen before installing.
- /plugin does not work in non-interactive runs such as claude -p. In that case, use claude plugin install from the shell.
Real examples
You want to use a plugin from the official marketplace in all your projects, just for yourself
/plugin install commit-commands@claude-plugins-official
The detail screen opens. Check the components, choose user scope (Install for you), and it installs. If the last line of the summary says "Plugin is now active.", you can use it right away. If it tells you to reload, run /reload-plugins. After that, typing / shows /commit-commands:commit in the list.
You want to use a plugin from an unofficial marketplace a coworker made
/plugin marketplace add your-org/plugins /plugin install deploy-helper@your-org
First you register the GitHub repository as a marketplace, then install in the name@marketplace form. your-org and deploy-helper are example names. The official docs also have a one-line form, /plugin install <name> --marketplace <repo>, which needs v2.1.275 or later.
Common mistakes and when not to use it
- If you install at project scope and only commit .claude/settings.json, the plugin is not installed on your teammates' computers. Each teammate needs to run claude plugin install <name>@<marketplace> --scope project once.
- If you write a marketplace address without https://, it is read as the GitHub owner/repo shorthand and fails. For a regular git URL, include https://.
- In name@marketplace, the part after the @ is the marketplace's registered name, not the repository address.
- Removing a marketplace also removes every plugin you installed from it.
- Keeping many plugins on increases per-turn context and usage. Clean up using the "Not used recently" list on the Installed tab.
FAQ
How is a plugin different from a skill?
A skill is a single unit of instructions in one SKILL.md. A plugin is a packaging unit that bundles skills, agents, hooks, and MCP servers for installation. You call a skill inside a plugin as /plugin:skill-name.
How do I turn a plugin off for a while?
On the Installed tab in /plugin, press Space to turn it off, or run claude plugin disable <name> from the shell. It is only disabled, not removed.
The official marketplace is not in my list.
It is registered automatically the first time you start an interactive terminal session. If you are installing by script on a new computer first, run claude plugin marketplace add anthropics/claude-plugins-official first.
Checked against the official docs on 2026-10-30. Sources: Claude Code docs: Install and manage plugins, Claude Code docs: Plugins overview, anthropics/claude-plugins-official. How we write