Claude Code plugins
for your whole team.

What is a Claude Code plugin?

A plugin is a directory of components that Claude Code installs, updates and turns off as one unit: skills, subagents, hooks, MCP servers and more. Plugins come from a marketplace, a repository with a .claude-plugin/marketplace.json that lists plugins and where to fetch each one. It is a catalog, not a hosted store.

Skills, agents and hooks all work without a plugin. Package them as one when several repositories or a whole team need the same setup, or when you want versioned releases. A plugin's skills run as /plugin-name:skill-name, so they never clash with yours.

How to install a Claude Code plugin

Anthropic's official marketplace, claude-plugins-official, is added the first time you start Claude Code in a terminal. Any other marketplace you add once, from a GitHub owner/repo (add #ref to pin a tag), a git URL, a local path starting with ./, or the URL of a marketplace.json.

In a session, /plugin install opens the plugin's details, with what it will install and, for official plugins, its context cost, then asks for a scope. From a shell it installs at user scope unless you pass --scope. The install summary says whether to run /reload-plugins.

/plugin marketplace add your-org/claude-plugins
/plugin install formatter@your-org
/reload-plugins

claude plugin marketplace add your-org/claude-plugins
claude plugin install formatter@your-org --scope project
claude plugin list

What goes in a plugin folder

Each component has a fixed place under the plugin root, and only the manifest goes inside .claude-plugin/: a skills folder saved there doesn't load. The manifest itself is optional, and when present only name is required. That name prefixes every skill and agent the plugin adds.

A plugin can also carry LSP servers (.lsp.json), output styles, themes, monitors and a settings.json of defaults. commands/ is the older, flat format for skills.

my-plugin/
├── .claude-plugin/
│   └── plugin.json        # the manifest
├── skills/review/SKILL.md # runs as /my-plugin:review
├── agents/reviewer.md     # subagent my-plugin:reviewer
├── hooks/hooks.json       # same shape as "hooks" in settings.json
├── .mcp.json              # MCP servers
└── bin/                   # on the Bash tool's PATH while enabled

{
  "name": "my-plugin",
  "description": "Review skills and a reviewer agent for our repos",
  "version": "1.0.0",
  "author": { "name": "Platform team" }
}

Build and test a plugin locally

You don't need a marketplace while you build. claude plugin validate checks the manifest and the frontmatter of every skill and agent, and --plugin-dir loads the plugin for one session. After an edit, /reload-plugins applies it without a restart.

When a component is missing, the Errors tab in /plugin gives the reason, such as a path that doesn't exist, and claude plugin details lists what Claude Code found. claude plugin init my-tool scaffolds a plugin in ~/.claude/skills/ that loads in every session.

claude plugin validate ./my-plugin   # exits 0 on "Validation passed"
claude --plugin-dir ./my-plugin      # load it for this session only
# inside the session:
/my-plugin:review
/reload-plugins                      # pick up edits

Share plugins with your team through a marketplace

A marketplace is a .claude-plugin/marketplace.json with a name, an owner and a plugins list, and each entry needs a name and a source. Write relative sources from the marketplace root, and give each entry the same name as its plugin.json: people install by the entry name, while the plugin's skills carry the manifest name.

To roll it out per repository, commit the two keys in the second file below to the project's .claude/settings.json. Once a teammate trusts the folder, Claude Code registers the marketplace and loads the plugins it lists by relative path. A plugin fetched from its own repository still needs claude plugin install formatter@your-org --scope project once on each machine; until then /plugin reports it as not installed.

{
  "name": "your-org",
  "owner": { "name": "Platform team" },
  "plugins": [
    {
      "name": "formatter",
      "source": "./plugins/formatter",
      "description": "Formats files after every edit"
    }
  ]
}

{
  "extraKnownMarketplaces": {
    "your-org": {
      "source": { "source": "github", "repo": "your-org/claude-plugins" }
    }
  },
  "enabledPlugins": {
    "formatter@your-org": true
  }
}

Before a plugin reaches the whole team

A plugin runs as you. Its hooks and MCP servers run outside the sandbox with your user permissions, files in its bin/ folder are on Claude's PATH, and auto-update, on by default for Anthropic's official marketplaces and off for third-party ones, can change files after you reviewed them. Read hooks/hooks.json, .mcp.json and bin/ before you install.

Every enabled plugin also costs context on every turn: the name and description of each skill and agent Claude can call loads whether or not the plugin is used. claude plugin details prints a plugin's always-on tokens, and the Installed tab in /plugin groups plugins you haven't used recently.

That cost is highest when nobody uses the plugin. In one engineer's 323 Claude Code sessions (September 2 to October 3, 2026), the Stripe plugin, enabled the whole time, used none of its 10 skills or its MCP tools.

A plugin you can read: Zest

Zest's own Claude Code plugin is a small, real example of the format: a hooks/hooks.json with SessionStart, SessionEnd and PostToolUse hooks that run a command from the plugin, and older-format commands such as /zest:login and /zest:ignore. Install it with /plugin marketplace add https://github.com/Winding-Labs/zest-claude, then /plugin install zest, then /reload-plugins, then /zest:login.

From then on Zest records the skills and subagents each session uses, naming the ones that come from a plugin, next to the session's models, tokens and the pull request it led to. A team sees which plugins earn their place in everyone's context. More in Claude Code usage.