What Are Claude Code Plugins and the Plugin Marketplace? A Complete Guide

As you use Claude Code more, you accumulate your own slash commands, frequently-used subagents, MCP servers, and hooks. A plugin is the mechanism that bundles them into one unit you can version, share, and reuse across teams and projects, and a marketplace is where they're distributed (plugins arrived in public beta in October 2025; in 2026 an official directory and /plugin search/list were added).

This article covers what a plugin is, its structure, how to use it, marketplaces, building and publishing your own, and distribution scope and safety — based on the official docs. Three takeaways up front. (1) A plugin is one directory bundling "skills / commands / subagents / hooks / MCP servers," with .claude-plugin/plugin.json as the manifest. (2) Use /plugin to add a marketplace and install to add a plugin. (3) Building your own is easy — drop in a plugin.json and a SKILL.md, test with claude --plugin-dir, and publish via git.

1. What a Claude Code plugin is

The official definition: a plugin is "a self-contained directory that bundles custom Claude Code functionality so it can be versioned, shared, and reused." A single plugin can include any combination of:

In short, a plugin is "a Claude Code extension boxed into a shareable form." Customizations you used to configure separately get collected into one repo so your whole team reproduces the same setup. You can also include LSP servers, background monitors, and executables (bin/), but the six above are enough to start.

2. Plugin structure

There's one important rule about layout: only plugin.json goes inside .claude-plugin/. The commands/, agents/, skills/, and hooks/ directories sit at the plugin root (not inside .claude-plugin/).

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # manifest — ONLY this file lives here
├── skills/
│   └── code-review/SKILL.md
├── agents/
│   └── security-reviewer.md
├── hooks/hooks.json
├── .mcp.json
└── README.md

A minimal plugin.json manifest:

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

name is the identifier and also the skill namespace (a skill is invoked like /my-first-plugin:hello). version is optional: if set, users only get updates when you bump it. If you omit version when distributing via git, the commit SHA acts as the version (every commit is a new version).

3. How to use — /plugin and marketplaces

Install via /plugin, which opens a tabbed manager (Discover / Installed / Marketplaces / Errors). The core commands:

# Add a marketplace (the distribution catalog)
/plugin marketplace add anthropics/claude-code        # a GitHub owner/repo
/plugin marketplace add ./my-marketplace              # a local path
/plugin marketplace add https://example.com/marketplace.json

# Install / manage plugins (user scope by default)
/plugin install plugin-name@marketplace-name
/plugin enable  plugin-name@marketplace-name
/plugin disable plugin-name@marketplace-name
/plugin uninstall plugin-name@marketplace-name

# List (filter with --enabled / --disabled). /plugin also has a search bar
/plugin list
/plugin list --enabled

# Apply changes without restart
/reload-plugins

"Adding a marketplace" = "registering a catalog," which by itself installs no plugins — you add the catalog, then install plugins individually. For scripting there are non-interactive CLI equivalents like claude plugin install …. If a plugin's bundled MCP server won't connect, see MCP connection error fixes.

4. What a marketplace is

A marketplace is a catalog with a .claude-plugin/marketplace.json that lists plugins and where to fetch each (a git repo, a local path, or a hosted file). There are official ones and a community one.

So if you just want to use plugins, the official marketplace is ready immediately. Add the community catalog or your own internal one as needed.

5. Build and publish your own

Building one is surprisingly easy. Start by placing a manifest and a skill, then testing locally.

# 1) Scaffold
mkdir -p my-first-plugin/.claude-plugin my-first-plugin/skills/hello
# write .claude-plugin/plugin.json and skills/hello/SKILL.md

# 2) Test without installing (a .zip works too)
claude --plugin-dir ./my-first-plugin

To publish, just put a .claude-plugin/marketplace.json at the root of a git repo. Users add it with /plugin marketplace add owner/repo.

{
  "name": "my-plugins",
  "owner": { "name": "Your Name" },
  "plugins": [
    {
      "name": "quality-review-plugin",
      "source": "./plugins/quality-review-plugin",
      "description": "Adds a quick code-review skill"
    }
  ]
}

Versioning resolves in order: version in plugin.json → (else) version in the marketplace entry → (else) the commit SHA. If you pin version, bump it on every release (forget, and users won't update). Validate before publishing with claude plugin validate .. To get listed in the official community catalog, apply via the submission form (Team/Enterprise and other conditions apply).

6. Distribution scope and safety

Installs have a scope: user (default, all projects) / project (all repo collaborators, recorded in .claude/settings.json) / local (just you, this repo) / managed (admin-distributed, not user-modifiable). For team distribution, put extraKnownMarketplaces and enabledPlugins in the project's .claude/settings.json, and members are prompted to install when they trust the folder.

Summary

A Claude Code plugin bundles skills, slash commands, subagents, hooks, and MCP servers into one directory you can version, share, and reuse (the manifest is .claude-plugin/plugin.json; commands/ etc. go at the root). They're distributed via marketplaces, and the official one (claude.com/plugins) is available out of the box. Install with /plugin marketplace add → /plugin install → (as needed) /plugin list, search, /reload-plugins.

Building your own is a short path: drop in a plugin.json and a SKILL.md, test with claude --plugin-dir, then publish by putting a marketplace.json in a git repo. Scopes are user / project / local / managed, with team distribution via .claude/settings.json. But plugins can run arbitrary code, so install only from trusted publishers and restrict sources with strictKnownMarketplaces in orgs. Plugins can also bundle hooks that run automatically at lifecycle points—see the deep-dive for how they work. Related: Claude Agent Skills, MCP, Claude Code Artifacts.

FAQ

Q. What's the difference between a plugin and a skill?
A. A skill is one of the components inside a plugin. A plugin is a distribution unit (directory) that bundles skills plus slash commands, subagents, hooks, and MCP servers. The plugin is the "box" for shipping your frequently-used skills and commands to a team; a skill is one of the "instruction sheets" inside that box.

Q. How do I install a plugin?
A. First add a marketplace (catalog) with /plugin marketplace add owner/repo, then install individually with /plugin install plugin-name@marketplace-name. The official marketplace (claude-plugins-official) is available automatically from first launch, and you can browse at claude.com/plugins or via /plugin Discover. Toggle with /plugin enable|disable; list with /plugin list.

Q. Can I build and distribute my own plugin?
A. Yes. Place a .claude-plugin/plugin.json (manifest) and a skills/…/SKILL.md, and test without installing via claude --plugin-dir ./your-plugin. To publish, just put a .claude-plugin/marketplace.json at the root of a git repo; users add it with /plugin marketplace add owner/repo. Remember: only plugin.json goes inside .claude-plugin/ — skills/ etc. live at the root.

Q. How does versioning work?
A. It resolves as: version in plugin.json → (else) version in the marketplace entry → (else) the git commit SHA. If you set version, updates only reach users when you bump it, so bump it every release (otherwise users stay on the old one). Omit version and every commit is a new version. Validate before publishing with claude plugin validate ..

Q. Are third-party plugins safe?
A. Not unconditionally. The official docs note a plugin "can execute arbitrary code with your privileges," and Anthropic does not verify third-party plugins or their bundled MCP. Install only from trusted publishers, and review the code if you're unsure. Organizations can restrict allowed sources with strictKnownMarketplaces ([] for a full lockdown).