Claude Code Plugins

What Are Claude Code Plugins?

Plugins are self-contained packages that extend Claude Code with custom functionality. A plugin can bundle any combination of:

• Skills — reusable instructions Claude can invoke automatically or users can call manually
• Agents — custom agent definitions with their own system prompts, tool restrictions, and models
• Hooks — shell commands that fire automatically before or after Claude Code actions
• MCP servers — connections to external tools and data sources via the Model Context Protocol
• LSP servers — language server integrations for real-time code intelligence
• Background monitors — processes that watch logs or files and notify Claude as events arrive
• Output styles and themes — response style and UI colour customisations
• Executables — binaries added to the Bash tool’s PATH while the plugin is active
• Default settings — configuration applied automatically when the plugin is enabled

Plugins are designed for sharing. Once packaged, teammates or the wider community can install them with a single /plugin install command via a marketplace.

Plugins vs Standalone Configuration

Claude Code supports two ways to add custom skills, agents, and hooks. Choosing between them depends on whether you need to share the configuration.

Use standalone configuration when:

• You are customising Claude Code for a single project
• The configuration is personal and does not need to be shared
• You are experimenting with skills or hooks before packaging them
• You want short, unnamespaced skill names like /hello or /deploy

Use plugins when:

• You want to share functionality with your team or the broader community
• You need the same skills or agents available across multiple projects
• You want version control and easy updates for your extensions
• You are distributing through a marketplace
• You are comfortable with namespaced skill names like /my-plugin:hello (namespacing prevents conflicts between plugins)

Recommended workflow: Start with standalone configuration in .claude/ for fast iteration, then convert to a plugin when you are ready to share.

Plugin Directory Structure

A plugin lives in its own directory. The .claude-plugin/plugin.json manifest is recommended for distributable plugins because it defines the plugin name, metadata, version, and optional component paths. Claude Code can also auto-discover components in default locations when the manifest is omitted.

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Plugin manifest (recommended)
├── skills/                  # Skills as <name>/SKILL.md directories
├── commands/                # Legacy flat Markdown skills (use skills/ for new plugins)
├── agents/                  # Custom agent definitions
├── output-styles/           # Custom output styles
├── themes/                  # Colour themes
├── hooks/
│   └── hooks.json           # Event handlers
├── monitors/
│   └── monitors.json        # Background monitor configurations
├── bin/                     # Executables added to Bash tool PATH
├── scripts/                 # Helper scripts used by skills, hooks, or monitors
├── .mcp.json                # MCP server configurations
├── .lsp.json                # LSP server configurations
└── settings.json            # Default settings applied when plugin is enabled

Common mistake: Do not put commands/, agents/, skills/, output-styles/, themes/, monitors/, or hooks/ inside the .claude-plugin/ directory. Only plugin.json goes inside .claude-plugin/. All other directories must be at the plugin root level.

A CLAUDE.md file at the plugin root is not loaded as project context. Plugins contribute context through skills, agents, hooks, MCP servers, LSP servers, monitors, and settings. If you want instructions to enter Claude’s context, put them in a skill or agent.

Quickstart: Creating Your First Plugin

Step 1 — Create the plugin directory

mkdir my-first-plugin

Step 2 — Create the plugin manifest

The manifest at .claude-plugin/plugin.json defines your plugin’s identity. Claude Code uses this metadata in the plugin manager. If you include a manifest, name is the only required field, but description and version are strongly recommended for shared plugins.

mkdir my-first-plugin/.claude-plugin

my-first-plugin/.claude-plugin/plugin.json:

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

Manifest metadata fields:

Manifest component path fields:

Path rules are easy to trip over:

• All custom paths in plugin.json should be relative to the plugin root and start with ./.
• skills extends the default skills/ directory.
• commands, agents, outputStyles, experimental.themes, and experimental.monitors replace their default directories unless you list the default path explicitly.
• Hooks, MCP servers, and LSP servers have their own merge behaviour because they can be declared as paths or inline objects.

Use userConfig when a plugin needs per-user settings such as API endpoints, tokens, directories, or feature flags:

{
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "API endpoint",
      "description": "Your team's API endpoint",
      "required": true
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "API authentication token",
      "sensitive": true
    }
  }
}

Configured values can be referenced as ${user_config.KEY} in MCP and LSP server configs, hook commands, and monitor commands. Non-sensitive values can also be substituted into skill and agent content.

Channels let a plugin declare message sources that inject content into the conversation, usually backed by a plugin-provided MCP server:

{
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        },
        "owner_id": {
          "type": "string",
          "title": "Owner ID",
          "description": "Your Telegram user ID"
        }
      }
    }
  ]
}

The server value must match a key in the plugin’s mcpServers. Channel-level userConfig uses the same schema as top-level userConfig.

Dependencies let one plugin require another:

{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

Use claude plugin tag --push when publishing versioned releases. For git-backed marketplaces, dependency constraints resolve against tags named {plugin-name}--v{version}.

Step 3 — Add a skill

Skills live in the skills/ directory. Each skill is a folder whose name becomes the skill name, prefixed by the plugin namespace.

mkdir -p my-first-plugin/skills/hello

my-first-plugin/skills/hello/SKILL.md:

---
description: Greet the user with a friendly message
disable-model-invocation: true
---

Greet the user warmly and ask how you can help them today.

Step 4 — Test your plugin locally

Use the --plugin-dir flag to load your plugin for a session without installing it:

claude --plugin-dir ./my-first-plugin

Then invoke your skill:

/my-first-plugin:hello

Run /help to see your skill listed under the plugin namespace. Run /reload-plugins after any changes to pick them up without restarting.

Step 5 — Add skill arguments

The $ARGUMENTS placeholder captures any text the user provides after the skill name, making skills dynamic:

---
description: Greet the user with a personalized message
---

Greet the user named "$ARGUMENTS" warmly and ask how you can help them today.

Usage:

/my-first-plugin:hello Alex

Plugin Components in Depth

Skills

By default, skills can be model-invoked: Claude can select and use them based on task context, without the user needing to invoke them manually. Each skill is a folder inside skills/ containing a SKILL.md file.

my-plugin/
└── skills/
    └── code-review/
        └── SKILL.md

A typical SKILL.md:

---
description: Reviews code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
---

When reviewing code, check for:

1. Code organisation and structure
2. Error handling
3. Security concerns
4. Test coverage

The description frontmatter field is what Claude reads to decide when to invoke the skill. Use disable-model-invocation: true for manual-only skills, especially workflows with side effects such as deploys or commits. Use user-invocable: false for background knowledge that Claude may use but users should not call from the slash menu.

Skill frontmatter fields:

After installing or reloading a plugin, run /reload-plugins to activate the skills.

For full skill authoring details including progressive disclosure and tool restrictions, see Extend Claude with skills.

Agents

Plugins can define custom subagents in the agents/ directory. Agents have their own system prompts, tool restrictions, and model selections. Claude can invoke them automatically when appropriate, and users can also select them from /agents.

Example agents/security-reviewer.md:

---
name: security-reviewer
description: Reviews code for security risks and unsafe patterns
model: sonnet
effort: medium
maxTurns: 20
disallowedTools: Write, Edit
---

Review code for security issues, risky dependencies, exposed secrets, and unsafe defaults.
Return findings with file references and concrete remediation steps.

Agent frontmatter fields:

For security reasons, plugin-shipped agents ignore hooks, mcpServers, and permissionMode. If you need those fields, copy the agent into .claude/agents/ or ~/.claude/agents/ instead of shipping it from a plugin.

You can set a default agent in the plugin’s settings.json:

{
  "agent": "security-reviewer"
}

This activates the security-reviewer agent as the main thread when the plugin is enabled. Settings in settings.json take priority over settings declared in plugin.json. Unknown keys are silently ignored.

Currently, only the agent and subagentStatusLine keys are supported in plugin settings.json.

Hooks

Hooks let you run shell commands automatically before or after Claude Code actions. Define them in hooks/hooks.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix"
          }
        ]
      }
    ]
  }
}

The hook command receives hook input as JSON on stdin. Use jq to extract fields like the file path. The format is the same as standalone hooks in settings.json, so existing hooks migrate directly.

Common hook events:

Hook handler types:

Hook handler fields:

Use hooks sparingly. They run with the user’s local privileges, so a shared plugin should make side effects clear and keep commands auditable.

MCP Servers

MCP (Model Context Protocol) server configurations go in .mcp.json at the plugin root, or inline in plugin.json under mcpServers. This connects Claude Code to external tools, APIs, and data sources — databases, GitHub, Slack, Jira, internal services and more — bundled as part of the plugin.

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_DATA}/db"
      }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

Plugin MCP servers start when the plugin is enabled and expose tools through Claude’s normal MCP tool system. They can use ${CLAUDE_PLUGIN_ROOT} for bundled files, ${CLAUDE_PLUGIN_DATA} for persistent state, ${CLAUDE_PROJECT_DIR} for project paths, and ${user_config.KEY} for values collected from the user.

Use MCP when the plugin needs a durable integration surface: API calls, database queries, browser automation, ticketing systems, internal tools, or reusable tool contracts. Use hooks when you only need to react to Claude Code lifecycle events.

LSP Servers

LSP (Language Server Protocol) plugins give Claude real-time code intelligence for a given language. Define them in .lsp.json:

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

LSP server fields:

For common languages (TypeScript, Python, Rust, and others), install the pre-built LSP plugins from the official marketplace instead of writing your own. Only create a custom LSP plugin when you need support for a language with no existing plugin. Users installing your LSP plugin must have the language server binary installed on their own machine.

Background Monitors

Background monitors watch logs, files, or external status in the background and notify Claude as events arrive. Claude Code starts each monitor automatically when the plugin is active — you do not need to instruct Claude to start watching.

Monitors require Claude Code v2.1.105 or later. They run only in interactive CLI sessions, run unsandboxed at the same trust level as hooks, and are skipped when the Monitor tool is unavailable.

Define monitors in monitors/monitors.json:

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

Each line written to stdout by command is delivered to Claude as a notification during the session. The full schema also supports a when trigger and variable substitution — see the plugins reference.

Monitor fields:

Monitor commands support ${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA}, ${CLAUDE_PROJECT_DIR}, ${user_config.KEY} and environment variable substitutions. If a monitor script must run from the plugin directory, start the command with cd "${CLAUDE_PLUGIN_ROOT}" && ....

Output Styles and Themes

Plugins can include output-styles/ and themes/ directories. Output styles customise how Claude responds, while themes customise the CLI appearance. These are useful when a team wants consistent review formats, concise operational responses, or a shared visual theme.

When declaring custom paths in plugin.json, note that commands, agents, outputStyles, themes, and monitors replace their default directories unless you list the default path explicitly. skills are different: custom skill paths are added alongside the default skills/ directory.

Example themes/dracula.json:

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

Plugin themes appear in /theme alongside built-in themes. They are read-only while installed from the plugin; users can copy them into their own theme directory if they want to customise them.

Output styles are best for response conventions, not capability. Use a skill or agent when the plugin needs task-specific instructions, tools, or routing logic.

Executables (bin/)

Any executables you place in the bin/ directory are added to the Bash tool’s PATH while the plugin is enabled. This lets you ship helper scripts or binaries that your hooks or skills depend on.

For example, a plugin can ship bin/check-release, then a skill or hook can call check-release directly. Keep executables self-contained, document required system dependencies, and prefer ${CLAUDE_PLUGIN_DATA} for caches or installed dependencies that should survive plugin updates.

Plugin Environment Variables

Claude Code provides useful variables for plugin components:

Quote these paths in shell commands because project and plugin paths may contain spaces.

When a plugin updates during a session, hooks, MCP servers and LSP servers keep using the previous plugin version until /reload-plugins runs. Monitors usually require a fresh session to switch to the new version. Treat ${CLAUDE_PLUGIN_ROOT} as read-only and versioned; write persistent state to ${CLAUDE_PLUGIN_DATA} instead.

Testing Plugins Locally

Load a local directory

claude --plugin-dir ./my-plugin

Load a zip archive (requires v2.1.128+)

claude --plugin-dir ./my-plugin.zip

Load from a URL

claude --plugin-url https://example.com/my-plugin.zip

Multiple plugins can be loaded at once:

claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two
claude --plugin-url "https://example.com/a.zip https://example.com/b.zip"

Precedence: When a --plugin-dir plugin has the same name as an installed marketplace plugin, the local copy takes precedence for that session. This lets you iterate on a plugin you already have installed without uninstalling it first.

Reloading: Run /reload-plugins after making changes to reload skills, agents, hooks, MCP servers, and LSP servers without restarting Claude Code.

Debugging

If a plugin is not working:

1. Check the structure — make sure commands/, agents/, skills/, and hooks/ are at the plugin root, not inside .claude-plugin/
2. Test components individually — check each skill, agent, and hook separately
3. Validate the plugin — run claude plugin validate ./my-plugin or use /plugin validate
4. Inspect what loaded — run claude plugin list and claude plugin details <name>
5. Use the CLI debugging tools — see Debugging and development tools

Useful plugin CLI commands:

Common failure modes:

Installation Scopes

When installing a plugin, choose a scope based on who should receive it:

Examples:

claude plugin install formatter@team-marketplace
claude plugin install formatter@team-marketplace --scope project
claude plugin update formatter
claude plugin uninstall formatter --keep-data

Converting Standalone Configuration to a Plugin

If you already have commands, skills, agents, or hooks in your project’s .claude/ directory, you can migrate them into a plugin.

Step 1 — Create the plugin structure

mkdir -p my-plugin/.claude-plugin

my-plugin/.claude-plugin/plugin.json:

{
  "name": "my-plugin",
  "description": "Migrated from standalone configuration",
  "version": "1.0.0"
}

Step 2 — Copy your existing files

cp -r .claude/commands my-plugin/
cp -r .claude/agents my-plugin/   # if any
cp -r .claude/skills my-plugin/   # if any

Step 3 — Migrate hooks

mkdir my-plugin/hooks

Copy the hooks object from your .claude/settings.json or settings.local.json into my-plugin/hooks/hooks.json. The format is identical.

Step 4 — Test the migrated plugin

claude --plugin-dir ./my-plugin

Test each component: run your skills, check agents appear in /agents, and verify hooks trigger correctly. After confirming everything works, remove the originals from .claude/ to avoid duplicates. The plugin version takes precedence when loaded.

What changes after migration

Sharing and Distribution

Prepare your plugin for release

1. Add a README.md with installation and usage instructions
2. Choose a versioning strategy:
   • Set an explicit version in plugin.json — users only receive updates when you bump the version
   • Omit version — if distributed via git, the commit SHA is used and every commit is treated as a new version
3. Create or use a marketplace for distribution
4. Have teammates test before a wider release

Marketplace file

A marketplace is a catalog of plugins. Put its manifest at .claude-plugin/marketplace.json in the marketplace repository:

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "devtools@example.com"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting on save",
      "version": "2.1.0"
    },
    {
      "name": "deployment-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "Deployment automation tools"
    }
  ]
}

Marketplace fields:

Plugin entry fields:

Plugin source types:

Users add a marketplace first, then install individual plugins:

claude plugin marketplace add acme-corp/claude-plugins
claude plugin marketplace list
claude plugin marketplace update
claude plugin install formatter@company-tools

Project teams can add known marketplaces and default plugins to .claude/settings.json so collaborators are prompted after trusting the repository:

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

Submit to the official Anthropic marketplace

• Claude.ai: claude.ai/settings/plugins/submit
• Console: platform.claude.com/plugins/submit

Once listed, you can prompt Claude Code users to install your plugin directly from your CLI. See Recommend your plugin from your CLI.

For internal team plugins, host a private marketplace in a private repository. See Plugin marketplaces.

Further Reading