A Claude Code plugin is built from components, such as skills, agents, hooks, and MCP servers. Each component has a default folder in the plugin, an optional manifest key in .claude-plugin/plugin.json that replaces or adds to that folder, and a name the user sees. For each key's full field table, see the manifest reference.
Use this page to add a component to a plugin that already loads.
After you add a component, run /reload-plugins in a running session or start a new one so Claude Code loads it. To check the component's file before loading it, run claude plugin validate . in your shell from the plugin directory.
Explore the plugin directory
The explorer shows an example plugin, my-plugin, that has one of every kind of component in its default location:
A review skill and an about command
A security-review subagent
A hook that formats files after Claude edits them, and the scripts/ folder it calls
A log monitor
An output style and a color theme
A route-audit workflow
A hello-plugin executable
Default settings
A local MCP server and a Go language server
Each file is the smallest valid example of its format, there to show the shape rather than to be useful: a real skill or agent carries full instructions and often supporting files, and a real hook or monitor does real work. The sections after the explorer use the same files as their examples and link to fuller ones. Select a file or folder to read what it's for, see what goes in it, and find the section that covers it.
The [manifest](/docs/en/plugins/manifest-reference) is the `plugin.json` file in a plugin's `.claude-plugin/` directory. It contains the plugin's metadata and the `userConfig` values that Claude Code prompts the user for. Claude Code loads a plugin without one, but [Anthropic's directory](/docs/en/plugins/publish#submit-to-anthropics-directory) requires it. Inside the file, only `name` is required. In this one, `description` is the text users see for the plugin in `/plugin`, and `version` keeps users on that version until you change it:
```json theme={null}
{
"name": "my-plugin",
"version": "1.0.0",
"description": "Review, formatting, and database tools for this team"
}
```
A [skill](/docs/en/skills) is a `SKILL.md` file. Save each skill in its own directory under `skills/`. Claude reads every skill's `description`, and when what the user asks for matches it, such as asking Claude to review a pull request here, Claude loads the skill's instructions and follows them. The user can also run it directly as `/my-plugin:review`:
```markdown theme={null}
---
description: Reviews a pull request for style and test coverage. Use when asked to review code.
---
Review the changed files. Report style problems first, then missing tests.
```
A command is a single Markdown file the user runs by name. Commands are the older format: a skill runs by name the same way and can also carry supporting files in its own directory, so write new ones as skills and keep `commands/` for files you already have. This file becomes `/my-plugin:about` and takes the same frontmatter as a skill:
```markdown theme={null}
---
description: Summarize the repository
---
Summarize what this repository does in three sentences.
```
A [subagent](/docs/en/sub-agents) is a separate assistant, with its own instructions and its own context window, that Claude can delegate a task to and get a result back from. Each Markdown file under `agents/` defines one: the frontmatter names it and says when to use it, and the body is its system prompt. This one is named `my-plugin:security-reviewer`, and the user can invoke it with `@agent-my-plugin:security-reviewer`:
```markdown theme={null}
---
name: security-reviewer
description: Reviews code changes for security issues. Use after edits to authentication or input handling.
model: sonnet
---
You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.
```
A [hook](/docs/en/hooks-guide) runs something automatically at a point in Claude Code's lifecycle, such as after every file edit: a shell command, an HTTP request, an MCP tool call, a prompt to a model, or a subagent. Save the plugin's hooks in `hooks/hooks.json` at the plugin root. This one runs the plugin's `scripts/format.sh` after Claude writes or edits a file:
A monitor is a shell command that Claude Code starts in the background when the session starts and keeps running until it ends, using the [Monitor tool](/docs/en/tools-reference#monitor-tool). What it prints reaches Claude as notifications. A `when` field can instead start it the first time a named skill runs. This one tails an error log:
A plugin can include [output styles](/docs/en/output-styles), which change how Claude formats and phrases its replies. Save each output style as `output-styles/.md`. This one appears in `/output-style` as `my-plugin:terse`:
```markdown theme={null}
---
name: terse
description: Answer in as few words as possible
keep-coding-instructions: true
---
Keep every reply short. Skip preambles and summaries.
```
A plugin can include [color themes](/docs/en/terminal-config#create-a-custom-theme) for the Claude Code interface. Save each theme as `themes/.json`. This one appears in `/theme` as `Dracula`, marked as from `my-plugin`:
The `workflows/` folder holds [workflow](/docs/en/workflows) `.js` files: a `meta` block, then a script body that orchestrates several subagents. This one runs as `/my-plugin:audit-routes`:
`bin/` is how a plugin ships a command-line tool. While the plugin is enabled, Claude Code puts this folder on the `PATH` of the shell it runs commands in, so Claude, or a skill's instructions, can run the tool by name without the user installing anything. With this [executable](#executables) in place, `hello-plugin` is a command Claude can run:
```bash theme={null}
#!/bin/bash
echo "hello from my-plugin"
```
The hook in `hooks/hooks.json` runs a script, and this folder is where the example keeps it. The name `scripts/` is a convention, not something Claude Code looks for: the hook points at the file by its path, `${CLAUDE_PLUGIN_ROOT}/scripts/format.sh`. A formatter script might look like this:
A `settings.json` at the plugin root holds [settings](/docs/en/settings-reference) that apply while the plugin is enabled, so a plugin can change how the session behaves and not only add components. Only two keys take effect from a plugin, [`agent`](/docs/en/settings-reference#agent) and [`subagentStatusLine`](/docs/en/settings-reference#subagentstatusline); every other key is dropped. See [Default settings](#default-settings).
This one sets `agent`, which runs the session's main thread as the plugin's own `security-reviewer` agent, so that agent's system prompt, tool restrictions, and model apply to the whole session:
```json theme={null}
{
"agent": "security-reviewer"
}
```
An [MCP server](/docs/en/mcp) gives Claude tools from an external system. Declare it in `.mcp.json` at the plugin root. This one starts a local server from a script inside the plugin, and appears in `/mcp` as `plugin:my-plugin:db`:
An LSP server gives Claude [diagnostics and code navigation](/docs/en/plugins/code-intelligence) for a language. Declare the server in `.lsp.json` at the plugin root. This one connects the Go language server for `.go` files:
Each section below covers one kind of component: where its files go in the plugin, an example that validates, what the user sees once the plugin loads, and the manifest key that changes the default location. Add the ones your plugin needs; none is required.
Skills
A skill is a SKILL.md file that Claude can load when its description matches the task. The user can also run it as a command. Save each skill in its own directory under skills/:
Give the SKILL.md a description so Claude knows when to use it:
---
description: Reviews a pull request for style and test coverage. Use when asked to review code.
---
Review the changed files. Report style problems first, then missing tests.
After you load the plugin, /my-plugin:review runs the skill. The command name and who can invoke it follow these rules:
Command name: /<plugin>:<directory>, so skills/review/SKILL.md in my-plugin is /my-plugin:review. If you set name in the frontmatter, it replaces the last segment and the plugin prefix stays. See how a skill gets its command name
You can also place skills outside the default skills/ directory:
Additional directories: list them in the skills manifest key. They add to the default skills/ scan rather than replacing it, unlike commands and agents
A single skill at the plugin root: with no skills/ directory and no skills manifest key, a SKILL.md at the plugin root loads as one skill. Set name in its frontmatter, because otherwise a marketplace install names the skill after its cache directory rather than your plugin
To include instructions in a plugin, write them as a skill. Claude Code doesn't load a CLAUDE.md at the plugin root, and claude plugin validate warns CLAUDE.md at the plugin root is not loaded as project context.
For frontmatter fields and supporting files, see Skills.
Commands
A command is a single Markdown file the user runs by name, such as /my-plugin:about.
Save a command at commands/<file>.md and it becomes /<plugin>:<file>. A subdirectory adds a segment, so commands/db/migrate.md is /my-plugin:db:migrate.
Command files take the same frontmatter as skills.
Define commands in the manifest
You only need this if you want to keep command files somewhere other than commands/, or to define a short command inside plugin.json without a separate Markdown file. Set the commands manifest key, and Claude Code reads it instead of scanning commands/. The key takes a path, an array of paths, or an object that maps each command name to either a source file or inline content.
This manifest defines /my-plugin:about inline, with no Markdown file:
{"name": "my-plugin",
"commands": {"about": {"content": "Summarize what this repository does in three sentences.",
"description": "Summarize the repository"}}}
Load the plugin and run /my-plugin:about in the session to confirm it loaded.
A subagent is a separate assistant, with its own instructions and context window, that Claude can delegate a task to. Each Markdown file under agents/ defines one:
---
name: security-reviewer
description: Reviews code changes for security issues. Use after edits to authentication or input handling.
model: sonnet
---
You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.
This agent is named my-plugin:security-reviewer, and the user can invoke it explicitly with @agent-my-plugin:security-reviewer. The name form is <plugin>:<name>, where <name> comes from the frontmatter, or from the file name when there is none.
The agents manifest key replaces the agents/ scan.
Organize agents in subfolders
You can put plugin agent files in subfolders of agents/. Claude Code loads them recursively and joins the plugin name, each subfolder name, and the file name with colons to form the agent's scoped name. For example, agents/review/security.md in a plugin named my-plugin loads as my-plugin:review:security. Two settings change that name:
Frontmatter name: it replaces only the file name, so name: audit in agents/review/security.md loads as my-plugin:review:audit
Manifest agents field: a file you list there loads without subfolder names, so "agents": "./custom/review/security.md" loads as my-plugin:security
Frontmatter fields in plugin agents
A plugin agent's frontmatter follows these rules:
Supported fields: name, description, model, effort, maxTurns, tools, disallowedTools, skills, memory, background, omitClaudeMd, isolation, color, and the cacheTtl key of experimental. The only valid isolation value is "worktree". See supported frontmatter fields for what each one does
Ignored fields: permissionMode, hooks, mcpServers, and initialPrompt. An agent file can't add hooks or MCP servers on its own, so add those as plugin hooks and MCP servers instead
Frontmatter that doesn't parse: the agent still loads with every field ignored. It's named after the file, and its description reads Agent from my-plugin plugin. Run claude plugin validate in your shell to find these files
For what each field does and the precedence rules, see Subagents.
Hooks
A hook runs something automatically at a point in Claude Code's lifecycle, such as after every file edit: a shell command, an HTTP request, an MCP tool call, a prompt to a model, or a subagent. Save the plugin's hooks in hooks/hooks.json at the plugin root, under a top-level "hooks" key, in the same shape as the hooks object in settings.json. That lets you copy an existing settings hook in unchanged.
This hook runs a bundled script after every Write or Edit:
Save the script at scripts/format.sh and make it executable.
Load the plugin and ask Claude to edit a file. A PostToolUse hook that exits 0 shows nothing in the transcript, so confirm it ran with debug logging or by what the script itself changes.
Hooks in hooks/hooks.json and in the hooks manifest key both load. For every event and its payload, see Hook events.
When plugin hooks fire
A plugin's hooks don't wait for one of the plugin's skills or commands to be used. Claude Code registers them when a session loads the plugin, and they fire on their events from then on. To limit when a hook runs, narrow its matcher.
The hook's environment, the quoting of ${CLAUDE_PLUGIN_ROOT}, and matchers for the plugin's own MCP tools work as follows:
Environment: every hook process receives CLAUDE_PLUGIN_ROOT and CLAUDE_PLUGIN_DATA in its environment, plus CLAUDE_PLUGIN_OPTION_<KEY> for each user configuration value, so your script can read them from there
Quoting: when command has no args, it runs through a shell, so wrap the ${CLAUDE_PLUGIN_ROOT} path in double quotes, as the hooks/hooks.json example under Hooks does, to keep the expanded path one shell word. When you pass args instead, each element is passed as one argument with no shell and needs no quoting. See exec form and shell form
Matching the plugin's own MCP tools: a tool from an MCP server this plugin declares is named mcp__plugin_<plugin>_<server>__<tool>, so write that full name in the matcher. A matcher on the server name alone never fires. See Match MCP tools
MCP servers
An MCP server gives Claude tools from an external system. Declare it in .mcp.json at the plugin root, in the same shape as a project .mcp.json. This .mcp.json declares one server named db:
You can also omit the mcpServers wrapper and put db at the top level of the file.
Load the plugin and run /mcp to confirm the server appears as plugin:my-plugin:db.
claude plugin validate checks .mcp.json and reports a server entry that Claude Code would drop at load time as an error. Requires Claude Code v2.1.281 or later.
The mcpServers manifest key takes an inline server map, a path to a JSON file, or an array of those. When a manifest server has the same name as one in .mcp.json, the manifest server replaces it.
Reach users on claude.ai and Cowork
A local stdio server, such as the db server under MCP servers, runs in Claude Code and in a Cowork session that runs on your machine in the Claude Desktop app, but not on claude.ai. To reach users there too, reference a remote server by its https:// URL, which claude.ai and Cowork offer to the user as a connector, as Bundle an MCP connector with its skill shows.
Server names, tool names, and reloads
The server's names, variable substitution, and reload behavior follow these rules:
Server name: plugin:<plugin>:<server>, so the db server in my-plugin is plugin:my-plugin:db in /mcp. Use the same form to name the server in an mcp_tool hook
Tool names: mcp__plugin_<plugin>_<server>__<tool>, so a query tool on that db server is mcp__plugin_my-plugin_db__query. That is the name to use in permission rules and hook matchers
Substitution: ${CLAUDE_PLUGIN_ROOT} and the other path variables are substituted in command, args, and env. No quoting is needed in args, because each element is passed as one argument
Reload: when the user runs /reload-plugins and the reload applies, a server whose configuration is unchanged keeps its connection. A server whose configuration changed reconnects, and one you removed disconnects
Include a packaged MCPB server
The mcpServers key also accepts a packaged server as an MCPB file, whose extension is .mcpb or the older .dxt. Point the key at the file, as a path inside the plugin or an https:// URL:
An LSP server gives Claude diagnostics and code navigation for a language. If an official code intelligence plugin already covers your language, install that instead of writing one. Otherwise declare the server in .lsp.json at the plugin root:
The file maps each server name directly to its configuration, with no wrapper object around the map. command is the binary's name, with its arguments in args. extensionToLanguage needs at least one extension, each starting with ..
claude plugin validate doesn't read this file. When any entry is invalid, the whole file is skipped at load and Invalid LSP server config for ".lsp.json" appears in the /pluginErrors tab.
Your plugin configures the connection but doesn't install the server binary, and each file extension gets one server:
Missing binary: Claude Code starts command by name from the user's PATH. When the binary isn't there, the server fails to start and claude --debug logs LSP server <name> failed to start
Extension conflicts: when two enabled servers claim the same extension, the first registered handles those files and the other isn't used for them, whether the servers come from one plugin or two. The /pluginErrors tab shows the warning LSP server "<name>" is not used for <ext> files
The lspServers manifest key takes the same map inline, a path to a JSON file, or an array of those, and its servers add to the ones in .lsp.json. When a manifest server has the same name as one in .lsp.json, the manifest server replaces it.
For transport, timeouts, restarts, and the other fields, see lspServers.
Send log output to stderr, not stdout. Claude Code reads a server's stdout as protocol messages only, and accepts message headers up to 64 KiB and a message body up to 32 MiB.
Claude Code disconnects a server that exceeds either limit or writes non-protocol output to stdout, and counts the disconnect as a crash for restartOnCrash and maxRestarts. When you run with --debug, Claude Code writes an error naming the cause to the debug log.
Executables
Files in bin/ at the plugin root are on the PATH of the Bash tool's shell while the plugin is enabled, so Claude can run them as bare commands. Add an executable script:
#!/bin/bashecho"hello from my-plugin"
Make it executable with chmod +x bin/hello-plugin and load the plugin. When you ask Claude to run hello-plugin, the Bash tool result shows the script's output.
Plugin bin/ directories come after the user's own PATH entries, so a plugin can't shadow git, ls, or another system command.
To set defaults that apply while the plugin is enabled, add a settings.json at the plugin root, or put the same object inline in the settings manifest key. Two keys take effect, agent and subagentStatusLine, and every other key is dropped.
Set agent to run one of the plugin's own agents as the main thread:
{"agent": "security-reviewer"}
Load the plugin and start a session. Claude then answers in the main conversation with the security-reviewer agent's system prompt and model.
For everything the key controls, see the agent setting.
When the same key is set in more than one place, these rules decide which value applies:
File over manifest: when both exist and settings.json sets at least one supported key, settings.json applies and the manifest's settings is ignored
User settings over plugin defaults: across settings sources, plugin defaults are the lowest layer, so a user's own agent in ~/.claude/settings.json overrides yours
Two plugins set the same key: the value from the plugin loaded last applies, and claude --debug logs overrides setting
A plugin can include color themes and output styles. Both appear in the same pickers as the user's own. For either one, setting the manifest key replaces the folder scan.
A channel lets an outside system such as a chat app send messages into a session. In a plugin, a channel is one of the MCP servers plus a channels entry that binds to it and can prompt for its own configuration. This manifest binds a channel to a telegram server and asks for a bot token:
server must match a key in mcpServers. The per-channel userConfig takes the same shape as the top-level userConfig key.
For what the server must implement and how users enable a channel plugin, see Package as a plugin in the channels reference. For the field table, see channels.
Monitors
A monitor is a shell command that runs in the background for the whole session. What it prints reaches Claude as notifications, so Claude can react to a log or a status change without being asked to watch it. Save the entries in monitors/monitors.json:
The command runs in a shell, in the working directory the session started in.
A monitor's command is limited in where it starts and what it can reference:
Interactive sessions only: plugin monitors start in an interactive session and never in non-interactive mode with the -p flag. They also start only where the Monitor tool is available
No user configuration: command gets the path variables and ${ENV_VAR} from the environment, but never ${user_config.*}. A monitor that references one doesn't start, and monitor processes don't receive CLAUDE_PLUGIN_OPTION_<KEY> either
Disabling mid-session: if you disable a plugin mid-session, Claude Code doesn't stop monitors that are already running. They stop when the session ends
The experimental.monitors manifest key takes the same array inline or a path to a JSON file, and is read instead of monitors/monitors.json.
For the when trigger and the other fields, see monitors.
Ask the user for configuration values
Declare the values your plugin needs from the user in the userConfig manifest key, so users don't edit settings.json themselves. Each option appears in a dialog with its title as the label and its description beneath it.
Set "sensitive": true for a token or password. The dialog then masks the input, and the value is stored in secure storage rather than settings.json.
This manifest asks for an endpoint and a token:
{"name": "my-plugin",
"userConfig": {"api_url": {"type": "string",
"title": "API URL",
"description": "Base URL of your team's API"},
"api_token": {"type": "string",
"title": "API token",
"description": "Token for your team's API",
"sensitive": true
}}}
When the configuration dialog appears
The dialog appears only in the interactive /plugin interface. It opens for any option that isn't set yet when the user does any of the following:
Installs the plugin in /plugin
Runs /plugin install <plugin>@<marketplace> inside a session
Enables the plugin from the Installed tab in /plugin
To open the same dialog at any time, the user runs /plugin configure <plugin>@<marketplace>.
The claude plugin install shell command never prompts for userConfig values. To set values from the shell, pass each one as --config KEY=VALUE. When options remain unset, the command prints a userConfig options not yet set line that names both ways to set them. The userConfig dialog never appears quotes the line.
For the option fields, where each value is stored, how a component references a saved value, and which fields reject ${user_config.*}, see User configuration.
Reference plugin paths and store data
You don't know where your plugin will be installed, so refer to its files and data through these variables rather than fixed paths. They're substituted in skill, command, and agent content, in hook and monitor commands, and in MCP and LSP server configurations. They're also exported to hook, MCP, and LSP processes:
${CLAUDE_PLUGIN_ROOT}: the plugin's install directory. Each version has its own cache directory, so the path changes when the plugin updates. Don't write state there
${CLAUDE_PLUGIN_DATA}: a directory that survives updates, for node_modules, virtual environments, and caches. It resolves to ~/.claude/plugins/data/<id>/ and is created when first referenced
${CLAUDE_PROJECT_DIR}: the project root, the same value hooks receive
In the data directory path, <id> is the plugin identifier with every character other than letters, digits, _, and - replaced by -, so my-plugin@my-marketplace becomes my-plugin-my-marketplace.
On Windows, the substituted paths use forward slashes so a shell doesn't read backslashes as escapes.
Install dependencies into the data directory
For a marketplace-installed plugin, Claude Code installs eligible Node.js package dependencies automatically when it caches the plugin, so you may not need to install them yourself. When you do, this SessionStart hook installs node_modules into ${CLAUDE_PLUGIN_DATA} on first run and again after an update changes package.json:
After the first session, ~/.claude/plugins/data/<id>/node_modules exists. An MCP server can then set NODE_PATH to ${CLAUDE_PLUGIN_DATA}/node_modules in its env. For which fields substitute which variable, see Environment variables.
Troubleshoot plugins: what to do when a component doesn't load or a hook doesn't fire
plugins/components.md+1−1
915A plugin can include color themes and output styles. Both appear in the same pickers as the user's own. For either one, setting the manifest key replaces the folder scan.915A plugin can include color themes and output styles. Both appear in the same pickers as the user's own. For either one, setting the manifest key replaces the folder scan.
916916
917| Component | Save as | Format | Appears in | Manifest key |917| Component | Save as | Format | Appears in | Manifest key |
919| Theme | `themes/<slug>.json` | The [custom theme file](/docs/en/terminal-config#create-a-custom-theme) format users write in `~/.claude/themes/` | `/theme`, under the file's `name` | `experimental.themes` |919| Theme | `themes/<slug>.json` | The [custom theme file](/docs/en/terminal-config#create-a-custom-theme) format users write in `~/.claude/themes/` | `/theme`, under the file's `name` | `experimental.themes` |
920| Output style | `output-styles/<name>.md` | The [custom output style](/docs/en/output-styles#create-a-custom-output-style) format, with `name` and `description` frontmatter | `/output-style`, as `<plugin>:<name>` | `outputStyles` |920| Output style | `output-styles/<name>.md` | The [custom output style](/docs/en/output-styles#create-a-custom-output-style) format, with `name` and `description` frontmatter | `/output-style`, as `<plugin>:<name>` | `outputStyles` |