Plugins 参考

Claude Code 插件系统完整技术规范：组件、manifest、目录与 CLI。

是什么

plugin 是一个自包含目录，通过组件扩展 Claude Code 的功能。组件类型包括 skills、agents、hooks、MCP servers、LSP servers 和 monitors（还有 output styles、themes、channels、bin/ 可执行文件）。

安装的插件被复制到本地 plugin cache（~/.claude/plugins/cache）而非原地使用，每个版本是独立目录，更新/卸载后旧版本目录会在 7 天后清理。manifest（.claude-plugin/plugin.json）是可选的——省略时 Claude Code 在默认位置自动发现组件并用目录名作为插件名。

怎么工作

插件可不带 manifest：组件在默认位置（skills/、commands/、agents/、hooks/hooks.json、.mcp.json、.lsp.json、monitors/monitors.json、output-styles/、themes/、bin/）被自动发现，插件名取自目录名。
skills 是带 SKILL.md 的目录；commands 是扁平 .md 文件——两者安装后被自动发现，Claude 可按任务上下文自动调用，也可被用户手动调用。
agents 用 Markdown + frontmatter 定义，出现在 /agents 界面。出于安全原因，插件自带 agent 不支持 hooks、mcpServers、permissionMode。
hooks 在 hooks/hooks.json 用 event matcher + action 配置，支持 command/http/mcp_tool/prompt/agent 五种类型。
MCP servers 在插件启用时自动启动；LSP servers 提供实时诊断与代码导航，但语言服务器二进制需另行安装。
monitors 是后台监控：每行 stdout 作为 notification 投递给 Claude，仅在交互式 CLI 会话中运行、非沙箱、信任级别同 hooks（需 v2.1.105+）。
路径变量 ${CLAUDE_PLUGIN_ROOT}/${CLAUDE_PLUGIN_DATA}/${CLAUDE_PROJECT_DIR} 在组件内容、hook/monitor 命令、MCP/LSP 配置中被内联替换，也作为环境变量导出给子进程。
skills 目录下含 .claude-plugin/plugin.json 的文件夹被作为 <name>@skills-dir 插件就地加载，无 marketplace、无安装步骤，用 claude plugin init 脚手架生成。

怎么配置 / 用法

manifest 位置：.claude-plugin/plugin.json（唯一放在 .claude-plugin/ 里的文件；其余目录必须在插件根）。唯一必填字段是 name（kebab-case、无空格，用于 namespacing）。

完整 schema：

json

{
  "name": "plugin-name",
  "displayName": "Plugin Name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": { "name": "...", "email": "...", "url": "..." },
  "homepage": "...",
  "repository": "...",
  "license": "MIT",
  "keywords": ["keyword1"],
  "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" }]
}

标准目录布局：

text

enterprise-plugin/
├── .claude-plugin/plugin.json   # 仅 manifest 放这里
├── skills/<name>/SKILL.md
├── commands/*.md
├── agents/*.md
├── output-styles/*.md
├── themes/*.json
├── monitors/monitors.json
├── hooks/hooks.json
├── bin/                          # 加入 Bash PATH 的可执行文件
├── settings.json                 # 仅支持 agent / subagentStatusLine 键
├── .mcp.json
├── .lsp.json
└── scripts/

userConfig 选项字段：type（string/number/boolean/directory/file，必填）、title（必填）、description（必填）、sensitive、required、default、multiple、min/max。值通过 ${user_config.KEY} 替换，并导出为 CLAUDE_PLUGIN_OPTION_<KEY> 环境变量。

什么时候用

想给 Claude Code 打包一组自定义功能（skill/agent/hook/MCP/LSP/monitor）并分发给团队或社区时。
需要查 plugin.json 各字段、组件默认目录路径、hooks.json 支持的事件清单与 hook 类型时。
开发插件时要正确引用脚本/数据路径（${CLAUDE_PLUGIN_ROOT} vs ${CLAUDE_PLUGIN_DATA}）或排查插件不加载、hook 不触发的问题。
用 claude plugin 系列 CLI（init/install/uninstall/enable/disable/update/list/details/validate/tag/prune）做脚本化插件管理时。

限制 / 坑

安装后的插件不能引用其目录外的文件——../shared-utils 这类路径遍历在 cache 中失效；跨插件共享需用 symlink（仅在同一 marketplace 内会被解引用复制）。
插件根的 CLAUDE.md 不会作为项目上下文加载；要注入指令需放进 skill。
若在 plugin.json 设了 version，必须每次发布都 bump，否则用户收不到更新；快速迭代应留空让其回退到 git commit SHA。
项目作用域的 @skills-dir 插件只从启动目录的 .claude/skills/ 加载，不会向上走到仓库根；需从仓库根启动或运行 /reload-plugins。
settings.json 默认设置目前只支持 agent 和 subagentStatusLine 两个键。

硬事实速查（14 条）

manifest 路径固定为 .claude-plugin/plugin.json，且唯一必填字段是 name（kebab-case）。
默认组件位置：skills→skills/、commands→commands/、agents→agents/、hooks→hooks/hooks.json、MCP→.mcp.json、LSP→.lsp.json、monitors→monitors/monitors.json、themes→themes/、output styles→output-styles/、executables→bin/。
所有除 plugin.json 外的组件目录必须在插件根，不能放进 .claude-plugin/。
路径字段语义：skills 追加到默认 skills/；commands/agents/outputStyles/experimental.themes/experimental.monitors 替换默认目录。所有自定义路径须相对插件根、以 ./ 开头。
hook 类型五种：command、http、mcp_tool、prompt、agent；事件名大小写敏感（如 PostToolUse 不是 postToolUse）。
三个路径变量：${CLAUDE_PLUGIN_ROOT}（安装目录，随更新变化，勿存状态）、${CLAUDE_PLUGIN_DATA}（持久目录，解析为 ~/.claude/plugins/data/{id}/，跨版本存活）、${CLAUDE_PROJECT_DIR}（项目根）。
plugin agent frontmatter 支持 name/description/model/effort/maxTurns/tools/disallowedTools/skills/memory/background/isolation；isolation 唯一合法值是 worktree；不支持 hooks/mcpServers/permissionMode。
安装作用域四种：user（~/.claude/settings.json，默认）、project（.claude/settings.json，随版本控制共享）、local（.claude/settings.local.json，gitignore）、managed（只读、仅更新）。
version 解析顺序：plugin.json 的 version > marketplace 条目的 version > git commit SHA > unknown；plugin.json 优先。
plugin cache 在 ~/.claude/plugins/cache，旧版本目录在更新/卸载后 7 天清理；Glob/Grep 会跳过孤立的旧版本目录。
manifest 不认识的顶层字段被忽略（validate 报 warning，--strict 把 warning 当 error）；类型错误仍是加载错误。
bin/ 目录的可执行文件在插件启用时加入 Bash 工具 PATH，可作为裸命令直接调用。
monitor 必填字段 name/command/description，可选 when（always 默认 / on-skill-invoke:<skill-name>）；需 v2.1.105+。
常见排错：插件不加载→plugin.json 无效（跑 claude plugin validate）；skill 不出现→目录结构错；hook 不触发→脚本不可执行（chmod +x）；MCP 失败→缺 ${CLAUDE_PLUGIN_ROOT}；路径错→用了绝对路径。

官方出处：https://code.claude.com/docs/en/plugins-reference

Plugins 参考 ​

是什么 ​

怎么工作 ​

怎么配置 / 用法 ​

什么时候用 ​

限制 / 坑 ​