Claude Code官方文档插件参考

Claude Code 插件参考手册 - 完整 Schema / CLI 命令 / 组件规范

Claude Code 插件系统的完整技术参考，包括组件架构、CLI 命令、插件清单架构、目录结构和开发工具。

发布于 2025年5月1日 · 阅读约 30 分钟

💡 想要安装插件？请参阅发现和安装插件。如需创建插件，请参阅 Plugins。如需分发插件，请参阅 Plugin marketplaces。

本参考提供了 Claude Code 插件系统的完整技术规范，包括组件架构、CLI 命令和开发工具。

plugin 是一个自包含的组件目录，用于扩展 Claude Code 的自定义功能。插件组件包括 skills、agents、hooks、MCP servers、LSP servers 和 monitors。

Plugin 组件参考

Skills

Plugins 向 Claude Code 添加 skills，创建可由您或 Claude 调用的 /name 快捷方式。

位置：插件根目录中的 skills/ 或 commands/ 目录

文件格式：Skills 是包含 SKILL.md 的目录；commands 是简单的 markdown 文件

Skill 结构：

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

集成行为：

安装插件时会自动发现 Skills 和 commands
Claude 可以根据任务上下文自动调用它们
Skills 可以在 SKILL.md 旁边包含支持文件

有关完整详情，请参阅 Skills。

Agents

Plugins 可以为特定任务提供专门的 subagents，Claude 可以在适当时自动调用。

位置：插件根目录中的 agents/ 目录

Agent 结构：

---
name: agent-name
description: 该 agent 的专长以及 Claude 应何时调用它
model: sonnet
effort: medium
maxTurns: 20
disallowedTools: Write, Edit
---

详细的系统提示，描述 agent 的角色、专业知识和行为。

Plugin agents 支持 name、description、model、effort、maxTurns、tools、disallowedTools、skills、memory、background 和 isolation frontmatter 字段。唯一有效的 isolation 值是 "worktree"。出于安全原因，plugin 提供的 agents 不支持 hooks、mcpServers 和 permissionMode。

集成点：

Agents 出现在 /agents 界面中
Claude 可以根据任务上下文自动调用 agents
Agents 可以由用户手动调用
Plugin agents 与内置 Claude agents 一起工作

有关完整详情，请参阅 Subagents。

Hooks

Plugins 可以提供事件处理程序，自动响应 Claude Code 事件。

位置：插件根目录中的 hooks/hooks.json，或在 plugin.json 中内联

Hook 配置：

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

Plugin hooks 响应与用户定义的 hooks相同的生命周期事件（SessionStart、PreToolUse、PostToolUse、Stop 等）。

Hook 类型：

command：执行 shell 命令或脚本
http：将事件 JSON 作为 POST 请求发送到 URL
mcp_tool：在配置的 MCP server 上调用工具
prompt：使用 LLM 评估提示（使用 $ARGUMENTS 占位符表示上下文）
agent：运行具有工具的 agentic 验证器以完成复杂验证任务

MCP servers

Plugins 可以捆绑 Model Context Protocol (MCP) servers 以将 Claude Code 与外部工具和服务连接。

位置：插件根目录中的 .mcp.json，或在 plugin.json 中内联

MCP server 配置：

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

集成行为：

启用插件时，Plugin MCP servers 会自动启动
Servers 在 Claude 的工具包中显示为标准 MCP 工具
Server 功能与 Claude 的现有工具无缝集成
Plugin servers 可以独立于用户 MCP servers 进行配置

LSP servers

💡 想要使用 LSP plugins？从官方市场安装它们：在 /plugin Discover 选项卡中搜索”lsp”。本部分记录了如何为官方市场未涵盖的语言创建 LSP plugins。

Plugins 可以提供 Language Server Protocol (LSP) servers，在处理代码库时为 Claude 提供实时代码智能。

LSP 集成提供：

即时诊断：Claude 在每次编辑后立即看到错误和警告
代码导航：转到定义、查找引用和悬停信息
语言感知：代码符号的类型信息和文档

位置：插件根目录中的 .lsp.json，或在 plugin.json 中内联

.lsp.json 文件格式：

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

必需字段：

字段	描述
`command`	要执行的 LSP 二进制文件（必须在 PATH 中）
`extensionToLanguage`	将文件扩展名映射到语言标识符

可选字段：

字段	描述
`args`	LSP server 的命令行参数
`transport`	通信传输：`stdio`（默认）或 `socket`
`env`	启动 server 时要设置的环境变量
`initializationOptions`	在初始化期间传递给 server 的选项
`settings`	通过 `workspace/didChangeConfiguration` 传递的设置
`workspaceFolder`	server 的工作区文件夹路径
`startupTimeout`	等待 server 启动的最长时间（毫秒）
`shutdownTimeout`	等待正常关闭的最长时间（毫秒）
`restartOnCrash`	server 崩溃时是否自动重启
`maxRestarts`	放弃前的最大重启尝试次数

⚠️ 您必须单独安装语言服务器二进制文件。 LSP plugins 配置 Claude Code 如何连接到语言服务器，但它们不包括服务器本身。

可用的 LSP plugins：

Plugin	语言服务器	安装命令
`pyright-lsp`	Pyright (Python)	`pip install pyright` 或 `npm install -g pyright`
`typescript-lsp`	TypeScript Language Server	`npm install -g typescript-language-server typescript`
`rust-analyzer-lsp`	rust-analyzer	参阅 rust-analyzer 安装

Monitors

Plugins 可以声明后台 monitors，Claude Code 在 plugin 激活时自动启动。每个 monitor 为会话的生命周期运行一个 shell 命令，并将每个 stdout 行作为通知传递给 Claude。

ℹ️ Plugin monitors 需要 Claude Code v2.1.105 或更高版本。

位置：插件根目录中的 monitors/monitors.json，或在 plugin.json 中内联

格式：监视器条目的 JSON 数组

[
  {
    "name": "deploy-status",
    "command": "${CLAUDE_PLUGIN_ROOT}/scripts/poll-deploy.sh ${user_config.api_endpoint}",
    "description": "Deployment status changes"
  },
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log",
    "when": "on-skill-invoke:debug"
  }
]

必需字段：

字段	描述
`name`	在插件中唯一的标识符
`command`	在会话工作目录中作为持久后台进程运行的 shell 命令
`description`	正在监视的内容的简短摘要

可选字段：

字段	描述
`when`	控制 monitor 何时启动。`"always"` 在会话启动和插件重新加载时启动它，这是默认值。`"on-skill-invoke:<skill-name>"` 在此插件中的命名 skill 首次被分派时启动它

Themes

Plugins 可以提供颜色主题，这些主题与内置预设和用户的本地主题一起出现在 /theme 中。主题是 themes/ 中的 JSON 文件，具有 base 预设和稀疏的 overrides 颜色令牌映射。

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

Plugin 安装范围

安装 plugin 时，您选择一个范围，确定 plugin 的可用位置以及谁可以使用它：

范围	设置文件	用例
`user`	`~/.claude/settings.json`	在所有项目中可用的个人 plugins（默认）
`project`	`.claude/settings.json`	通过版本控制共享的团队 plugins
`local`	`.claude/settings.local.json`	项目特定的 plugins，gitignored
`managed`	托管设置	托管 plugins（只读，仅更新）

Plugin 清单架构

.claude-plugin/plugin.json 文件定义了您的 plugin 的元数据和配置。

清单是可选的。如果省略，Claude Code 会自动发现默认位置中的组件，并从目录名称派生 plugin 名称。当您需要提供元数据或自定义组件路径时，使用清单。

完整架构

{
  "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"],
  "skills": "./custom/skills/",
  "commands": ["./custom/commands/special.md"],
  "agents": ["./custom/agents/reviewer.md"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./monitors.json"
  },
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

必需字段

如果包含清单，name 是唯一必需的字段。

字段	类型	描述	示例
`name`	string	唯一标识符（kebab-case，无空格）	`"deployment-tools"`

元数据字段

字段	类型	描述
`$schema`	string	用于编辑器自动完成和验证的 JSON Schema URL
`version`	string	可选。语义版本。设置此项会将 plugin 固定到该版本字符串
`description`	string	plugin 目的的简要说明
`author`	object	作者信息
`homepage`	string	文档 URL
`repository`	string	源代码 URL
`license`	string	许可证标识符
`keywords`	array	发现标签

组件路径字段

字段	类型	描述
`skills`	string\|array	包含 `<name>/SKILL.md` 的自定义 skill 目录
`commands`	string\|array	自定义平面 `.md` skill 文件或目录
`agents`	string\|array	自定义 agent 文件
`hooks`	string\|array\|object	Hook 配置路径或内联配置
`mcpServers`	string\|array\|object	MCP 配置路径或内联配置
`outputStyles`	string\|array	自定义输出样式文件/目录
`lspServers`	string\|array\|object	LSP 配置用于代码智能
`experimental.themes`	string\|array	颜色主题文件/目录
`experimental.monitors`	string\|array	后台 Monitor 配置
`userConfig`	object	用户可配置的值，在启用时提示
`channels`	array	消息注入的频道声明
`dependencies`	array	此 plugin 需要的其他 plugins

用户配置

userConfig 字段声明了 Claude Code 在启用 plugin 时提示用户的值。使用此字段而不是要求用户手动编辑 settings.json。

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

每个选项支持这些字段：

字段	必需	描述
`type`	是	以下之一：`string`、`number`、`boolean`、`directory` 或 `file`
`title`	是	在配置对话框中显示的标签
`description`	是	显示在字段下方的帮助文本
`sensitive`	否	如果为 `true`，掩盖输入并将值存储在安全存储中而不是 `settings.json`
`required`	否	如果为 `true`，当字段为空时验证失败
`default`	否	用户未提供任何内容时使用的值
`multiple`	否	对于 `string` 类型，允许字符串数组
`min` / `max`	否	`number` 类型的边界

路径行为规则

自定义路径是否替换或扩展 plugin 的默认目录取决于该字段：

替换默认值：commands、agents、outputStyles、experimental.themes、experimental.monitors
添加到默认值：skills
自己的合并规则：hooks、MCP servers 和 LSP servers

对于所有路径字段：

所有路径必须相对于 plugin 根目录，并以 ./ 开头
来自自定义路径的组件使用相同的命名和命名空间规则
可以将多个路径指定为数组

环境变量

Claude Code 提供两个变量用于引用 plugin 路径：

${CLAUDE_PLUGIN_ROOT}：plugin 安装目录的绝对路径。使用此路径引用与 plugin 捆绑的脚本、二进制文件和配置文件。当 plugin 更新时，此路径会更改。

${CLAUDE_PLUGIN_DATA}：用于 plugin 状态的持久目录，在更新后保留。使用此目录用于已安装的依赖项，如 node_modules 或 Python 虚拟环境、生成的代码、缓存以及任何应在 plugin 版本之间保留的其他文件。

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

持久数据目录

${CLAUDE_PLUGIN_DATA} 目录解析为 ~/.claude/plugins/data/{id}/，其中 {id} 是 plugin 标识符。对于安装为 formatter@my-marketplace 的 plugin，目录是 ~/.claude/plugins/data/formatter-my-marketplace/。

Plugin 缓存和文件解析

Plugins 通过以下两种方式之一指定：

通过 claude --plugin-dir 或 claude --plugin-url，用于会话期间。
通过市场，为将来的会话安装。

出于安全和验证目的，Claude Code 将市场 plugins 复制到用户的本地 plugin 缓存（~/.claude/plugins/cache），而不是就地使用它们。

路径遍历限制

已安装的 plugins 无法引用其目录外的文件。遍历 plugin 根目录外的路径（例如 ../shared-utils）在安装后将不起作用。

使用外部依赖

如果您的 plugin 需要访问其目录外的文件，您可以在 plugin 目录中创建指向外部文件的符号链接：

ln -s /path/to/shared-utils ./shared-utils

Plugin 目录结构

标准 plugin 布局

完整的 plugin 遵循此结构：

enterprise-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── commands/
│   ├── status.md
│   └── logs.md
├── agents/
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── output-styles/
│   └── terse.md
├── themes/
│   └── dracula.json
├── monitors/
│   └── monitors.json
├── hooks/
│   ├── hooks.json
│   └── security-hooks.json
├── bin/
│   └── my-tool
├── settings.json
├── .mcp.json
├── .lsp.json
├── scripts/
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE
└── CHANGELOG.md

⚠️ .claude-plugin/ 目录包含 plugin.json 文件。所有其他目录（commands/、agents/、skills/、output-styles/、themes/、monitors/、hooks/）必须在 plugin 根目录，而不是在 .claude-plugin/ 内。

CLI 命令参考

Claude Code 提供了用于非交互式 plugin 管理的 CLI 命令。

plugin install

从可用市场安装 plugin。

claude plugin install <plugin> [options]

选项：

选项	描述	默认值
`-s, --scope <scope>`	安装范围：`user`、`project` 或 `local`	`user`

示例：

# 安装到用户范围（默认）
claude plugin install formatter@my-marketplace

# 安装到项目范围（与团队共享）
claude plugin install formatter@my-marketplace --scope project

# 安装到本地范围（gitignored）
claude plugin install formatter@my-marketplace --scope local

plugin uninstall

删除已安装的 plugin。

claude plugin uninstall <plugin> [options]

选项：

选项	描述	默认值
`-s, --scope <scope>`	从范围卸载：`user`、`project` 或 `local`	`user`
`--keep-data`	保留插件的持久数据目录
`--prune`	同时删除其他 plugin 不需要的自动安装依赖项
`-y, --yes`	跳过 `--prune` 确认提示

别名： remove、rm

plugin prune

删除不再被任何已安装 plugin 需要的自动安装 plugin 依赖项。

claude plugin prune [options]

别名： autoremove

ℹ️ claude plugin prune 需要 Claude Code v2.1.121 或更高版本。

plugin enable

启用已禁用的 plugin。

claude plugin enable <plugin> [options]

plugin disable

禁用 plugin 而不卸载它。

claude plugin disable <plugin> [options]

plugin update

将 plugin 更新到最新版本。

claude plugin update <plugin> [options]

plugin list

列出已安装的 plugins 及其版本、源市场和启用状态。

claude plugin list [options]

选项：

选项	描述	默认值
`--json`	输出为 JSON
`--available`	包括来自市场的可用 plugins。需要 `--json`

plugin tag

为当前目录中的 plugin 创建发布 git 标签。

claude plugin tag [options]

选项：

选项	描述	默认值
`--push`	创建标签后将其推送到远程
`--dry-run`	打印将被标记的内容而不创建标签
`-f, --force`	即使工作树是脏的或标签已存在，也创建标签

调试和开发工具

调试命令

使用 claude --debug 查看 plugin 加载详情。

这显示：

正在加载哪些 plugins
plugin 清单中的任何错误
Skill、agent 和 hook 注册
MCP server 初始化

常见问题

问题	原因	解决方案
Plugin 未加载	无效的 `plugin.json`	运行 `claude plugin validate` 或 `/plugin validate` 检查 `plugin.json`、skill/agent/command frontmatter 和 `hooks/hooks.json` 的语法和架构错误
Skills 未出现	目录结构错误	确保 `skills/` 或 `commands/` 在根目录，而不是在 `.claude-plugin/` 中
Hooks 未触发	脚本不可执行	运行 `chmod +x script.sh`
MCP server 失败	缺少 `${CLAUDE_PLUGIN_ROOT}`	对所有 plugin 路径使用变量
路径错误	使用了绝对路径	所有路径必须是相对的，并以 `./` 开头
LSP `Executable not found in $PATH`	语言服务器未安装	安装二进制文件

示例错误消息

清单验证错误：

Invalid JSON syntax: Unexpected token } in JSON at position 142：检查缺少的逗号、多余的逗号或未引用的字符串
Plugin has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Required：缺少必需字段
Plugin has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...：JSON 语法错误

Hook 故障排除

Hook 脚本未执行：

检查脚本是否可执行：chmod +x ./scripts/your-script.sh
验证 shebang 行：第一行应该是 #!/bin/bash 或 #!/usr/bin/env bash
检查路径是否使用 ${CLAUDE_PLUGIN_ROOT}："command": "${CLAUDE_PLUGIN_ROOT}/scripts/your-script.sh"
手动测试脚本：./scripts/your-script.sh

MCP server 故障排除

Server 未启动：

检查命令是否存在且可执行
验证所有路径是否使用 ${CLAUDE_PLUGIN_ROOT} 变量
检查 MCP server 日志：claude --debug 显示初始化错误
在 Claude Code 外手动测试 server

目录结构错误

症状：Plugin 加载但组件（skills、agents、hooks）缺失。

正确结构：组件必须在 plugin 根目录，而不是在 .claude-plugin/ 内。只有 plugin.json 属于 .claude-plugin/。

my-plugin/
├── .claude-plugin/
│   └── plugin.json      ← 仅清单在此处
├── commands/            ← 在根级别
├── agents/              ← 在根级别
└── hooks/               ← 在根级别

分发和版本管理参考

版本管理

Claude Code 使用 plugin 的版本作为缓存键，以确定是否有可用的更新。

版本从以下第一个设置的字段解析：

plugin 的 plugin.json 中的 version 字段
plugin 的 marketplace.json 中的市场条目中的 version 字段
plugin 源的 git 提交 SHA，用于 git 托管市场中的 github、url、git-subdir 和相对路径源
unknown，用于 npm 源或不在 git 仓库内的本地目录

这为你提供了两种方式来对 plugin 进行版本管理：

方法	如何操作	更新行为	最适合
显式版本	在 `plugin.json` 中设置 `"version": "2.1.0"`	用户仅在你提升此字段时获得更新。	具有稳定发布周期的已发布 plugin
提交 SHA 版本	从 `plugin.json` 和市场条目中省略 `version`	用户在每次对 plugin 的 git 源进行新提交时获得更新	正在积极开发的内部或团队 plugin

⚠️ 如果你在 plugin.json 中设置 version，你必须在每次想让用户接收更改时提升它。

如果你使用显式版本，请遵循语义版本控制（MAJOR.MINOR.PATCH）。

另请参阅

Plugins - 教程和实际用法
Plugin marketplaces - 创建和管理市场
Skills - Skill 开发详情
Subagents - Agent 配置和功能
Hooks - 事件处理和自动化
MCP - 外部工具集成

本文翻译自 Anthropic Claude Code 官方文档，最近一次同步：2025-05-01。