Claude Code 插件系统技术参考，帮助你配置插件组件和排查加载错误。插件是一个自包含目录，包含 skills（/name 快捷方式）、agents（子代理）、hooks（事件处理器）、MCP 服务器（外部工具集成）、LSP 服务器（代码智能）和 monitors（后台监控）。所有组件在 .claude-plugin/plugin.json 中声明，环境变量 ${CLAUDE_PLUGIN_ROOT} 指向安装目录，数据目录 ${CLAUDE_PLUGIN_DATA} 用于持久化状态。安装时通过 -s 指定 user / project / local / managed 作用域。运行 claude --debug 可查看加载细节，用 claude plugin validate 检查清单语法。

Claude Code 插件技术参考：组件 Schema、plugin.json 字段与 CLI 命令完全指南 #

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

插件（plugin）是一个自包含目录，包含扩展 Claude Code 功能的组件：skills、agents、hooks、MCP servers、LSP servers 和 monitors。

插件组件参考 #

Skills #

插件通过 skills 提供 /name 快捷方式，由你或 Claude 调用。

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

文件格式：skills 是包含 SKILL.md 的子目录；commands 是扁平 .md 文件

Skill 结构：

skills/
├── pdf-processor/
│   ├── SKILL.md
│   └── scripts/
└── code-reviewer/
    └── SKILL.md

集成行为：

• 插件安装后自动发现，Claude 可根据任务上下文自动调用
• Skills 可包含 SKILL.md 旁的支撑文件（如脚本、文档）

详情参见技能。

Agents #

插件可提供专门子代理，Claude 在适当时机自动调用。

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

文件格式：Markdown 文件，frontmatter 描述代理能力

---
name: agent-name
description: 代理专长与调用时机
model: sonnet
effort: medium
maxTurns: 20
disallowedTools: Write, Edit
---

代理系统提示（描述角色、知识和行为）

支持的 frontmatter 字段：name, description, model, effort, maxTurns, tools, disallowedTools, skills, memory, background, isolation（仅 "worktree"）。安全限制：插件代理不支持 hooks、mcpServers、permissionMode。

集成要点：

• 出现在 /agents 界面，可自动或手动调用
• 与内置 Claude 代理并存

详情参见子代理。

Hooks #

插件可提供事件处理器，自动响应 Claude Code 生命周期事件。

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

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

支持的事件（与用户 hooks 相同生命周期）：

Hook 类型：command（shell 命令）、http（POST 请求）、mcp_tool（调用 MCP 工具）、prompt（用 LLM 评估）、agent（带工具的验证代理）

MCP 服务器 #

插件可捆绑 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"
      }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

集成行为：插件启用后自动启动，作为标准 MCP 工具集成，可与用户 MCP 服务器独立配置。

LSP 服务器 #

想使用 LSP 插件？从市场搜索 “lsp” 安装。本节说明如何为官方市场未覆盖的语言创建 LSP 插件。

插件可提供语言服务器协议（LSP）服务器，使 Claude 获得实时代码智能（即时诊断、代码导航、类型信息）。

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

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

必填字段：command（PATH 中的二进制）、extensionToLanguage（映射文件扩展名到语言 ID）

可选字段：args, transport（stdio 或 socket）, env, initializationOptions, settings, workspaceFolder, startupTimeout, shutdownTimeout, restartOnCrash, maxRestarts

注意：语言服务器二进制需要单独安装（如 pip install pyright、npm install -g typescript-language-server typescript）。如果看到 LSP Executable not found in $PATH 错误，请先安装对应二进制。

Monitors #

需要 Claude Code v2.1.105+。这是一个实验性组件。

插件可声明后台 monitor，在插件启用时自动启动。每个 monitor 运行一个 shell 命令，其 stdout 行会作为通知传递给 Claude。

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

[
  {
    "name": "deploy-status",
    "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh ${user_config.api_endpoint}",
    "description": "部署状态变化"
  },
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "应用错误日志",
    "when": "on-skill-invoke:debug"
  }
]

必填字段：name（插件内唯一，防止重复进程）、command（持久后台进程）、description（通知摘要）

可选字段：when（默认 "always" 或 "on-skill-invoke:<skill-name>"）

限制：仅交互式 CLI 会话中运行，无沙箱，信任级别与 hooks 相同。禁用插件不会停止已运行的 monitor，它们会在会话结束时停止。

Themes #

实验性组件。

插件可提供颜色主题，出现在 /theme 中。主题是 themes/ 下的 JSON 文件，包含 base（"dark" 或 "light"）和 overrides 颜色 tokens 映射。

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

选择主题后，配置中存储 custom:<plugin-name>:<slug>。主题只读；按 Ctrl+E 可复制到 ~/.claude/themes/ 编辑副本。

插件安装作用域 #

插件清单 Schema #

.claude-plugin/plugin.json 可选。省略时 Claude Code 按默认位置自动发现组件，用目录名作为插件名。

完整 Schema #

{
  "name": "plugin-name",
  "displayName": "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/",
  "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（唯一标识符，kebab-case，无空格）。用于组件命名空间，如 UI 中显示为 plugin-dev:agent-creator。

元数据字段 #

displayName（v2.1.143+，可含空格）、version、description、author、homepage、repository、license、keywords。

版本管理：若设置 version，用户需等你手动 bump 才更新；若省略，则用 git commit SHA 作为版本，每个新 commit 视为新版本。如果同时在市场条目设置了版本，plugin.json 优先。

组件路径字段 #

路径规则：所有路径应以 ./ 开头，相对于插件根目录。当 manifest 指定了替换字段（如 commands），默认目录不再扫描；若需保留默认，需显式列出："commands": ["./commands/", "./extras/"]。

未识别字段 #

Claude Code 忽略不认识的顶层字段（仅警告）。例如，可同时作为 VS Code 扩展清单使用。运行 claude plugin validate --strict 可将警告视为错误（适合 CI）。

用户配置 (userConfig) #

声明启用时提示用户输入的值，避免编辑 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
    }
  }
}

非敏感值存储于 settings.json 的 pluginConfigs[<plugin-id>].options；敏感值存储于系统钥匙串（或 ~/.claude/.credentials.json），约 2KB 总限制，保持简短。所有值可通过 ${user_config.KEY} 在 MCP、LSP、hook、monitor 命令中替换，并导出为 CLAUDE_PLUGIN_OPTION_<KEY> 环境变量。

Channels #

插件可声明消息频道（Telegram/Slack/Discord 风格），由 MCP 服务器提供注入内容。

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

server 必须匹配插件 mcpServers 中的 key。

环境变量 #

持久数据最佳实践 #

数据目录存活于插件版本之外，建议对比 plugin.json 与数据目录中的副本是否需要重装依赖。以下 SessionStart hook 示例安装 node_modules：

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

插件缓存与文件解析 #

市场插件被复制到 ~/.claude/plugins/cache，不能引用外部文件。旧版本目录标记为孤儿，7 天后自动删除（宽限期让旧会话继续运行）。

路径遍历限制与符号链接 #

无法引用插件目录之外的文件。可在插件内创建符号链接：若目标在插件目录内则保留为相对链接；若在同一个市场内则解引用复制内容；若在市场外则跳过（安全原因）。

标准插件目录结构 #

enterprise-plugin/
├── .claude-plugin/plugin.json
├── skills/        # SKILL.md 子目录
├── commands/      # 扁平 .md 技能文件
├── agents/        # 子代理 Markdown
├── output-styles/ # 输出样式
├── themes/        # 颜色主题 JSON
├── monitors/      # 监控配置 JSON
├── hooks/         # hooks.json 及额外 hook 文件
├── bin/           # 可执行文件（加入 Bash 工具 PATH）
├── settings.json  # 默认设置
├── .mcp.json      # MCP 服务器定义
├── .lsp.json      # LSP 服务器配置
├── scripts/       # hook 和工具脚本
├── LICENSE
└── CHANGELOG.md

组件目录必须在插件根目录，而非 .claude-plugin/ 内。

CLI 命令参考 #

plugin install #

claude plugin install <plugin> [options]

选项：-s, --scope <scope>（user/project/local，默认 user）

示例：claude plugin install formatter@my-marketplace --scope project

plugin uninstall #

claude plugin uninstall <plugin> [options]

选项：-s, --scope <scope>（默认 user）、--keep-data（保留数据目录）、--prune（同时移除无依赖的自动安装依赖）、-y（跳过确认）

别名：remove, rm

注意：从最后一个作用域卸载时默认删除 ${CLAUDE_PLUGIN_DATA} 目录，用 --keep-data 保留。

plugin prune #

移除无其他插件需要的自动安装依赖（仅限 dependencies 安装的，手动安装的插件不受影响）。

claude plugin prune [options]

选项：-s, --scope（默认 user）、--dry-run（列出但不移除）、-y 跳过确认

需要 v2.1.121+。别名：autoremove

plugin enable / disable #

启用/禁用插件而不卸载。

claude plugin enable <plugin> [options]
claude plugin disable <plugin> [options]

选项：-s, --scope（user/project/local，默认 user）

禁用时若其他启用插件依赖它，命令失败并提示链式禁用命令。

plugin update #

更新插件到最新版本。

claude plugin update <plugin> [options]

选项：-s, --scope（默认 user，支持 managed）

plugin list #

列出已安装插件的信息（版本、市场、启用状态）。

claude plugin list [options]

选项：--json（JSON 输出）、--available（含市场可用插件，需 --json）

plugin details #

显示插件组件清单和预计 token 成本。

claude plugin details <name>

输出按组件分组（Skills、Agents、Hooks、MCP、LSP），显示 always-on 和 on-invoke 两种 token 估算。

plugin tag #

为当前目录中的插件创建 Git release tag。适用于版本依赖解析。

claude plugin tag [options]

选项：--push（push 到远程）、--dry-run、-f, --force

调试与常见问题 #

调试命令 #

claude --debug

显示插件加载详情、清单错误、组件注册、MCP 初始化。

常见问题 #

错误消息示例 #

• Invalid JSON syntax: Unexpected token }：检查逗号、引号
• Plugin has an invalid manifest ... Validation errors: name: Required：缺少 name
• Warning: No commands found in plugin my-plugin custom directory: ./cmds.：指定路径下无有效命令文件
• Plugin my-plugin has conflicting manifests：重复定义组件

Hook 调试清单 #

1. 脚本可执行：chmod +x
2. shebang 行：#!/bin/bash
3. 使用 ${CLAUDE_PLUGIN_ROOT} 并加双引号
4. 事件名大小写正确：PostToolUse 而非 postToolUse
5. matcher 正则匹配工具名

MCP 服务器调试清单 #

1. 命令存在且可执行
2. 路径使用 ${CLAUDE_PLUGIN_ROOT}
3. 查看 claude --debug 输出中的初始化错误
4. 在 Claude Code 外手动测试服务器

版本管理 #

通过 plugin.json 的 version 字段或 git commit SHA 作为版本。若设置 version，UI/CLI 显示的版本为该字段值，更新需要手动 bump。若不设置，每次新 commit 自动视为新版本（适用于内部开发）。遵循语义化版本：MAJOR.MINOR.PATCH。

常见问题 #

插件安装后 skills/commands 不出现怎么办？ #

检查目录结构：skills/ 或 commands/ 必须在插件根目录，而非 .claude-plugin/ 内。运行 claude --debug 查看加载信息，确认是否有 “No commands found” 警告。执行 claude plugin validate 检查清单和组件 frontmatter 语法。

如何在插件中使用外部 API token 但不写死在配置里？ #

使用 userConfig 字段声明 sensitive: true 的配置项（如 api_token）。启用插件时用户会被提示输入，值存储在系统钥匙串（或 ~/.claude/.credentials.json），并通过 ${user_config.api_token} 在 MCP、LSP、hook 命令中替换，也能通过 CLAUDE_PLUGIN_OPTION_API_TOKEN 环境变量访问。

更新插件后 hooks/MCP 服务器仍使用旧路径怎么办？ #

由于插件更新后 CLAUDE_PLUGIN_ROOT 指向新路径，但当前会话中的 hooks/MCP/LSP 服务器进程仍使用旧路径。运行 /reload-plugins 可切换这些组件到新路径；monitors 需要重启整个会话（SessionEnd 后重新开始）。