Plugin manifest 参考

plugin.json 的完整参考：每个字段的类型和默认值、接受的路径形式，以及 userConfig 和环境变量模式。

Plugin manifest 是 plugin 的 .claude-plugin/ 目录中的 plugin.json 文件。它包含 plugin 的元数据和 Claude Code 提示用户输入的 userConfig 值。它还声明任何在其默认位置之外定义内联或保留的组件。

本参考适用于 plugin 创建者，以及将组件字段放在 marketplace 条目中的 marketplace 所有者。

从与您要查找的内容相匹配的部分开始：

• 一个字段：字段表给出每个字段的类型、是否必需、其默认值以及它接受的内容。路径规则涵盖 ./ 前缀和每个组件路径的包含
• 一个 userConfig 选项或一个 channels 条目：用户配置和频道模式
• ${CLAUDE_PLUGIN_ROOT} 或 plugin 可以引用的另一个变量：环境变量
• 每个组件的文件位置：标准布局
• 来自 claude plugin validate 的消息：故障排除页面列出每条消息及其修复，并链接到本页的相关部分

Manifest 文件

manifest 是可选的。没有它，Claude Code 会加载它在标准布局中找到的组件。然后 plugin 名称来自 marketplace 条目，或者当您使用 --plugin-dir 加载 plugin 时来自目录名称。

当您想要元数据、组件在其默认目录之外、userConfig 或内联组件定义时，编写 manifest。

在 plugin 根目录下的 .claude-plugin/plugin.json 处保存 manifest。将所有其他 plugin 文件放在 plugin 根目录，而不是在 .claude-plugin/ 内。这包括 skills/、commands/ 和 hooks/。

以下示例设置了字段表中的大多数键。它在包含每个引用路径的 plugin 目录中通过验证。

{
  "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 条目内的无法识别的键被拒绝：

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

验证 manifest

claude plugin validate 是 manifest 的权威检查。从您的 shell 针对 plugin 目录运行它：

claude plugin validate ./my-plugin

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

• Validation passed：manifest 加载
• Validation passed with warnings：manifest 加载，但验证器发现需要修复的内容，例如 Claude Code 剥离的未知顶级字段、不是 kebab-case 的 name，或缺少 version、description 或 author。传递 --strict 以在 CI 中将警告转换为失败
• Validation failed：manifest 有类型不匹配、缺失或逃逸 plugin 根目录的路径，或 userConfig 选项、channels 条目、lspServers 配置或 monitors 条目内的未知键。Claude Code 在加载 plugin 时报告相同的问题

该命令还检查 plugin 在 .mcp.json 中声明的每个 MCP 服务器条目、在 mcpServers 命名的 .json 文件中，或在 plugin.json 中内联声明的条目。这些 MCP 检查需要 Claude Code v2.1.281 或更高版本，包括：

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

字段

该表列出了 plugin.json 中的顶级键。name 是唯一必需的键。如果字段名称是链接，链接的部分有其完整规则。

对于组件键（如 commands 和 hooks），组件路径形式显示每个接受的形式及示例，每个路径遵循 ./ 前缀、扩展名和包含的路径规则。

在"类型"列中，路径是相对于 plugin 根目录的字符串，例如 "./custom/commands"。

`name`

plugin 标识符。它必须非空，没有空格、@、:、路径分隔符、控制字符或双向格式字符；使用 kebab-case。

Claude Code 在其下命名空间每个组件，因此 plugin deploy-tools 中的 agent reviewer 显示为 deploy-tools:reviewer。

claude plugin validate 还检查该名称是否通过作为 Anthropic 自己的 plugin 之一。检查忽略大小写并将任何分隔符的运行视为一个：

错误读作 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 仍然安装和加载其名称被拒绝的 plugin。

`displayName`

在 UI 中显示的名称，代替 name。它可能包含空格和任何大小写，它不用于命名空间或查找。

对于 marketplace 安装的 plugin，marketplace 条目上的 displayName 优先于此值。

`version`

版本字符串，不针对 semver 检查。设置它会将 plugin 固定到该版本，直到您更改它；参见版本和更新。具有command 源的 plugin、来自托管在 claude.ai 上的 marketplace 的 plugin 以及从作为本地目录添加的 marketplace 就地加载的 plugin 不由此字段固定。

`metadata`

用于您自己数据的自由形式对象，例如目录或权利字段。Claude Code 不读取它。需要 Claude Code v2.1.222 或更高版本。

目录列表字段

当您提交插件时，Anthropic 的目录会从 plugin.json 中读取 icon、documentationUrl、supportUrl、privacyPolicyUrl 和 termsOfServiceUrl 字段，用于您插件的列表。Claude Code 在加载时忽略它们。请仅在 plugin.json 中设置它们。在市场条目中，claude plugin validate 会将它们逐一报告为未知字段。

将 icon 设置为插件内图像文件的路径，例如 ./logo.png，并将四个 URL 字段分别设置为 https:// URL。

在 Claude Code v2.1.281 或更高版本上，claude plugin validate 接受这些字段且不发出警告。更早的版本会为每个字段打印一条 Unknown field 警告，因此在这些版本上使用 --strict 运行会失败。

`defaultEnabled`

当用户未在 enabledPlugins 中设置时，plugin 是否在启用时启动。默认为 true。启用的 plugin 依赖的 plugin 无论如何都会启用启动。marketplace 条目中的相同字段覆盖此字段。

一旦用户的 enabledPlugins 条目被写入，它在 plugin 更新中持续存在，因此在后续版本中更改 defaultEnabled 不会更改现有用户的设置。

`dependencies`

必须为此 plugin 启用的 plugin。每个条目是 "name"、"name@marketplace" 或 { "name": "...", "marketplace": "...", "version": "..." }。裸名称针对此 plugin 自己的 marketplace 解析。参见依赖约束。

`settings`

Claude Code 在 plugin 启用时应用的设置。仅 agent 和 subagentStatusLine 生效；其他键在加载时被删除。plugin 根目录处的 settings.json 优先于此键。参见默认设置。

组件路径形式

每个组件键接受相对于 plugin 根目录的路径。hooks、mcpServers、lspServers 和 experimental.monitors 也接受内联配置，commands 也接受对象映射，mcpServers 也接受 MCP 包路径和 URL。以下示例显示每个接受的形式一次。有关每个组件在运行时的作用，参见Plugin 组件。

仅路径字段

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 命令文件或目录。在对象映射中，每个键在 plugin 前缀后成为命令名称。例如，plugin 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 参考。

hooks 文件将事件映射包装在顶层 "hooks" 键中，即 hooks/hooks.json 所使用的形状。仅包含事件映射而没有该包装的文件将无法加载。内联对象就是事件映射本身，不带包装。

Claude Code 在该文件存在时将您声明的内容与 hooks/hooks.json 合并。此数组加载一个 hooks 文件并声明一个内联 PostToolUse hook：

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

该数组指定的文件在其自身的事件映射外包含 "hooks" 包装：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/check-command.sh" }
        ]
      }
    ]
  }
}

`mcpServers`

mcpServers 采用 .json 文件路径、MCP 包路径或 URL、内联映射或混合它们的数组。有关服务器配置字段，参见plugin 提供的 MCP 服务器。

Claude Code 首先加载 plugin 根目录处的 .mcp.json，然后按顺序加载每个声明的形式。稍后声明的服务器名称替换较早的名称。

mcpServers 值采用以下形式之一：

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

`lspServers`

lspServers 采用 .json 文件路径、服务器名称到配置的内联映射，或两者的数组。

Claude Code 首先加载 plugin 根目录处的 .lsp.json，然后按顺序加载每个声明的配置。稍后声明的服务器名称替换较早的名称。

每个服务器配置是具有这些字段的严格对象。未知键验证失败。

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

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

有关 Anthropic 作为 plugin 发布的语言服务器以及服务器在运行时的行为，参见代码智能。

`monitors`

experimental.monitors 采用 .json 文件路径或内联数组。当您省略该键时，Claude Code 加载 monitors/monitors.json（如果存在）。

每个条目是具有这些字段的严格对象。

此内联数组声明一个在 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 运行的字段。

路径规则

manifest 中的每个组件路径相对于 plugin 根目录，必须以 ./ 开头。路径如 commands/foo.md 验证失败。skills 和 mcpServers 各接受该规则之外的一种形式：

• skills：也接受 "."。"." 和 "./" 都表示 plugin 根目录。在 v2.1.221 之前，"." 验证失败，因此当 plugin 必须在较早版本上加载时使用 "./"
• mcpServers：也接受 https:// 包 URL

experimental.evals 不是组件路径，因此本节中的规则不适用于它，而是由 claude plugin eval 在运行时检查该值。它指定插件根目录下的一个目录，例如 "quality/evals"，可以带或不带 ./ 前缀。如果是数组，则仅使用第一个条目。有关该值接受的内容以及值不可用时会发生什么，请参阅使用不同的 eval 目录。

包含和存在

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

• 包含：在 plugin 根目录外解析的路径不加载，/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。默认文件首先加载，manifest 声明的内容合并到它中，如组件路径形式下所述

如果 plugin 有默认文件夹（如 commands/）并且还设置了替换它的 manifest 键，Claude Code 加载 manifest 路径而不是文件夹。claude plugin list 和 /plugin 界面然后显示警告 Default <folder>/ folder is ignored because the manifest sets "<key>"。

要避免警告，将键设置为该文件夹内的路径："commands": ["./commands/deploy.md"] 命名默认文件夹中的文件，不产生警告。

用户配置

userConfig 声明 Claude Code 在 plugin 启用时提示用户输入的值，因此用户不自己编辑 settings.json。

键是由字母、数字和下划线组成的标识符，不能以数字开头。

每个值是具有这些字段的严格对象。未知键验证失败。

每个启用的 plugin 的每个选项也显示为 /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，Claude Code v2.1.271 之前版本的用户无法加载 plugin。

options 适用于不是 multiple 或 sensitive 的 string 字段。将 default 设置为列出的值之一，或设置 required: true 以便用户必须选择一个。每个选项是 1 到 64 个字符的纯标签，您在 shell 中运行的 claude plugin validate 报告它拒绝的任何其他内容。其 options 违反这些规则的 plugin 无法加载。

值的存储位置

非敏感值保存在用户 settings.json 中的 pluginConfigs 下。敏感值转到平台的安全凭证存储。设置页面列出从哪些设置文件读取 pluginConfigs。

引用保存的值

在 plugin 需要的地方引用保存的值，采用以下两种形式之一：

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

通过 shell 运行的字段

Shell 形式 hook 命令、monitor 命令和 MCP headersHelper 拒绝 ${user_config.*}。引用它的组件在这些字段之一中失败，出现错误而不是运行，因为字段的值被传递到会重新解析替换值的 shell。

该表显示值如何可以到达这些字段。

频道

channels 声明 plugin 提供的消息频道，例如到聊天应用的桥接。当您声明一个时，Claude Code 可以在 plugin 启用时提示频道的配置。有关服务器如何注入消息，参见频道参考。

每个条目是绑定到 plugin 的 MCP 服务器之一的严格对象，具有这些字段：

此 manifest 将频道绑定到 plugin 的 telegram MCP 服务器，并提示替换到服务器 env 中的机器人令牌：

{
  "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 为 plugin 组件提供三个路径变量。在每个变量解析的位置下列出的字段中将它们引用为 ${NAME}，并在接收它们的进程中将它们读取为环境变量。

${CLAUDE_PLUGIN_ROOT} 在 plugin 更新时改变，因此不要在那里写入状态。有关根目录移动的位置和旧目录何时被清理，参见加载页面。

默认情况下，当您从最后一个安装它的地方卸载 plugin 时，Claude Code 会删除 ${CLAUDE_PLUGIN_DATA} 目录。有关 --keep-data 和其他保留它的情况，参见 plugin 卸载。

每个变量解析的位置

在每个 plugin 组件中，${...} 引用在特定字段中内联解析，某些组件也在其进程环境中接收变量：

变量不存在于 Claude 通过 Bash 工具在主会话或子代理中运行的命令的环境中。在 skill、command 和 agent 内容中，在 Markdown 体中写入 ${...} 引用，Claude Code 在加载内容时内联替换路径。

引用和路径分隔符

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

• Hook 命令：使用exec 形式与 args 以便每个路径是一个没有引用的参数
• Shell 形式 hooks 和 monitor 命令：用双引号包装变量，以便带空格的路径保持为一个单词

如果您在 hooks 文件中的 shell 形式命令中将这些变量之一留在引号外，claude plugin validate 会发出警告，除非 hook 将 shell 设置为 "powershell"。

此 shell 形式 hook 运行与 plugin 捆绑的脚本：

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

在 Windows 上，替换的路径使用正斜杠，因此 shell 不会将反斜杠读取为转义。

标准布局

每个组件类型在 plugin 根目录下有默认位置，当 manifest 不指向其他位置时使用。

使用每个默认位置的 plugin，加上其 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

要点击此布局并阅读每个文件的作用，打开plugin 浏览器。

plugin 根目录处的 CLAUDE.md 不作为上下文加载，claude plugin validate 在找到一个时发出警告。要包含加载到 Claude 上下文中的说明，将它们放在 skill 中。

Marketplace 条目和 manifest

市场条目接受其自己的字段（包括 strict），以及此页面上除目录列表字段之外的每个字段。

strict 字段决定条目是否可以向具有自己 plugin.json 的 plugin 添加组件。它默认为 true。

条目字段如何与 `plugin.json` 结合

条目要么充当 manifest，要么向其添加组件，要么与其冲突：

• 没有 plugin.json：条目是 manifest，无论 strict 如何。条目 hooks 仅以内联对象形式加载。对于文件路径或数组，/plugin Errors 选项卡显示 not yet supported in a marketplace entry 错误
• plugin.json 存在，strict 未设置或 true：Claude Code 加载 manifest 并将条目的 commands、agents、skills、outputStyles 和 themes 附加到它。对于 hooks，条目对事件的匹配器替换 manifest 对该相同事件的匹配器，仅 manifest 声明的事件保留其
• plugin.json 存在，strict: false：声明 commands、agents、skills、hooks、outputStyles 或 themes 的条目是冲突，plugin 加载失败，出现 Plugin <name> has conflicting manifests

当其 source 是 marketplace 根目录的 marketplace 条目列出特定 skills 子目录时，仅这些子目录加载，plugin 的默认 skills/ 目录不被扫描。manifest 中的 skills 键改为添加到默认值。

元数据优先级

某些元数据字段有固定的优先级，无论 strict 如何：

• defaultEnabled 和显示字段：条目的 defaultEnabled 和其显示字段（如 displayName）覆盖 manifest 的
• version：manifest 的 version 覆盖条目的
• name：当条目在与 manifest 不同的 name 下列出 plugin 时，enabledPlugins 使用条目名称，组件在 manifest 名称下命名空间

有关完整的优先级表，参见严格模式。

后续步骤

• 向 plugin 添加组件：每个组件在运行时的作用，带有验证的示例
• Marketplace 参考：marketplace 可以为您的 plugin 设置的条目字段
• Plugin 命令参考：claude plugin validate 标志和输出
• Plugin 故障排除：每条验证消息及其修复