zhongwei/gh-obra-superpowers-developing-for-claude-code
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ac511e2e505eeffb417010af10ab41d725a266ff
gh-obra-superpowers-develop…/skills/working-with-claude-code/references/plugins-reference.md
Zhongwei Li ac511e2e50 Initial commit
2025-11-30 08:44:51 +08:00

13 KiB
Raw Blame History

Plugins reference

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

For hands-on tutorials and practical usage, see [Plugins](/en/docs/claude-code/plugins). For plugin management across teams and communities, see [Plugin marketplaces](/en/docs/claude-code/plugin-marketplaces).

This reference provides complete technical specifications for the Claude Code plugin system, including component schemas, CLI commands, and development tools.

Plugin components reference

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

Commands

Plugins add custom slash commands that integrate seamlessly with Claude Code's command system.

Location: commands/ directory in plugin root

File format: Markdown files with frontmatter

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

Agents

Plugins can provide specialized subagents for specific tasks that Claude can invoke automatically when appropriate.

Location: agents/ directory in plugin root

File format: Markdown files describing agent capabilities

Agent structure:

---
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 kinds of problems it solves.

Integration points:

  • Agents appear in the /agents interface
  • Claude can invoke agents automatically based on task context
  • Agents can be invoked manually 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 based on the task context.

Location: skills/ directory in plugin root

File format: Directories containing SKILL.md files with frontmatter

Skill structure:

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

Integration behavior:

  • Plugin Skills are automatically discovered when the plugin is installed
  • Claude autonomously invokes Skills based on matching task context
  • Skills can include supporting files alongside SKILL.md

For SKILL.md format and complete Skill authoring guidance, see:

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:

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

Available events:

  • PreToolUse: Before Claude uses any tool
  • PostToolUse: After Claude uses any tool
  • UserPromptSubmit: When user submits a prompt
  • Notification: When Claude Code sends notifications
  • Stop: When Claude attempts to stop
  • SubagentStop: When a subagent attempts to stop
  • SessionStart: At the beginning of sessions
  • SessionEnd: At the end of sessions
  • PreCompact: Before conversation history is compacted

Hook types:

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

MCP servers

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

Location: .mcp.json in plugin root, or inline in plugin.json

Format: Standard MCP server configuration

MCP server configuration:

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

  • Plugin MCP servers start automatically when the plugin is enabled
  • Servers appear as standard MCP tools in Claude's toolkit
  • Server capabilities integrate seamlessly with Claude's existing tools
  • Plugin servers can be configured independently of user MCP servers

Plugin manifest schema

The plugin.json file defines your plugin's metadata and configuration. This section documents all supported fields and options.

Complete schema

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

Field Type Description Example
name string Unique identifier (kebab-case, no spaces) "deployment-tools"

Metadata fields

Field Type Description Example
version string Semantic version "2.1.0"
description string Brief explanation of plugin purpose "Deployment automation tools"
author object Author information {"name": "Dev Team", "email": "dev@company.com"}
homepage string Documentation URL "https://docs.example.com"
repository string Source code URL "https://github.com/user/plugin"
license string License identifier "MIT", "Apache-2.0"
keywords array Discovery tags ["deployment", "ci-cd"]

Component path fields

Field Type Description Example
commands string|array Additional command files/directories "./custom/cmd.md" or ["./cmd1.md"]
agents string|array Additional agent files "./custom/agents/"
hooks string|object Hook config path or inline config "./hooks.json"
mcpServers string|object MCP config path or inline config "./mcp.json"

Path behavior rules

Important: Custom paths supplement default directories - they don't replace them.

  • If commands/ exists, it's loaded in addition to custom command paths
  • All paths must be relative to plugin root and start with ./
  • Commands from custom paths use the same naming and namespacing rules
  • Multiple paths can be specified as arrays for flexibility

Path examples:

{
  "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. Use this in hooks, MCP servers, and scripts to ensure correct paths regardless of installation location.

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

Plugin directory structure

Standard plugin layout

A complete plugin follows this structure:

enterprise-plugin/
├── .claude-plugin/           # Metadata directory
│   └── plugin.json          # Required: plugin manifest
├── commands/                 # Default command location
│   ├── status.md
│   └──  logs.md
├── agents/                   # Default agent location
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── skills/                   # Agent Skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── hooks/                    # Hook configurations
│   ├── hooks.json           # Main hook config
│   └── security-hooks.json  # Additional hooks
├── .mcp.json                # MCP server definitions
├── scripts/                 # Hook and utility scripts
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # License file
└── CHANGELOG.md             # Version history
The `.claude-plugin/` directory contains the `plugin.json` file. All other directories (commands/, agents/, skills/, hooks/) must be at the plugin root, not inside `.claude-plugin/`.

File locations reference

Component Default Location Purpose
Manifest .claude-plugin/plugin.json Required metadata file
Commands commands/ Slash command markdown files
Agents agents/ Subagent markdown files
Skills skills/ Agent Skills with SKILL.md files
Hooks hooks/hooks.json Hook configuration
MCP servers .mcp.json MCP server definitions

Debugging and development tools

Debugging commands

Use claude --debug to see plugin loading details:

claude --debug

This shows:

  • Which plugins are being loaded
  • Any errors in plugin manifests
  • Command, agent, and hook registration
  • MCP server initialization

Common issues

Issue Cause Solution
Plugin not loading Invalid plugin.json Validate JSON syntax
Commands not appearing Wrong directory structure Ensure commands/ at root, not in .claude-plugin/
Hooks not firing Script not executable Run chmod +x script.sh
MCP server fails Missing ${CLAUDE_PLUGIN_ROOT} Use variable for all plugin paths
Path errors Absolute paths used All paths must be relative and start with ./

Distribution and versioning reference

Version management

Follow semantic versioning for plugin releases:


## See also

- [Plugins](/en/docs/claude-code/plugins) - Tutorials and practical usage
- [Plugin marketplaces](/en/docs/claude-code/plugin-marketplaces) - Creating and managing marketplaces
- [Slash commands](/en/docs/claude-code/slash-commands) - Command development details
- [Subagents](/en/docs/claude-code/sub-agents) - Agent configuration and capabilities
- [Agent Skills](/en/docs/claude-code/skills) - Extend Claude's capabilities
- [Hooks](/en/docs/claude-code/hooks) - Event handling and automation
- [MCP](/en/docs/claude-code/mcp) - External tool integration
- [Settings](/en/docs/claude-code/settings) - Configuration options for plugins
Reference in New Issue View Git Blame Copy Permalink