插件参考

插件清单是插件 .claude-plugin/ 目录里的 plugin.json 文件。它携带插件的元数据，以及 Claude Code 向用户提示填写的 userConfig 值，还声明你内联定义或放在默认位置之外的任何组件。本参考面向插件作者，以及把组件字段放进市场条目的市场所有者。学习构建插件见「创建插件」；各组件在运行时做什么见「插件组件」。下面的版本号要求以官方为准。

清单文件

清单是可选的。没有它，Claude Code 会加载在标准布局里找到的组件；此时插件名取自市场条目，或在你用 --plugin-dir 加载插件时取自目录名。当你需要元数据、默认目录之外的组件、userConfig 或内联的组件定义时，才写清单。

把清单保存为插件根目录下的 .claude-plugin/plugin.json。其他所有插件文件放在插件根目录，而不是 .claude-plugin/ 里，包括 skills/、commands/ 和 hooks/。下面的例子设置了字段表里的大部分键，在包含每个被引用路径的插件目录里能通过校验：

{
  "name": "deploy-tools",
  "displayName": "Deploy Tools",
  "version": "1.2.0",
  "description": "Deployment commands, a review agent, and a status monitor",
  "author": {
    "name": "Example Team",
    "email": "dev@example.com",
    "url": "https://example.com"
  },
  "homepage": "https://example.com/docs/deploy-tools",
  "repository": "https://github.com/example/deploy-tools",
  "license": "MIT",
  "keywords": ["deployment", "ci"],
  "defaultEnabled": true,
  "dependencies": ["secrets-vault"],
  "metadata": { "catalogId": "cat-123" },
  "skills": ["./extra-skills/"],
  "commands": {
    "status": {
      "source": "./commands/status.md",
      "description": "Show the current deployment status"
    },
    "about": {
      "content": "Explain what the deploy-tools plugin provides.",
      "description": "Describe this plugin"
    }
  },
  "agents": ["./agents/reviewer.md"],
  "hooks": "./config/extra-hooks.json",
  "mcpServers": {
    "deploy-api": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  },
  "lspServers": "./.lsp.json",
  "outputStyles": "./styles/",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./config/monitors.json"
  },
  "userConfig": {
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "Token for the deployment API",
      "sensitive": true
    }
  }
}

无法识别的字段

无法识别的顶层键会被剥离，而 userConfig 选项、channels 条目、lspServers 配置或 monitors 条目里无法识别的键会被拒绝：

• 顶层字段：该字段被剥离，插件仍然加载；claude plugin validate 把每个无法识别的顶层字段报告为警告。
• 严格对象：userConfig 选项、channels 条目、lspServers 配置和 monitors 条目是严格的；其中的未知键是错误，插件不加载。

校验清单

claude plugin validate 是对清单的权威检查，在 shell 里对插件目录运行：

claude plugin validate ./my-plugin

该命令报告以下结果之一：

• Validation passed：清单能加载。
• Validation passed with warnings：清单能加载，但校验器发现了需要修复的东西，例如 Claude Code 会剥离的未知顶层字段、不是 kebab-case 的 name，或缺失的 version、description 或 author。在 CI 里传 --strict 把警告变成失败。
• Validation failed：清单有类型不匹配、缺失或逃出插件根目录的路径，或 userConfig 选项、channels 条目、lspServers 配置、monitors 条目里有未知键。Claude Code 加载该插件时会报告同样的问题。

该命令还会检查插件在 .mcp.json 里、在 mcpServers 所指名的 .json 文件里或在 plugin.json 里内联声明的每个 MCP 服务器条目（这些 MCP 检查需要 Claude Code v2.1.281 或更高）：

• 错误：Claude Code 加载插件时会丢弃的条目、引用了清单未声明选项的 ${user_config.KEY}，以及不是有效绝对 URL 的远程 url。
• 警告：指向非环回主机的 http:// 或 ws:// URL，以及看起来像字面凭据的头值。

字段

下表列出 plugin.json 的顶层键。name 是唯一必需的键。

类型列里，「路径」是相对插件根目录的字符串，如 "./custom/commands"。

name

插件标识。它必须非空，不含空格、@、:、路径分隔符、控制字符或双向格式化字符；使用 kebab-case。Claude Code 把每个组件都放在它的命名空间下，所以插件 deploy-tools 里的智能体 reviewer 显示为 deploy-tools:reviewer。

claude plugin validate 还检查名称不能冒充 Anthropic 自己的插件。该检查忽略大小写，并把任何一串分隔符当作一个：

错误信息是 Plugin name "<name>" is reserved: it passes as one of Anthropic's own，警告是 Plugin name "<name>" reads as one of Anthropic's own。claude plugin init 和 claude plugin tag 拒绝引发错误的名称；只有这些命令检查名称，Claude Code 仍会安装并加载它们拒绝的名称的插件。

displayName

在界面中代替 name 显示的名称。它可以包含空格和任何大小写，不用于命名空间或查找。对从市场安装的插件，市场条目上的 displayName 优先于这个值。

version

版本字符串，不按 semver 检查。设置它会把插件固定在该版本，直到你改变它；见插件加载页的「版本与更新」。带 command 来源的插件、来自 claude.ai 上托管市场的插件，以及从作为本地目录添加的市场原地加载的插件，不受这个字段固定。

metadata

供你自己数据用的自由格式对象，例如目录或授权字段。Claude Code 不读取它（需要 Claude Code v2.1.222 或更高）。

defaultEnabled

用户没有在 enabledPlugins 里设置它时，插件是否默认启用，默认 true。被已启用插件依赖的插件无论如何都默认启用。市场条目里的同名字段覆盖这个字段。用户的 enabledPlugins 条目一旦写入，就会跨插件更新持久保留，所以在之后的发布里改变 defaultEnabled 不会改变现有用户的设置。

dependencies

必须启用才能让本插件工作的插件。每个条目是 "name"、"name@marketplace" 或 { "name": "...", "marketplace": "...", "version": "..." }；裸名称针对本插件自己的市场解析。见「插件依赖」。

settings

插件启用期间 Claude Code 应用的设置。只有 agent 和 subagentStatusLine 生效，其他键在加载时被丢弃。插件根目录的 settings.json 优先于这个键；见插件组件页的「默认设置」。

组件路径形式

每个组件键都接受相对插件根目录的路径。hooks、mcpServers、lspServers 和 experimental.monitors 也接受内联配置，commands 还接受对象映射，mcpServers 还接受 MCP 包路径和 URL。

仅路径的字段

agents、skills、outputStyles、workflows 和 experimental.themes 接受一个路径或路径数组。agents 的条目必须是 .md 文件，skills 的条目必须是目录；其他三个接受目录或文件。

{
  "agents": ["./custom-agents/reviewer.md", "./custom-agents/tester.md"],
  "skills": ["./extra-skills/", "."],
  "outputStyles": "./styles/"
}

commands

commands 接受路径、路径数组或对象映射。路径指名一个扁平的 .md 命令文件或目录。在对象映射里，每个键在插件前缀之后成为命令名：例如插件 deploy-tools 里的 "about" 运行为 /deploy-tools:about。每个值恰好设置 source 或 content 之一，两者都设或都不设的条目校验失败。该表里的其他字段是可选的：

这个映射从文件声明一个命令，并从内联内容声明另一个：

{
  "commands": {
    "status": { "source": "./commands/status.md", "argumentHint": "[env]" },
    "about": { "content": "Explain what this plugin provides." }
  }
}

hooks

hooks 接受 .json 文件路径、与 settings.json 里 hooks 形状相同的内联 hooks 对象，或混合两者的数组。hook 事件和处理器字段见 hooks 参考。Claude Code 把你声明的内容与 hooks/hooks.json（存在时）合并。

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

mcpServers

mcpServers 接受 .json 文件路径、MCP 包路径或 URL、内联映射，或混合它们的数组。服务器配置字段见 MCP 页的插件提供的 MCP 服务器。Claude Code 先加载插件根目录的 .mcp.json，再按顺序加载每种声明的形式；后声明的同名服务器替换先声明的。mcpServers 值取以下形状之一：

包路径或 URL 必须以 .mcpb 或 .dxt 结尾，任何其他扩展名校验失败。

lspServers

lspServers 接受 .json 文件路径、服务器名到配置的内联映射，或两者之一的数组。Claude Code 先加载插件根目录的 .lsp.json，再按顺序加载每个声明的配置；后声明的同名服务器替换先声明的。每个服务器配置是带这些字段的严格对象，未知键会校验失败：

这个内联配置为 .go 文件运行 gopls：

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

Anthropic 作为插件发布的语言服务器以及它们在运行时的行为，见「代码智能插件」。

monitors

experimental.monitors 接受 .json 文件路径或内联数组。省略该键时，如果 monitors/monitors.json 存在，Claude Code 就加载它。每个条目是带这些字段的严格对象：

这个内联数组声明一个在 deploy skill 第一次运行时启动的 monitor：

{
  "experimental": {
    "monitors": [
      {
        "name": "deploy-status",
        "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
        "description": "Deployment status changes",
        "when": "on-skill-invoke:deploy"
      }
    ]
  }
}

monitor 的 command 不能引用 ${user_config.*}，见下面「通过 shell 运行的字段」。

路径规则

清单里的每个组件路径都相对插件根目录，且必须以 ./ 开头；commands/foo.md 这样的路径校验失败。skills 和 mcpServers 各接受一种该规则之外的形式：

• skills：也接受 "."；"." 和 "./" 都表示插件根目录。（v2.1.221 之前，"." 清单校验失败，所以插件必须在更早版本上加载时用 "./"。）
• mcpServers：也接受 https:// 包 URL。

包含与存在

每个组件路径都必须解析到插件根目录之内并且必须存在。claude plugin validate 检查每个组件键下的路径：

• 包含：解析到插件根目录之外的路径不会加载，/plugin 的 Errors 标签页显示 <component> path escapes plugin directory: <path>。含 .. 的路径是常见情形，claude plugin validate 报告错误 Path contains ".." which could be a path traversal attempt。
• 存在：不存在的路径不会加载，/plugin 的 Errors 标签页显示 <component> path not found: <path>；claude plugin validate 报告错误 Path not found。

对 outputStyles、lspServers、monitors 和 themes 路径，claude plugin validate 的检查需要 Claude Code v2.1.283 或更高。

每个键如何与它的默认位置组合

每个组件键要么替换它的默认位置，要么加到它之上，要么与它合并：

• 替换默认：commands、agents、outputStyles、workflows、experimental.themes、experimental.monitors。设置了 commands 时，默认的 commands/ 目录不会被扫描；要保留默认并添加更多，显式列出它："commands": ["./commands/", "./extras/"]。
• 加到默认之上：skills。skills/ 目录仍会被扫描，列出的目录与它一起加载。
• 合并：hooks、mcpServers、lspServers。默认文件先加载，清单声明的内容合并进去，如「组件路径形式」所述。

如果插件有 commands/ 这样的默认文件夹，同时又设置了替换它的清单键，Claude Code 加载清单路径而不是该文件夹；claude plugin list 和 /plugin 界面随后显示警告 Default <folder>/ folder is ignored because the manifest sets "<key>"。要避免该警告，把键设为该文件夹内的路径："commands": ["./commands/deploy.md"] 指名默认文件夹里的文件，不产生警告。

用户配置

userConfig 声明插件启用时 Claude Code 向用户提示填写的值，使用户不必自己编辑 settings.json。键是由字母、数字和下划线组成的标识符，不能以数字开头。每个值是带这些字段的严格对象，未知键校验失败：

每个已启用插件的每个选项还会作为一行出现在 /config 面板里，sensitive 选项和 multiple 列表除外（/config 里的行需要 Claude Code v2.1.269 或更高）。这个 userConfig 声明一个端点和一个被遮蔽的令牌：

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

把字段限制为固定选项

在 userConfig 字段上设置 options，让用户从固定列表里选择它的值。要把 tone 字段限制为三个选项，把它们列在 options 里并把 default 设为其中之一：

{
  "userConfig": {
    "tone": {
      "type": "string",
      "title": "Tone",
      "description": "Voice for generated replies",
      "options": ["neutral", "warm", "formal"],
      "default": "neutral"
    }
  }
}

如果你在任何字段上声明了 options，运行 v2.1.271 之前 Claude Code 版本的用户无法加载该插件。options 适用于既非 multiple 也非 sensitive 的 string 字段；把 default 设为列出的值之一，或设置 required: true 让用户必须选一个。每个选项是 1 到 64 个字符的纯标签，你在 shell 里运行的 claude plugin validate 会报告它拒绝的其他任何东西；options 违反这些规则的插件加载失败。

值存储在哪里

非敏感的值保存在用户 settings.json 的 pluginConfigs 下。敏感的值改为进入平台的安全凭据存储。设置参考页列出了从哪些设置文件读取 pluginConfigs。

引用已保存的值

在插件需要的地方用两种形式之一引用已保存的值：

• ${user_config.KEY}：在 MCP 服务器配置、LSP 服务器配置、exec 形式 hook 的 args，以及 skill 和智能体内容里被替换；在 skill 和智能体内容里，只有非敏感的值被替换，敏感的值在那里变成占位符。
• CLAUDE_PLUGIN_OPTION_<KEY>：为每个选项导出给 hook 进程，<KEY> 大写；shell 形式的 hook 为 api_token 读取 $CLAUDE_PLUGIN_OPTION_API_TOKEN。

通过 shell 运行的字段

shell 形式的 hook 命令、monitor 命令和 MCP 的 headersHelper 拒绝 ${user_config.*}。在这些字段里引用它的组件会以错误失败而不是运行，因为该字段的值被传给 shell，shell 会重新解析被替换的值。下表展示值如何改为到达这些字段：

Channels

channels 声明插件提供的消息 channel，例如到聊天应用的桥。声明一个之后，插件启用时 Claude Code 可以提示填写该 channel 的配置。服务器如何注入消息见 Channels reference。每个条目是绑定到插件某个 MCP 服务器的严格对象，带这些字段：

这个清单把 channel 绑定到插件的 telegram MCP 服务器，并提示填写一个会替换进服务器 env 的 bot 令牌：

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": { "BOT_TOKEN": "${user_config.bot_token}" }
    }
  },
  "channels": [
    {
      "server": "telegram",
      "displayName": "Telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        }
      }
    }
  ]
}

环境变量

Claude Code 给插件组件提供三个路径变量。在「每个变量在哪里解析」列出的字段里把它们引用为 ${NAME}，并在接收它们的进程里把它们读作环境变量。

${CLAUDE_PLUGIN_ROOT} 在插件更新时会变，所以不要把状态写在那里；根目录何时移动、旧目录何时被清理，见加载页。默认情况下，当你从插件最后安装的位置卸载它时，Claude Code 会删除 ${CLAUDE_PLUGIN_DATA} 目录；--keep-data 以及数据保留的其他情形见 plugin uninstall 文档。

每个变量在哪里解析

在每个插件组件里，${...} 引用在特定字段里内联解析，有些组件还在进程环境里接收这些变量：

这些变量不在 Claude 通过 Bash 工具运行的命令的环境里（不论在主会话还是子智能体里）。在 skill、命令和智能体内容里，把 ${...} 引用写在 Markdown 正文里，Claude Code 在加载内容时内联替换路径。

引号和路径分隔符

让每个被替换的路径保持为单个参数：

• hook 命令：用带 args 的 exec 形式，使每个路径是一个无需加引号的参数。
• shell 形式的 hook 和 monitor 命令：把变量包在双引号里，使含空格的路径仍是一个词。

如果你在 hooks 文件的 shell 形式命令里把这些变量留在引号之外，claude plugin validate 会警告，除非该 hook 把 shell 设为 "powershell"。这个 shell 形式的 hook 运行随插件捆绑的脚本：

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

在 Windows 上，被替换的路径使用正斜杠，这样 shell 不会把反斜杠读作转义。

标准布局

每种组件类型在插件根目录下都有一个默认位置，在清单没有指向别处时使用。

一个用到所有默认位置、外加其 hooks 调用的 scripts/ 文件夹的插件，布局如下：

deploy-tools/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── deploy/
│       └── SKILL.md
├── commands/
│   └── status.md
├── agents/
│   └── reviewer.md
├── hooks/
│   └── hooks.json
├── monitors/
│   └── monitors.json
├── output-styles/
│   └── terse.md
├── themes/
│   └── dracula.json
├── workflows/
│   └── release-audit.js
├── bin/
│   └── deploy-tool
├── scripts/
│   └── format.sh
├── settings.json
├── .mcp.json
└── .lsp.json

插件根目录的 CLAUDE.md 不会作为上下文加载，claude plugin validate 发现它时会警告。要包含加载进 Claude 上下文的指令，把它们放进 skill。

市场条目与清单

市场条目接受本页的每个字段，外加它自己的字段，包括 strict。strict 字段决定条目是否可以向带有自己 plugin.json 的插件添加组件，默认 true。

条目字段如何与 plugin.json 组合

条目要么充当清单，要么向它添加组件，要么与它冲突：

• 没有 plugin.json：不论 strict 如何，条目就是清单。条目的 hooks 只在内联对象形式下加载；对那里的文件路径或数组，/plugin 的 Errors 标签页显示 not yet supported in a marketplace entry 错误。
• 有 plugin.json，strict 未设置或为 true：Claude Code 加载清单，并把条目的 commands、agents、skills、outputStyles 和 themes 追加到它上面。对 hooks，条目对某个事件的 matcher 替换清单对同一事件的 matcher，只有清单声明的事件保留它们的。
• 有 plugin.json，strict: false：声明了 commands、agents、skills、hooks、outputStyles 或 themes 中任何一个的条目是冲突，插件以 Plugin <name> has conflicting manifests 加载失败。

当 source 是市场根目录的市场条目列出了具体的 skills 子目录时，只有那些子目录加载，插件默认的 skills/ 目录不被扫描；清单里的 skills 键则是加到默认之上。

元数据优先级

有些元数据字段不论 strict 如何都有固定的优先级：

• defaultEnabled 和显示字段：条目的 defaultEnabled 及其 displayName 这样的显示字段覆盖清单的。
• version：清单的 version 覆盖条目的。
• name：当条目用与清单不同的 name 列出插件时，enabledPlugins 使用条目名，组件则以清单名为命名空间。

完整的优先级表见市场参考的 Strict mode。

marketplace.json 速查

市场文件位于 .claude-plugin/marketplace.json，必须有 name、owner 和 plugins 数组。每个插件条目需要 name 和 source；source 可以是从市场根出发的相对路径，也可以是指向 GitHub 仓库、Git URL 等外部位置的来源对象。条目的 name 要和插件清单的 name 一致。字段的完整列表以官方市场参考为准。

claude plugin 命令速查

在 shell 里管理插件：

在会话里对应的是 /plugin（打开插件面板）、/plugin install、/plugin marketplace add 和 /reload-plugins（不重启就应用待处理的改动）。启动标志 --plugin-dir、--plugin-url 为单个会话加载插件。

下一步

• 给插件添加组件：各组件在运行时做什么，附带能通过校验的示例。
• 市场参考：市场能为你的插件设置的条目字段。
• 插件命令参考：claude plugin validate 的标志和输出。
• 排查插件：每条校验消息及其修复。