Claude Code Plugins: Install, Build, and Verify

What Is a Claude Code Plugin?

A Claude Code plugin is a directory that bundles skills, subagents, hooks, MCP servers, LSP servers, and executables into one installable, versioned unit. Anthropic's plugin documentation frames the choice as standalone configuration in a .claude/ directory versus a plugin, and the split is about distribution rather than capability.

Everything a plugin contains can already live loose in .claude/. Packaging it changes three things:

• Namespacing - a standalone skill is invoked as /hello, while the same skill inside a plugin becomes /plugin-name:hello. Two plugins can ship a skill with the same name and neither shadows the other.
• Versioning - the version field in the manifest pins the plugin, and users only receive updates when you bump it.
• Distribution - a plugin can be published to a marketplace, installed with one command, and updated in the background, which loose files in a repository cannot.

The manifest itself is optional. A directory whose components sit in the default locations loads without a plugin.json, though you need one to set the name, description, and version that the plugin manager displays.

Plugins vs Skills, Subagents, and MCP Servers

These five names get used interchangeably in forum threads, and they are not interchangeable. Four of them are capabilities. One of them is the box the other four ship in.

If you are weighing whether a capability belongs in a plugin at all, the same trade-off shows up one layer down in MCP vs CLI for AI agents. For the components themselves, we cover how Agent Skills work, Claude Code subagents and agent teams, and how the Model Context Protocol works in dedicated guides.

One naming detail trips people up. A plugin can also contain a commands/ directory, which holds skills as flat Markdown files. It is the older layout, and the documentation directs new plugins to use skills/ instead.

What Goes Inside a Plugin Directory

This is where most first plugins break, and Anthropic flags it as a common mistake in the documentation: only plugin.json goes inside .claude-plugin/. Every other directory sits at the plugin root, one level up.

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # the ONLY file that belongs in here
├── skills/
│   └── code-review/
│       └── SKILL.md
├── agents/                  # subagent definitions
├── hooks/
│   └── hooks.json           # lifecycle event handlers
├── monitors/
│   └── monitors.json        # background watchers
├── bin/                     # executables added to the Bash tool PATH
├── .mcp.json                # MCP server configuration
├── .lsp.json                # language server configuration
└── settings.json            # defaults applied when the plugin is enabled

The plugin root means that plugin's own directory, never your global ~/.claude/. A .mcp.json dropped at ~/.claude/.mcp.json is not read at all. A plugin that ships exactly one skill can skip the skills/ folder and put SKILL.md at the plugin root.

The manifest is small. Only name is doing real work, because it sets the namespace prefix for every skill the plugin provides:

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

How to Install a Claude Code Plugin

Installing is two steps that people often collapse into one: register a catalog, then install a plugin from it. Adding a marketplace installs nothing by itself.

The official Anthropic marketplace is the exception, because Claude Code registers it the first time you start it interactively. On a machine with no plugins installed, that is the entire starting state:

$ claude --version
2.1.119 (Claude Code)

$ claude plugin marketplace list
Configured marketplaces:

  ❯ claude-plugins-official
    Source: GitHub (anthropics/claude-plugins-official)

$ claude plugin list
No plugins installed. Use `claude plugin install` to install a plugin.

From there, installing takes the plugin name and the marketplace name, joined by an at sign:

/plugin install github@claude-plugins-official

# GitHub shorthand, owner/repo
/plugin marketplace add anthropics/claude-plugins-community

# any git host, full URL, optional #ref for a branch or tag
/plugin marketplace add https://gitlab.com/company/plugins.git#v1.0.0

# a local directory, useful while developing the catalog
/plugin marketplace add ./my-marketplace

# a hosted marketplace.json
/plugin marketplace add https://example.com/marketplace.json

{
  "enabledPlugins": {
    "formatter@my-marketplace": true,
    "code-reviewer@synced": false
  }
}

How to Build Your Own Plugin

The fastest path is to scaffold, load the directory directly, and iterate without installing anything. The --plugin-dir flag points Claude Code at a folder for that session, and it accepts a .zip archive as well as a directory.

# scaffold a plugin into your skills directory
claude plugin init my-tool --with skills,hooks

# or load any directory for one session while you iterate
claude --plugin-dir ./my-plugin

# pick up edits without restarting the session
/reload-plugins

One version caveat worth knowing before you copy that first line: claude plugin init is a recent addition. On Claude Code v2.1.119 it is absent, and running it prints the plugin help rather than an error, which reads like nothing happened. Run claude plugin --help to see what your build supports; --plugin-dir works either way, so scaffold by hand if init is missing.

When the plugin is ready to share, publishing means listing it in a catalog rather than uploading it anywhere. A marketplace.json needs a name, an owner, and a plugins array, and each entry points at a source that can be a relative path, a GitHub repository, a git URL, an npm package, or a zip archive.

{
  "name": "company-tools",
  "owner": { "name": "DevTools Team" },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting on save"
    }
  ]
}

Push that to a repository your team can read and they run /plugin marketplace add owner/repo. A private repository keeps the catalog internal, which is the supported path for org-only tooling.

How to Verify a Plugin Actually Works

Anthropic ships a validator, and the plugins reference lists claude plugin validate among its debugging and development tools.

Anthropic's plugin authoring guide separately tells authors to run it locally before submitting to the community marketplace, so it is worth being precise about what it covers.

To test the boundary, I built a plugin whose only skill is deliberately dishonest. Its description claims it checks accessibility; its instruction body says to reply with the word done and do nothing else. Running the validator against it on Claude Code v2.1.119 produced this:

$ claude plugin validate ./demo-plugin
Validating plugin manifest: ./demo-plugin/.claude-plugin/plugin.json

⚠ Found 1 warning:

  ❯ author: No author information provided. Consider adding author details for plugin attribution

✔ Validation passed with warnings

Exit code zero. The single complaint is a missing author field. The validator reads the manifest and the structure, which is exactly what it is documented to do, and it has no opinion about whether the skill inside does what it claims.

That gap matters more as plugins move into shared repositories, because a project-scope install applies to everyone who clones the repo. The checks worth adding sit outside the manifest:

• Component inventory - open the plugin detail view, or run claude plugin details, and confirm the commands, agents, hooks, and servers it contributes match what the description promised.
• Trigger each component - invoke the skill by its namespaced name, check agents appear in /context, and cause the event a hook matches so you can see it fire in the debug log.
• Behavioural assertion - for any plugin that touches your product's UI, the question is not whether the skill ran but whether the resulting change is correct in a real browser.

That last one is the gap TestMu AI's Kane CLI is built for. It is a deterministic browser agent that takes a natural-language objective, drives a real Chrome instance through the Chrome DevTools Protocol, and returns an evidence-backed verdict rather than a log of clicks. Because it runs from the terminal and in CI, it slots into the same loop as the coding agent: the plugin makes a change, and a separate agent confirms the rendered result. We walk through that pairing in verifying what Claude Code ships, and the Kane CLI documentation covers installation and CI setup.

Why Your Plugins Are Not Showing Up

Almost every report of a plugin that installed but did nothing resolves to one of four causes. Work them in order.

• It installed but never activated - the install summary tells you which. If it says Run /reload-plugins to activate, run that. If the reload warns it will re-read the conversation, rerun it as /reload-plugins --force.
• Directories are in the wrong place - skills/, agents/, and hooks/ inside .claude-plugin/ produce a plugin that loads with none of its components.
• Something failed at load time - open /plugin and read the Errors tab. A language server whose binary is missing reports Executable not found in $PATH there.
• The cache is stale - clear it with rm -rf ~/.claude/plugins/cache, restart Claude Code, and reinstall the plugin.

A fifth cause is worth knowing before it confuses you: an invalid configuration entry is skipped silently rather than reported. Launch with claude --debug to see why one was dropped.

Are Claude Code Plugins Safe to Install?

Anthropic's own framing is direct: plugins and marketplaces are highly trusted components that can execute arbitrary code on your machine with your user privileges. Two mechanisms explain why that is the accurate description rather than a cautious one.

• Hooks run shell commands - a hook bound to PostToolUse executes on your machine every time Claude edits a file, with whatever command the plugin author wrote.
• bin/ joins your PATH - executables in that directory are added to the Bash tool's PATH for as long as the plugin is enabled.

The practical control is the detail pane shown before you confirm an install. It lists the commands, agents, skills, hooks, and MCP and LSP servers the plugin will add, alongside a context-cost estimate and a last-updated date. A plugin that asks for hooks when its description only promised a slash command is worth a closer read of the source.

Scope discipline helps too. Install to local scope while you evaluate something, and promote it to project scope only once you trust it, because project scope commits the decision for everyone who clones the repository.

What to Do First

Run /plugin and open the Discover tab. The official marketplace is already registered, so you can install one plugin to local scope, trigger its main skill, and read the Errors tab before you decide anything else. Ten minutes there teaches more than any catalog listing.

If you are testing your own product, the catalog gap is worth knowing about. Counting the plugins array in the official Anthropic marketplace catalog on 27 August 2026 returned 289 entries, of which 275 carry a category label. Anyone can reproduce the count by fetching that file. Development accounts for 119 of them and database for 38, while the testing category holds 2. Plenty of test-adjacent tooling is filed elsewhere, but the labelled testing shelf is close to empty.

Claude Code plugins reward the same discipline as any other dependency: package the workflow your team repeats, keep the manifest honest, and put a real check behind anything that touches the UI. Start with the agentic coding CLI tools your team already runs, then add verification with Kane CLI so an agent-authored change is confirmed in a real browser before it merges.