Plugins Reference

Plugins Reference

Complete technical reference for the Claude Code plugin system, including schemas, CLI commands, and component specifications.

Tip: For hands-on tutorials and practical usage, see Plugins. For plugin management across teams and communities, see Plugin marketplaces.

Plugin Components Reference

This section documents the five types of components that plugins can provide:

Commands

Plugins add custom slash commands that integrate with Claude Code's command system. Location: commands/ directory in plugin root File format: Markdown files with frontmatter

• For details on command structure, invocation patterns, and features, see Plugin commands.

Agents

Plugins can provide specialized subagents for specific tasks that Claude can invoke automatically. Location: agents/ directory in plugin root File format: Markdown files describing agent capabilities

Agent Structure Example:

---
description: What this agent specializes in
capabilities: ["task1", "task2", "task3"]
---
# Agent Name
Detailed description of the agent's role, expertise, and when Claude should invoke it.

## Capabilities
- Specific task the agent excels at
- Another specialized capability
- When to use this agent vs others

## Context and examples
Provide examples of when this agent should be used and what problems it solves.

Integration Points:

• Agents appear in the /agents interface
• Claude can invoke agents automatically based on context
• Agents can be manually invoked by users
• Plugin agents work alongside built-in Claude agents

Skills

Plugins can provide Agent Skills that extend Claude's capabilities. Skills are model-invoked—Claude autonomously decides when to use them.

Location: skills/ directory in plugin root File format: Directories containing SKILL.md files with frontmatter

Skill Structure Example:

skills/
  ├── pdf-processor/
  │   ├── SKILL.md
  │   ├── reference.md (optional)
  │   └── scripts/ (optional)
  └── code-reviewer/
      └── SKILL.md

Integration Behavior:

• Plugin Skills are detected when the plugin is installed
• Claude invokes Skills based on context
• Skills can include supporting files

For SKILL.md format and authoring guidance, see:

• Use Skills in Claude Code
• Agent Skills overview

Hooks

Plugins can provide event handlers that respond to Claude Code events automatically.

Location: hooks/hooks.json in plugin root, or inline in plugin.json Format: JSON configuration with event matchers and actions

Hook Configuration Example:

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

Available Events:

• PreToolUse: Before tool use
• PostToolUse: After tool use
• UserPromptSubmit: When user submits prompt
• Notification: Claude Code notifications
• Stop: When Claude stops
• SubagentStop: Subagent attempts to stop
• SessionStart / SessionEnd
• PreCompact: Before history is compacted

Hook Types:

• command: Execute shell commands or scripts
• validation: Validate file/project state
• notification: Send alerts/status

MCP Servers

Plugins can bundle Model Context Protocol (MCP) servers to connect Claude Code with external tools.

Location: .mcp.json in plugin root or inline in plugin.json Format: Standard MCP server configuration

MCP Server Example:

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

Integration Behavior:

• MCP servers start automatically when enabled
• Servers appear as tools in Claude's toolkit
• Servers can be configured independently of user MCP servers

Plugin Manifest Schema

The plugin.json file defines plugin metadata and configuration.

Complete Schema Example

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "commands": ["./custom/commands/special.md"],
  "agents": "./custom/agents/",
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json"
}

Required Fields

Metadata Fields

Component Path Fields

Path Behavior Rules

Important: Custom paths supplement default directories – they do not replace them.

• If commands/ exists, it's loaded in addition to custom paths.
• All paths must be relative and start with ./.
• Multiple paths can be specified as arrays.

Example:

{
  "commands": ["./specialized/deploy.md", "./utilities/batch-process.md"],
  "agents": ["./custom-agents/reviewer.md", "./custom-agents/tester.md"]
}

Environment Variables

• ${CLAUDE_PLUGIN_ROOT} contains the absolute path to your plugin directory.

Example:

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/process.sh"
          }
        ]
      }
    ]
  }
}

Plugin Directory Structure

Standard Plugin Layout

A complete plugin example:

enterprise-plugin/
  ├── .claude-plugin/         # Metadata directory
  │   └── plugin.json         # Required manifest
  ├── commands/               # Default commands
  │   ├── status.md
  │   └── logs.md
  ├── agents/                 # Subagents
  │   ├── security-reviewer.md
  │   ├── performance-tester.md
  │   └── compliance-checker.md
  ├── skills/
  │   ├── code-reviewer/
  │   │   └── SKILL.md
  │   └── pdf-processor/
  │       ├── SKILL.md
  │       └── scripts/
  ├── hooks/
  │   ├── hooks.json
  │   └── security-hooks.json
  ├── .mcp.json
  ├── scripts/
  │   ├── security-scan.sh
  │   ├── format-code.py
  │   └── deploy.js
  ├── LICENSE
  └── CHANGELOG.md

Warning: .claude-plugin/ contains plugin.json. All other directories (commands/, agents/, skills/, hooks/) must be at the plugin root—not inside .claude-plugin/.

File Locations Reference

Debugging and Development Tools

Debugging Commands

To see plugin loading details, run:

claude --debug

This shows:

• Which plugins are loaded
• Plugin manifest errors
• Command/agent/hook registration
• MCP server initialization

Common Issues

Distribution and Versioning Reference

Version Management

Follow semantic versioning for plugin releases.

See Also

• Plugins – Tutorials and practical usage
• Plugin marketplaces – Marketplace management
• Slash commands – Command development
• Subagents – Agent configuration
• Agent Skills – Extend capabilities
• Hooks – Automation
• MCP – Tool integration
• Settings – Plugin configuration