插件技术参考

本文档提供 Claude Code 插件系统的完整技术规范，包括组件 Schema、CLI 命令和开发工具。

想安装插件？查看发现并安装插件。想创建插件？查看创建插件。想分发插件？查看插件市场。

插件是一个自包含的目录，包含扩展 Claude Code 的组件：技能、代理、钩子、MCP 服务器和 LSP 服务器。

插件组件参考

技能（Skills）

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

技能结构：

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

详情参见技能。

代理（Agents）

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

markdown

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

代理的详细系统提示。

支持的前置元数据字段：name、description、model、effort、maxTurns、tools、disallowedTools、skills、memory、background、isolation（仅支持 "worktree"）。

出于安全原因，插件代理不支持 hooks、mcpServers 和 permissionMode。

钩子（Hooks）

位置：hooks/hooks.json 或内联在 plugin.json 中

json

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

支持的事件列表（与用户定义的钩子相同）：

事件	触发时机
`SessionStart`	会话开始或恢复时
`UserPromptSubmit`	提交提示时，Claude 处理前
`PreToolUse`	工具调用执行前，可阻止
`PermissionRequest`	出现权限对话框时
`PostToolUse`	工具调用成功后
`PostToolUseFailure`	工具调用失败后
`Stop`	Claude 完成响应时
`InstructionsLoaded`	CLAUDE.md 或规则文件加载时
`SessionEnd`	会话终止时
`WorktreeCreate` / `WorktreeRemove`	Worktree 创建/删除时
`PreCompact` / `PostCompact`	上下文压缩前/后

钩子类型：command、http、prompt、agent

MCP 服务器

位置：.mcp.json 或内联在 plugin.json 中

json

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    }
  }
}

LSP 服务器

位置：.lsp.json 或内联在 plugin.json 中

json

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

必填字段：

字段	说明
`command`	要执行的 LSP 二进制文件
`extensionToLanguage`	文件扩展名到语言标识符的映射

可选字段：args、transport、env、initializationOptions、settings、startupTimeout、shutdownTimeout、restartOnCrash、maxRestarts

注意：必须单独安装语言服务器二进制文件。若在 /plugin 错误标签页看到 Executable not found in $PATH，请安装对应二进制文件。

插件安装作用域

作用域	设置文件	使用场景
`user`	`~/.claude/settings.json`	跨所有项目的个人插件（默认）
`project`	`.claude/settings.json`	通过版本控制共享的团队插件
`local`	`.claude/settings.local.json`	项目专属插件，已 gitignore
`managed`	管理设置	管理员安装的插件（只读）

插件清单 Schema

.claude-plugin/plugin.json 定义插件的元数据和配置。清单是可选的——如果省略，Claude Code 会从默认位置自动发现组件。

必填字段

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

元数据字段

字段	类型	说明
`version`	string	语义化版本
`description`	string	插件用途的简短说明
`author`	object	作者信息（`name`、`email`）
`homepage`	string	文档 URL
`repository`	string	源码 URL
`license`	string	许可证标识符
`keywords`	array	发现标签

组件路径字段

字段	类型	说明
`commands`	string\|array	额外的命令文件/目录
`agents`	string\|array	额外的代理文件
`skills`	string\|array	额外的技能目录
`hooks`	string\|array\|object	钩子配置路径或内联配置
`mcpServers`	string\|array\|object	MCP 配置路径或内联配置
`lspServers`	string\|array\|object	LSP 服务器配置

环境变量

Claude Code 提供两个用于引用插件路径的变量，在技能内容、代理内容、钩子命令以及 MCP/LSP 配置中均可使用：

${CLAUDE_PLUGIN_ROOT}：插件安装目录的绝对路径，用于引用插件捆绑的脚本、二进制文件和配置文件
${CLAUDE_PLUGIN_DATA}：插件跨更新持久化的数据目录，用于存储 node_modules 等依赖、生成的代码和缓存

持久数据目录

${CLAUDE_PLUGIN_DATA} 解析为 ~/.claude/plugins/data/{id}/，其中 {id} 是插件标识符（a-z、A-Z、0-9、_、- 以外的字符替换为 -）。

卸载插件时，数据目录会自动删除（除非使用 --keep-data）。

插件目录结构

标准插件布局：

enterprise-plugin/
├── .claude-plugin/           # 元数据目录（可选）
│   └── plugin.json           # 插件清单
├── commands/                 # 默认命令位置
├── agents/                   # 默认代理位置
├── skills/                   # 代理技能
│   └── code-reviewer/
│       └── SKILL.md
├── hooks/                    # 钩子配置
│   └── hooks.json
├── settings.json             # 插件的默认设置
├── .mcp.json                 # MCP 服务器定义
├── .lsp.json                 # LSP 服务器配置
└── scripts/                  # 钩子和工具脚本

警告：.claude-plugin/ 只包含 plugin.json。所有其他目录（commands/、agents/、skills/、hooks/）必须在插件根目录，而不是在 .claude-plugin/ 内。

CLI 命令参考

安装插件

bash

claude plugin install <plugin> [options]

选项	说明	默认值
`-s, --scope <scope>`	安装作用域：`user`、`project` 或 `local`	`user`

bash

# 安装到 user 作用域（默认）
claude plugin install formatter@my-marketplace

# 安装到 project 作用域（团队共享）
claude plugin install formatter@my-marketplace --scope project

卸载插件

bash

claude plugin uninstall <plugin> [options]

选项	说明
`-s, --scope <scope>`	从指定作用域卸载
`--keep-data`	保留持久数据目录

别名：remove、rm

启用/禁用插件

bash

claude plugin enable <plugin>
claude plugin disable <plugin>

更新插件

bash

claude plugin update <plugin>

调试和开发工具

调试命令

bash

claude --debug  # 查看插件加载详情

或在 TUI 中使用 /debug。

常见问题排查

问题	原因	解决方案
插件无法加载	`plugin.json` 无效	运行 `claude plugin validate` 检查
命令未显示	目录结构错误	确保 `commands/` 在根目录，而不在 `.claude-plugin/` 内
钩子未触发	脚本没有执行权限	运行 `chmod +x script.sh`
MCP 服务器失败	缺少 `${CLAUDE_PLUGIN_ROOT}`	对所有插件路径使用此变量
LSP 找不到可执行文件	语言服务器未安装	安装对应二进制文件

版本管理

遵循语义化版本：

json

{
  "name": "my-plugin",
  "version": "2.1.0"
}

MAJOR：破坏性变更
MINOR：向后兼容的新功能
PATCH：向后兼容的 Bug 修复

重要：如果更改了插件代码但未在 plugin.json 中更新版本，现有用户不会看到变更（因为缓存原因）。

插件技术参考 ​

插件组件参考 ​

技能（Skills） ​

代理（Agents） ​

钩子（Hooks） ​

MCP 服务器 ​

LSP 服务器 ​

插件安装作用域 ​

插件清单 Schema ​

必填字段 ​

元数据字段 ​

组件路径字段 ​

环境变量 ​

持久数据目录 ​

插件目录结构 ​

CLI 命令参考 ​

安装插件 ​

卸载插件 ​

启用/禁用插件 ​

更新插件 ​

调试和开发工具 ​

调试命令 ​

常见问题排查 ​

版本管理 ​

相关资源 ​

插件技术参考

插件组件参考

技能（Skills）

代理（Agents）

钩子（Hooks）

MCP 服务器

LSP 服务器

插件安装作用域

插件清单 Schema

必填字段

元数据字段

组件路径字段

环境变量

持久数据目录

插件目录结构

CLI 命令参考

安装插件

卸载插件

启用/禁用插件

更新插件

调试和开发工具

调试命令

常见问题排查

版本管理

相关资源