Add components to a plugin

​

Explore the plugin directory

• 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

​

Add each kind of component

​

Skills

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── review/
        └── SKILL.md

---
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.

• 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
• Who invokes it: Claude, the user, or both, controlled by frontmatter. See Control who invokes a skill

• 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

​

Commands

​

Define commands in the manifest

{
  "name": "my-plugin",
  "commands": {
    "about": {
      "content": "Summarize what this repository does in three sentences.",
      "description": "Summarize the repository"
    }
  }
}

​

Agents

---
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.

​

Organize agents in subfolders

• 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

• 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

​

Hooks

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/format.sh\""
          }
        ]
      }
    ]
  }
}

​

When plugin hooks fire

​

Environment, quoting, and matching MCP tools

• 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

{
  "mcpServers": {
    "db": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  }
}

​

Reach users on claude.ai and Cowork

​

Server names, tool names, and reloads

• 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

{
  "name": "my-plugin",
  "mcpServers": "./servers/db.mcpb"
}

​

LSP servers

{
  "gopls": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

• 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 /plugin Errors tab shows the warning LSP server "<name>" is not used for <ext> files

​

Executables

#!/bin/bash
echo "hello from my-plugin"

​

Default settings

{
  "agent": "security-reviewer"
}

• 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

​

Themes and output styles

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555"
  }
}

​

Channels

{
  "name": "my-plugin",
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": { "BOT_TOKEN": "${user_config.bot_token}" }
    }
  },
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        }
      }
    }
  ]
}

​

Monitors

[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]

• 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

​

Ask the user for configuration values

{
  "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

• Installs the plugin in /plugin
• Runs /plugin install <plugin>@<marketplace> inside a session
• Enables the plugin from the Installed tab in /plugin

​

Reference plugin paths and store data

• ${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

​

Install dependencies into the data directory

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
          }
        ]
      }
    ]
  }
}

​

Next steps

• Plugin manifest reference: plugin.json fields, path rules, and the standard layout
• Test plugins with evals: check that the components you added change Claude’s behavior the way you intend
• Publish and distribute a plugin: version the plugin and put it in a marketplace
• Troubleshoot plugins: what to do when a component doesn’t load or a hook doesn’t fire