skip to content

What is a Claude Code plugin, and where do its manifest and its components sit in the plugin directory?

level: juniorimportance: must knowfreq 24%

answer

  1. one directory, installed as a unit
  2. only plugin.json inside .claude-plugin
  3. component folders at the plugin root
  4. hooks/hooks.json, .mcp.json, .lsp.json, bin/
  5. names prefixed with the plugin name

basics

~20 s

A Claude Code plugin is a directory packaging skills, agents, hooks, MCP and LSP servers as one installable unit. Only the optional manifest lives in .claude-plugin/plugin.json; components sit at the plugin root, namespaced by the plugin name.

solid answer

~40 s

A plugin is a folder Claude Code installs and loads as one unit. Its manifest, `.claude-plugin/plugin.json`, is optional; when present it needs a kebab-case `name` and can add `version`, `description` and `author`. Every component sits at the plugin root, never inside `.claude-plugin/`: `skills/<name>/SKILL.md`, `agents/*.md`, `hooks/hooks.json` (the same shape as a settings `hooks` block), `.mcp.json`, `.lsp.json` for language servers, and `bin/` for executables placed on the Bash tool's `PATH`. Components are namespaced by the plugin name, so a `review` skill in `my-plugin` runs as `/my-plugin:review` and two plugins can both ship a `review`. Use a plugin when a setup must be shared, installed in many projects or versioned; standalone `.claude/` files serve one person in one project.

code

json · 6 lines
json
{
  "name": "team-toolkit",
  "description": "Review skills, a reviewer agent, a format hook and two MCP servers",
  "version": "1.4.0",
  "author": { "name": "Platform Team" }
}

go deeper

for a junior

Recall the one layout rule that matters: only plugin.json goes in .claude-plugin, every component folder sits at the plugin root, and plugin skills run as /plugin-name:skill.

for a middle

Explain each default location (skills, agents, hooks/hooks.json, .mcp.json, .lsp.json, bin) and how names are prefixed, including the mcp__plugin_ tool names that rules and matchers need.

for a senior

Show you know what packaging changes at runtime: hooks fire from load, descriptions cost context every turn, agent frontmatter cannot add hooks or servers, and paths may not escape the root.

for a principal

Weigh when a plugin earns its overhead against standalone .claude files: sharing and versioning across repositories versus a per-turn context cost and code that runs as every user.

## What a plugin is, and when you need one A **Claude Code plugin** is a directory of components that Claude Code installs, enables and loads as a single unit. The components are the same extension points that also work on their own: **skills** (`SKILL.md` instructions), **agents** (subagent definitions), **hooks** (commands run at lifecycle events), **MCP servers** (tools from external systems) and **LSP servers** (language servers for code intelligence). Most plugins arrive from a **marketplace**, a catalog that lists plugins and where to fetch each one. Most of what a plugin carries can also live standalone: a skill in `~/.claude/skills/`, a hook in a settings file, a server in `.mcp.json`. What the plugin mainly adds is packaging: - **One install** brings several components together, with updates from the marketplace. - **Namespacing** keeps two teams' `review` skills from colliding. - **Versioned releases** let you ship the same setup to many repositories and people. For one developer in one project, standalone files under `.claude/` are simpler. ## The directory layout The **plugin root** is the plugin's own directory, the one you would pass to `--plugin-dir`. Each component type has a default location under it: | Component | Default location | What loads | |---|---|---| | Manifest | `.claude-plugin/plugin.json` | Name, version, description, author, path overrides | | Skills | `skills/<name>/SKILL.md` | One folder per skill | | Commands | `commands/*.md` | The older single-file form; prefer skills | | Agents | `agents/*.md` | One subagent per file | | Hooks | `hooks/hooks.json` | A top-level `"hooks"` key, same shape as in settings | | MCP servers | `.mcp.json` | Same shape as a project `.mcp.json` | | LSP servers | `.lsp.json` | Server command, args and file extensions | | Executables | `bin/` | Added to the Bash tool's `PATH` while enabled | Only `plugin.json` belongs inside `.claude-plugin/`. A `skills/` folder saved there does not load, and a `CLAUDE.md` at the plugin root is not loaded as context at all; `claude plugin validate` warns about it. Instructions that should reach Claude belong in a skill, and a rule that must hold every time belongs in a hook, because a hook is enforced by the harness while a skill only guides the model. ## The manifest The manifest is **optional**. Without one, Claude Code loads whatever it finds in the standard layout, and the plugin name comes from the marketplace entry or, with `--plugin-dir`, from the directory name. When you write one, `name` is the field that matters: no spaces, `@`, `:` or path separators, kebab-case by convention. `version` is optional too, but setting it holds users on that version until you change the string. Manifest keys such as `skills`, `agents` or `mcpServers` can point at non-default paths, and a path that resolves outside the plugin root is rejected. ## How components are named once loaded 1. A skill in `skills/review/` of plugin `my-plugin` runs as `/my-plugin:review`. 2. An agent file `agents/security-reviewer.md` becomes `my-plugin:security-reviewer`, mentionable as `@agent-my-plugin:security-reviewer`. 3. A server `db` in the plugin's `.mcp.json` shows in `/mcp` as `plugin:my-plugin:db`, and its tools are named `mcp__plugin_my-plugin_db__<tool>`; that full name is what permission rules and hook matchers must use. Two packaging details trip people up. A plugin agent's frontmatter ignores `permissionMode`, `hooks` and `mcpServers`, so an agent file cannot smuggle in hooks or servers; those must be declared as plugin hooks and plugin MCP servers. And a plugin's hooks register when the plugin loads and fire on their events from then on, whether or not any of its skills is ever used. ## What an enabled plugin adds to every session An enabled plugin is part of every session, not only the ones where you call it: - The **name and description** of each skill, agent and command Claude may invoke on its own sits in context on every turn; full bodies load only when used. - **MCP and LSP servers** run alongside the session, and **hooks** fire at their events. - Whatever it runs, it **runs as you**. `claude plugin details <name>` prints a component inventory and the always-on token cost, which is the quickest way to see a plugin's footprint. ## Code-intelligence plugins A **code-intelligence plugin** is a plugin whose component is an LSP server for one language, such as `typescript-lsp` or `pyright-lsp` in Anthropic's official marketplace. It names the server command and extensions but does not ship the binary, which must be on the `PATH` of the shell that starts `claude`. Once running, Claude gets diagnostics after each edit and a read-only `LSP` tool for jumping to definitions and references.

  • Why does a CLAUDE.md placed at a plugin's root not change Claude's behaviour?
    Claude Code does not load a `CLAUDE.md` from a plugin root as context, and `claude plugin validate` warns that it is not loaded. Put guidance the model should read into a skill, whose description stays in context and whose body loads when relevant. If the rule must hold on every call, ship it as a hook in `hooks/hooks.json`, because the harness enforces a hook while the model only reads a skill.
  • What does a code-intelligence plugin add, and why can installing it alone leave Claude with no diagnostics?
    It declares a language server in `.lsp.json`, so after each edit Claude receives the server's errors and warnings and gains a read-only `LSP` tool for definitions and references. The plugin does not include the server binary: if `gopls` or `typescript-language-server` is not on the `PATH` of the shell that started `claude`, the `/plugin` Errors tab shows `Executable not found in $PATH`. Cloud sessions never start plugin language servers.
  • How do you name a plugin's MCP tool in a permission rule or a hook matcher?
    Use the full form `mcp__plugin_<plugin>_<server>__<tool>`, for example `mcp__plugin_my-plugin_db__query`. The server itself appears in `/mcp` as `plugin:my-plugin:db`. A hook matcher written against the bare server name never fires, because the tool name Claude Code matches carries the plugin prefix.

  • Skills and hooks go inside .claude-plugin, next to plugin.json.
  • A plugin cannot load at all without a plugin.json manifest.
  • A CLAUDE.md at the plugin root loads as project instructions.
  • Plugin skills keep their bare names, so /review still works.
  • A plugin's hooks run only when one of its skills is invoked.
  • A code-intelligence plugin bundles the language server binary.