Claude Code plugins and the plugin marketplace

What are Claude Code plugins?

A plugin packages several Claude Code extensions so you can install, update and share them together. According to the plugins overview, a plugin is a directory of components, usually with a manifest. The manifest is a JSON file at .claude-plugin/plugin.json that gives the plugin its name and can add a version, a description and other metadata.

The components are what the plugin adds to Claude Code:

• Skills: SKILL.md instructions that Claude loads when relevant and that you can also run as a command. See the guide to Claude Code skills.
• Agents: subagent definitions Claude can delegate to.
• Hooks: commands Claude Code runs at points in its lifecycle, such as after every edit. See the guide to Claude Code hooks.
• MCP servers: tool servers Claude Code connects to while the plugin is enabled.
• A hooks module: hooks written as JavaScript functions that can also draw panes and add commands. The docs call a plugin that has one a mod.

None of the components is required. A plugin with one skill is valid. Plugin skills and agents get the plugin name as a prefix, so a hello skill in a plugin called my-first-plugin runs as /my-first-plugin:hello. That prefix is why two plugins can each ship a hello skill without colliding.

Do you need a plugin, or will a skill or hook do?

Skills, subagents, hooks and MCP servers all work on their own, with no plugin. A skill saved in ~/.claude/skills/ is available in every project on your machine. The docs say to use a plugin when you want several of these packaged as one unit, or to install a setup someone else built with one command and updates from its marketplace. Make one yourself to give your setup to teammates, install it in many projects, or publish versioned releases.

One consequence is worth knowing before you install anything. An enabled plugin is part of every session, not only the ones where you use it. For each skill, agent and command that Claude can invoke on its own, the name and description sit in Claude's context on every turn. Those tokens count toward your usage even when nothing from the plugin runs. The full text of a skill loads only when it is used. The usage limits guide explains how that adds up.

What is the Claude Code plugin marketplace?

A marketplace is a repository or directory with a .claude-plugin/marketplace.json file that lists plugins and where to fetch each one. The docs describe it as a catalog, not a hosted store. You add a marketplace once, then install plugins from it by name, in the form plugin@marketplace, such as commit-commands@claude-plugins-official.

Searchers often mean the website. The docs make a distinction here: a plugin marketplace is not Claude Marketplace, the website where you browse plugins, connectors and partner products. The website is not a marketplace you add with /plugin marketplace add. It can, however, copy the install command for you: a plugin's Claude Code button there copies claude plugin install <name>@claude-plugins-official.

Most of the official marketplace comes from partners and other authors, not from Anthropic. The docs name a few that Anthropic maintains, such as commit-commands, code-review and feature-dev, plus the language server plugins. The catalog changes often, so browse the Discover tab rather than relying on a list in an article.

How do you install a Claude Code plugin?

In a terminal session, install by naming the plugin and its marketplace. The example below uses the one from the docs:

/plugin install commit-commands@claude-plugins-official

In a session this command does not install right away. It opens the /plugin panel on that plugin's details so you can review it and pick a scope first. To browse instead, run /plugin with no arguments. The panel opens on the Discover tab, which lists plugins from your marketplaces; type to search and press Enter to open one.

1. Review what it adds. The details pane lists what will install: commands, agents, skills, hooks, and MCP and LSP servers. For plugins in the official marketplace it can also show a Context cost with two token estimates, Every turn and When invoked.
2. Choose a scope. User scope, project scope or local scope (table below).
3. Read the install summary. The last sentence tells you whether the plugin is active now (Plugin is now active.), needs a reload (Run /reload-plugins to apply.), needs its MCP server configured, or failed to load.
4. Confirm it works. Type / and look for the plugin's skills in the form /<plugin>:<skill>, or run claude plugin list in your shell.

Project scope has a catch the docs spell out. Committing the settings entry turns the plugin on for collaborators but does not download it. Each collaborator also runs claude plugin install <name>@<marketplace> --scope project once. When the same plugin is set at several scopes, local overrides project, and project overrides user.

You can also install without opening a session, which suits setup scripts:

claude plugin install formatter@your-org --scope project
claude plugin list

The default scope from the shell is user. Plugins installed this way load the next time you start Claude Code, or when you run /reload-plugins in an open session.

How do you add a marketplace?

You only need this when the plugin is not in the official marketplace. Run /plugin marketplace add followed by the source, or claude plugin marketplace add from your shell. /plugin market works as a shorter form.

/plugin marketplace add anthropics/claude-plugins-community
/plugin install some-plugin@claude-community

Include the https:// prefix on every URL, or use the git@host:path form for SSH. A bare gitlab.example.com/group/repo.git is read as GitHub shorthand and rejected. When the command works it prints Successfully added marketplace: <name>, and the plugins appear on the Discover tab with no reload.

To add a marketplace and install in one step, name the source with --marketplace: claude plugin install deploy-helper --marketplace your-org/plugins. The shell form needs Claude Code v2.1.292 or later and the in-session form v2.1.275 or later. Private marketplaces use the git credentials already on your machine and never prompt, so HTTPS needs a credential helper and SSH needs a key that works without a passphrase prompt.

A note on old tutorials. The claude-code-plugins marketplace in the anthropics/claude-code repository is deprecated. The docs say to install with claude plugin install <plugin>@claude-plugins-official and to skip any tutorial step that runs /plugin marketplace add anthropics/claude-code.

How do you update, disable and remove plugins?

The Installed tab in /plugin lists your plugins. Press Space to enable or disable the selected one, Enter to open its details, where you can choose Update now or Uninstall. You can also run /plugin enable, /plugin disable or /plugin uninstall. When you close the panel with pending changes, Claude Code runs /reload-plugins for you. If the reload would invalidate the prompt cache, it warns and leaves the change pending until you run /reload-plugins --force.

Plugins update automatically only when their marketplace has auto-update turned on. It is on by default for claude-plugins-official and the other official names (with two exceptions in the docs), and for marketplaces added from claude.ai. It is off by default for every other marketplace, including the community and third-party ones. Toggle it on the Marketplaces tab by selecting a marketplace and choosing Enable auto-update or Disable auto-update.

The running session keeps the versions it already loaded. After an update you see Plugin updated: <name> · Run /reload-plugins to apply, and the next session loads the new version. There is no command that updates every plugin at once. To update one, use Update now or claude plugin update <plugin>@<marketplace>. To update everything from one marketplace, choose Update marketplace on the Marketplaces tab.

• See what a plugin costs: claude plugin details <name> prints an Always-on line, the number of tokens the plugin adds to every session where it is enabled, with per-component rows.
• Find unused plugins: plugins you installed and have not used recently appear under Not used recently on the Installed tab, each with a Last used line.
• Remove a marketplace: claude plugin marketplace remove <name> uninstalls every plugin you installed from it.

Updating the plugin is separate from updating Claude Code itself. For that, see how to update Claude Code.

What does the plugin structure look like?

A plugin is a folder. The manifest goes in a .claude-plugin/ directory, and everything else sits next to that directory at the plugin root, not inside it. This layout follows the docs' example plugin:

my-plugin/
├── .claude-plugin/
│   └── plugin.json        # manifest: only "name" is required
├── skills/
│   └── review/
│       └── SKILL.md       # runs as /my-plugin:review
├── commands/
│   └── about.md           # older single-file format; write new ones as skills
├── agents/
│   └── security-reviewer.md
├── hooks/
│   └── hooks.json
├── scripts/
│   └── format.sh          # called by a hook
└── .mcp.json              # MCP servers

The docs also describe a bin/ directory, whose executables Claude Code adds to the PATH of the Bash tool's shell while the plugin is enabled. The minimal manifest looks like this:

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

name is required, becomes the prefix on every skill and agent, and must not contain spaces. description is the text users see in /plugin. version is optional; setting it keeps users on that version until you change it. A skill is a directory under skills/ that contains a SKILL.md file. The docs' first example is a skill with disable-model-invocation: true in its frontmatter, so Claude does not run it on its own.

Two commands cover the build loop. claude plugin validate ./my-first-plugin checks the manifest and the skill frontmatter and ends with ✔ Validation passed. claude --plugin-dir ./my-first-plugin starts a session with the plugin loaded for that session only, without installing it. You do not need a marketplace while you develop.

How do you publish your own marketplace?

A marketplace is a directory with a .claude-plugin/marketplace.json file plus the plugins it lists. You push it to a git host and anyone with access registers it with one command. The file needs a name, an owner and a plugins array, and each plugin entry needs a name and a source.

{
  "name": "my-marketplace",
  "description": "Plugins for my team",
  "owner": {
    "name": "Your Name"
  },
  "plugins": [
    {
      "name": "my-first-plugin",
      "source": "./plugins/my-first-plugin",
      "description": "A greeting plugin to learn the basics"
    }
  ]
}

1. Create my-marketplace/.claude-plugin/ and my-marketplace/plugins/, and copy your plugin under plugins/.
2. Run claude plugin validate ./my-marketplace.
3. Register it: claude plugin marketplace add ./my-marketplace.
4. Install from it: claude plugin install my-first-plugin@my-marketplace.

The docs flag two mistakes that cause most failed installs from a new marketplace: a relative source path written from the wrong directory (it starts at the marketplace root, the folder containing .claude-plugin/), and an entry name that differs from the name in the plugin's own plugin.json. Keep the two names the same.

If you have a repeatable Claude Code workflow worth packaging, the board lists plenty of developer tool ideas. Each one has a generated build prompt, and a plugin is a reasonable shape for several of them.

Are Claude Code plugins safe to install?

Treat a plugin like any program you download. The plugin security page is direct about it: a plugin can execute arbitrary code on your machine with your user privileges. Hooks run as shell commands. Monitors run as background shell commands. MCP and language servers start as processes. Skills, commands and agents enter Claude's context as instructions and influence what Claude does with the tools it already has.

Claude Code's permission rules and sandbox cover the tool calls Claude makes, not the code a plugin runs by itself. The docs say hooks, monitors, MCP servers and LSP servers run outside the sandbox. A marketplace's name tells you who publishes the catalog, not what each plugin in it does. Anthropic's tiers help you see who is behind a catalog, but whatever the tier, read before you install.

• Read the Will install list in the details pane and note any hooks and servers.
• Prefer plugins whose source you can read, and pin a marketplace to a tag with #ref if you want it to stop changing.
• Remember auto-update: when it is on, files you reviewed can change on disk later.
• Disable what you are not using. Each enabled plugin adds its descriptions to every turn.

For permission rules in general, see the Claude Code permissions guide.