Claude Code Plugin Reference Manual

Plugins are thecore of functional expansion, which can help you add custom slash commands, subagents, automation hooks, and other capabilities. This tutorial coverscore components、configuration specifications、CLI managementthree dimensions, to quickly help you master the key points of plugin usage and development.

---

Plugin Core Components: 5 Types of Extension Capabilities

Plugins achieve functional expansion through 5 types of components, each with fixed storage locations and format requirements.

Component Type	Storage Location	File Format	Core Function
Command	Plugin root directorycommands/	Markdown file with frontmatter metadata	Add custom slash commands, e.g.,/deploy /code-review
Agent	Plugin root directoryagents/	Markdown file	Provide dedicated subagents, such as code review agents, performance testing agents
Skill	Plugin root directoryskills/	containingSKILL.mddirectory	Allow Claude to automatically recognize scenarios and invoke them, e.g., PDF parsing, data visualization
Hook	Plugin root directoryhooks/hooks.jsonorplugin.jsonInline	JSON configuration file	Listen to Claude events and respond automatically, e.g., automatically format code after file editing
MCP server	Plugin root directory.mcp.jsonorplugin.jsonInline	JSON configuration file	Connect external tools (such as GitHub, Jira) and turn their features into tools usable by Claude
LSP server	Plugin root directory.lsp.jsonorplugin.jsonInline	JSON configuration file	Provide code intelligence capabilities, such as syntax checking, go-to definition, hover hints

Key Component Examples

1. Hook Configuration Example: Automatically format after file editing

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

}

: Support Go language intelligence hints

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

---

Plugin Basic Specifications: Installation Scope and Manifest

1. Installation Scope: Determines the Plugin's Availability Range

When installing a plugin, you need to choose a scope. Different scopes correspond to different configuration files and usage scenarios:

Scope	Configuration file path	Applicable scenario
user	~/.claude/settings.json	Personal, common to all projects (default)
project	.claude/settings.json	Team-shared, synchronized with the repository
local	.claude/settings.local.json	Project-specific, is.gitignoreignored
managed	managed-settings.json	Managed plugin, read-only and automatically updated

2. Plugin Manifest:plugin.jsonKey Points to Know

plugin.jsonis the plugin'score configuration file, stored in.claude-plugin/the directory, used to define plugin metadata and component paths.

a. Required Fields

Field	Type	Requirement	Example
name	string	Unique identifier, kebab-case format	"go-code-helper"

b. Core Metadata Fields

{
  "version": "1.0.0", // 语义化版本
  "description": "提供 Go 语言代码智能和调试能力",
  "author": {
    "name": "Dev Team",
    "email": "[email protected]"
  },
  "license": "MIT"
}

c. Component Path Fields

Used to specify the location of custom components. The path must berelative to the plugin root directoryand./start with:

{
  "commands": ["./custom-commands/deploy.md"],
  "agents": "./custom-agents/",
  "hooks": "./hooks.json"
}

d. Environment Variables

${CLAUDE_PLUGIN_ROOT}Absolute path of the plugin root directory, used to reference files within the plugin in scripts and configurations, avoiding path errors.

3. Standard Plugin Directory Structure

my-plugin/
├── .claude-plugin/           # 元数据目录
│   └── plugin.json          # 插件清单（必需）
├── commands/                 # 自定义斜杠命令
├── agents/                   # 子代理定义
├── skills/                   # 自动技能
├── hooks/                    # 事件钩子配置
├── .mcp.json                # MCP 服务器配置
├── .lsp.json                # LSP 服务器配置
└── scripts/                 # 钩子执行脚本

Note:commands/ agents/Component directories such as these must be in the pluginroot directoryand cannot be placed.claude-plugin/inside.

---

Plugin Management: CLI Command Quick Reference

Through the Claude Code CLI, you can quickly install, uninstall, enable/disable plugins, suitable for scripting and automation scenarios.

Command	Purpose	Example
claude plugin install <插件名> -s <范围>	Install plugin	claude plugin install go-lsp --scope project
claude plugin uninstall <插件名>	Uninstall plugin	claude plugin uninstall go-lsp
claude plugin enable <插件名>	Enable disabled plugin	claude plugin enable go-lsp
claude plugin disable <插件名>	Disable plugin (without uninstalling)	claude plugin disable go-lsp
claude plugin update <插件名>	Update plugin to the latest version	claude plugin update go-lsp

---

Debugging and Troubleshooting: Common Problem Solutions

1. Debugging Commands

Run the following command to view plugin loading details and locate configuration and loading issues:

claude --debug

You can view: plugin loading status, manifest syntax errors, component registration status, MCP/LSP server initialization logs.

2. Frequently Asked Issues and Solutions

Issue	Cause	Solution
Plugin not loaded	plugin.jsonSyntax error or missing required fields	useclaude plugin validateValidate JSON syntax, add the missingnamefield
Custom commands not displayed	Command file placed in.claude-plugin/inside	willcommands/Move the directory to the plugin root directory
Hook script not executing	Script does not have executable permission	Runchmod +x scripts/your-script.shto grant permission
LSP promptExecutable not found	Corresponding language server not installed	Install the binary file (e.g., Go requires installinggopls）
MCP server startup failed	Path uses absolute path, not using${CLAUDE_PLUGIN_ROOT}	Replace with environment variable reference, such as${CLAUDE_PLUGIN_ROOT}/server

---

Version Management and Distribution

• Version Specification: Follow Semantic VersioningMAJOR.MINOR.PATCH, for example1.2.3
• Distribution Channels: Distribute through the plugin marketplace, or directly share the plugin directory (must include the complete structure)
• Changelog: It is recommended to add in the plugin root directoryCHANGELOG.mdto record version update content

Other Extensions