插件参考¶

Claude Code 插件系统的完整技术规范，包含组件 schema、CLI 命令和开发工具。

安装插件见 Discover and install plugins。创建插件见 Plugins。分发插件见 Plugin marketplaces。

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

插件组件参考¶

Skills¶

位置： skills/ 或 commands/ 目录，或插件根目录的单个 SKILL.md

Skills 是含 SKILL.md 的目录；commands 是简单 markdown 文件。安装后自动发现，Claude 可根据任务上下文自动调用。Skills 可包含 SKILL.md 旁边的支持文件。

如果插件没有 skills/ 目录也没有 skills 清单字段，根目录的 SKILL.md 作为单一 skill 加载。用 frontmatter 的 name 字段控制调用名；没有它则回退到安装目录名。

在插件 skills 和 commands 中，布尔 frontmatter 字段（如 disable-model-invocation）接受 yes、no、on、off、1、0（任何大小写），以及 true 和 false。v2.1.218 之前仅识别 true 和 false。

详见 Skills。

Agents¶

位置： agents/ 目录

Markdown 文件描述 agent 能力：

---
name: agent-name
description: What this agent specializes in and when Claude should invoke it
model: sonnet
effort: medium
maxTurns: 20
disallowedTools: Write, Edit
---

Detailed system prompt for the agent describing its role, expertise, and behavior.

支持 name、description、model、effort、maxTurns、tools、disallowedTools、skills、memory、background、isolation frontmatter 字段。唯一有效的 isolation 值是 "worktree"。安全原因不支持 hooks、mcpServers、permissionMode。

集成要点：
- 启用后 agent 出现在 @-mention typeahead 中，名称为 my-plugin:code-reviewer
- Claude 可根据任务上下文自动调用
- 与内置 Claude agent 协同工作

详见 Subagents。

Hooks¶

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

响应 Claude Code 生命周期事件：

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

支持的事件：

Hook 类型：

• command：执行 shell 命令或脚本
• http：将事件 JSON 作为 POST 请求发送到 URL
• mcp_tool：调用配置的 MCP 服务器上的工具
• prompt：用 LLM 评估 prompt（用 $ARGUMENTS 占位符传上下文）
• agent：运行带工具的 agentic 验证器

针对插件自身捆绑 MCP 服务器的 hook 必须使用作用域名称。工具匹配器和 if 字段用 mcp__plugin_<plugin-name>_<server-name>__<tool>，mcp_tool hook 的 server 字段用 plugin:<plugin-name>:<server-name>。

MCP 服务器¶

位置： .mcp.json 或内联在 plugin.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"
      }
    }
  }
}

• 插件启用时自动启动
• 作为标准 MCP 工具出现在 Claude 工具集中
• 可独立于用户 MCP 服务器配置
• 如果会话中 /reload-plugins，配置未变的服务器保持活跃连接

LSP 服务器¶

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

提供实时代码智能：即时诊断（编辑后立即看到错误和警告）、代码导航（跳转定义、查找引用）、类型信息和文档。

安装 LSP 插件：在 /plugin Discover 标签搜索 "lsp"。本节记录如何为官方市场未覆盖的语言创建 LSP 插件。

.lsp.json 格式：

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

必填字段：

可选字段：

restartOnCrash 和 shutdownTimeout 需 v2.1.205+。v2.1.205 之前，schema 接受这两个选项但设置任一会导致 Claude Code 跳过该 LSP 服务器。

同一扩展名的多个服务器：当多个启用的 LSP 服务器声明同一扩展名时，第一个注册的处理该扩展名的文件，其他不启动。/plugin 界面显示警告。

初始化失败的服务器：配置无效（如缺 command 或 extensionToLanguage）的服务器被跳过，其他服务器正常启动。用 claude --debug 查看跳过原因。

[!WARNING]
语言服务器二进制文件必须单独安装。 LSP 插件配置连接方式但不包含服务器本身。如果 /plugin Errors 标签显示 Executable not found in $PATH，安装对应语言的二进制文件。

可用 LSP 插件：

Monitors¶

位置： monitors/monitors.json 或内联在 plugin.json

后台监视器，Claude Code 在插件活跃时自动启动。每个 monitor 运行一个 shell 命令作为会话生命周期内的持久进程，每行 stdout 作为通知传递给 Claude。

插件 monitor 使用与 Monitor 工具相同的机制，共享其可用性约束：仅在交互式 CLI 会话中运行，与 hooks 同等信任级别无沙箱运行。

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

必填字段：

可选字段：

command 支持路径替换 ${CLAUDE_PLUGIN_ROOT}、${CLAUDE_PLUGIN_DATA}、${CLAUDE_PROJECT_DIR}。monitor command 不能引用 ${user_config.*} 值——Claude Code 会拒绝并报错。v2.1.207 之前 monitor 命令会替换 ${user_config.*} 值。

会话中禁用插件时，已运行的 monitor 不会停止——会话结束时才停止。

Themes¶

位置： themes/ 目录

颜色主题，出现在 /theme 中。含 base 预设和稀疏的 overrides 颜色 token 映射。Themes 是实验组件。

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

用户选择插件主题时，Claude Code 保存 custom:<plugin-name>:<slug>。插件主题只读：用户按 Ctrl+E 时复制到 ~/.claude/themes/ 供编辑。

安装作用域¶

详见 Install plugins 和 Configuration scopes。

Skills 目录插件¶

~/.claude/skills/ 或 <cwd>/.claude/skills/ 下含 .claude-plugin/plugin.json 的文件夹自动作为 <name>@skills-dir 加载，无需市场和安装步骤。用 plugin init 脚手架。

Skills 目录树支持三种不同的东西：

插件从哪里加载¶

项目作用域插件检入仓库。因内容来自仓库而非你，加载时受信任门控限制：
- MCP 服务器经过与项目 .mcp.json 相同的逐服务器批准
- LSP 服务器在信任工作区后才启动
- 后台 monitor 不加载

个人作用域插件无这些限制。

[!WARNING]
项目作用域 @skills-dir 插件仅从启动 Claude Code 的目录的 .claude/skills/ 加载，不会像普通 skills 那样向上查找仓库根目录。从子目录启动会遗漏根目录的插件。从仓库根启动，或切换目录后运行 /reload-plugins。

编辑、重载和禁用¶

skill 的 SKILL.md 修改立即生效。其他组件（hooks/、.mcp.json、agents/、output-styles/）需运行 /reload-plugins 或重启。详见 Live change detection。

禁用 skills-directory 插件（无需 uninstall）：

claude plugin disable my-tool@skills-dir

plugin.json Schema¶

清单可选。省略时 Claude Code 自动发现默认位置的组件。需提供元数据或自定义组件路径时使用清单。

必填字段¶

仅 name（kebab-case，无空格）。

未识别字段¶

Claude Code 忽略未识别的顶层字段。你可以在 plugin.json 中保留其他生态的元数据（VS Code/Cursor 扩展清单、npm package.json、MCPB/DXT bundle 清单）。

claude plugin validate 将未识别字段报为警告（非错误）。如果字段与已知字段只差一两个字符，警告会建议可能的正确名称。传 --strict 将警告视为错误（适合 CI）。

元数据字段¶

Default Enablement¶

设置 defaultEnabled: false 可让插件安装后默认禁用。用户通过 claude plugin enable 或 /plugin 界面开启。适用于有成本或需用户主动选择的插件（如连接外部服务）。需 v2.1.154+。

优先级：用户设置 > 依赖要求 > defaultEnabled。

组件路径字段¶

实验组件¶

experimental 键下的组件（themes 和 monitors）的清单 schema 可能在稳定前跨版本变化。

路径行为规则¶

• 所有路径必须相对于插件根目录且以 ./ 开头
• 可以数组形式指定多个路径
• skill 路径指向含 SKILL.md 的目录时，frontmatter name 字段决定调用名

环境变量¶

三者都作为环境变量导出给 hook 进程和 MCP/LSP 服务器子进程。

${CLAUDE_PLUGIN_ROOT} 在插件更新时变化。更新后旧版目录保留约两周，但应视为临时的。

User Configuration¶

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

每个选项支持的字段：

值可用 ${user_config.KEY} 在 MCP/LSP 配置和 hook 命令中替换。所有值导出为 CLAUDE_PLUGIN_OPTION_<KEY> 环境变量。

Shell 中运行的字段拒绝 ${user_config.*}（防注入），改用替代方式：
- Shell 形式 hook：用 exec 形式带 args，或从环境读 CLAUDE_PLUGIN_OPTION_<KEY>
- Monitor 命令：从配置文件读值
- MCP headersHelper：从配置文件读值

非敏感值存储在用户 settings.json 的 pluginConfigs 键下。敏感值存入 macOS Keychain 或 ~/.claude/.credentials.json。

pluginConfigs 仅从三个设置源读取：用户设置（~/.claude/settings.json）、--settings（CLI 标志或 SDK 内联设置）、managed settings。项目 .claude/settings.json 或 .claude/settings.local.json 中的条目被忽略（安全原因）。

Channels¶

channels 字段声明消息频道注入内容到对话。每个频道绑定插件提供的 MCP 服务器。

{
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "sensitive": true
        }
      }
    }
  ]
}

server 字段必填，必须匹配插件 mcpServers 中的键。

持久数据目录¶

${CLAUDE_PLUGIN_DATA} 解析为 ~/.claude/plugins/data/{id}/。常见用途是安装语言依赖一次后跨会话和更新复用。

推荐模式：比较捆绑清单与数据目录中的副本，不同时重新安装。示例 SessionStart hook：

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
          }
        ]
      }
    ]
  }
}

卸载时数据目录自动删除。CLI 默认删除；传 --keep-data 保留。

插件目录结构¶

enterprise-plugin/
├── .claude-plugin/plugin.json   # 清单（可选）
├── skills/                      # Skills
├── commands/                    # 扁平 .md 技能
├── agents/                      # Subagent 定义
├── workflows/                   # Workflow 脚本
├── output-styles/               # 输出样式
├── themes/                      # 颜色主题
├── monitors/monitors.json       # 后台监视器
├── hooks/hooks.json             # Hook 配置
├── bin/                         # 添加到 PATH 的可执行文件
├── settings.json                # 插件默认设置
├── .mcp.json                    # MCP 服务器
├── .lsp.json                    # LSP 服务器
└── scripts/                     # Hook 和工具脚本

[!WARNING]
.claude-plugin/ 目录仅放 plugin.json。其他目录（commands/、agents/、skills/ 等）必须在插件根目录，不在 .claude-plugin/ 内。

插件根目录的 CLAUDE.md 不作为项目上下文加载。插件通过 skills、agents 和 hooks 贡献上下文。

文件位置参考¶

CLI 命令参考¶

plugin init¶

脚手架新插件到 ~/.claude/skills/<name>/。下次会话自动作为 <name>@skills-dir 加载。

claude plugin init <name> [options]

别名：new

plugin install¶

claude plugin install <plugin> [options]

plugin uninstall¶

claude plugin uninstall <plugin> [options]

别名：remove、rm

[!NOTE]
不同市场的同名已安装插件，plugin-name@marketplace-name 形式仅卸载指定市场的。v2.1.212 之前可能匹配不同市场的同名插件。

plugin prune¶

移除不再被任何已安装插件需要的自动安装依赖。需 v2.1.121+。

claude plugin prune [options]

别名：autoremove

plugin enable¶

claude plugin enable <plugin> [--scope <scope>]

如果插件声明了依赖，递归启用。

plugin disable¶

claude plugin disable [plugin] [options]

被依赖时拒绝，错误给出链式禁用命令。

plugin update¶

claude plugin update <plugin> [-s user|project|local|managed]

plugin list¶

claude plugin list [--json] [--available]

--available 需配合 --json 使用，包含市场中可用的插件。

会话内 /plugin list 打印类似列表（仅市场安装的插件）。接受 --enabled 或 --disabled 过滤。ls 是 list 的简写。

plugin details¶

显示插件组件清单和预计 token 开销。

claude plugin details <name>

输出列出 Skills、Agents、Hooks、MCP servers、LSP servers 分组的所有组件，以及 token 估算：
- Always-on：每次会话的固定开销
- On-invoke：组件触发时的开销

plugin tag¶

为插件创建发布 git tag。详见 Tag plugin releases。

claude plugin tag [path] [options]

plugin validate¶

claude plugin validate <path> [--strict]

--strict 将警告视为错误。适合 CI 中捕获拼写错误或遗留字段。

缓存和文件解析¶

市场插件安装后复制到 ~/.claude/plugins/cache。每个版本独立目录。更新/卸载后旧版标记为孤立，14 天后自动清理。Glob/Grep 工具跳过孤立目录。

路径遍历限制： 安装的插件不能引用目录外的文件（../shared-utils 不会工作，外部文件不被复制）。

市场内用符号链接共享文件：
- 插件自身目录内：保留为相对 symlink
- 同一市场内其他位置：解引用，目标内容被复制
- 市场外：跳过（安全原因）

调试和开发工具¶

用 claude --debug 查看插件加载详情：加载了哪些插件、清单错误、技能/agent/hook 注册、MCP 服务器初始化。

常见问题¶

版本管理¶

Claude Code 用插件版本作为缓存键判断是否有更新。版本从以下来源按序解析：

1. plugin.json 的 version 字段
2. marketplace.json 中插件条目的 version 字段
3. 插件源的 git commit SHA
4. unknown（npm 源或非 git 仓库的本地目录）

两种版本策略：

[!WARNING]
设置了 version 后，必须每次要让用户收到变更时 bump 它。仅推送新 commit 不够——Claude Code 看到同一版本字符串就保留缓存。快速迭代时不设 version。

另见¶

• Plugins — 创建插件
• Plugin marketplaces — 分发插件
• Plugin dependencies — 版本约束
• Discover plugins — 安装插件
• Skills — 技能详解
• Sub-agents — subagent 详解
• Hooks — 事件处理和自动化
• MCP — 外部工具集成
• Settings — 插件配置选项