Plugin manifest 参考 - Claude Code Docs

Plugin manifest 是 plugin 的 .claude-plugin/ 目录中的 plugin.json 文件。它包含 plugin 的元数据和 Claude Code 提示用户输入的 userConfig 值。它还声明任何在其默认位置之外定义内联或保留的组件。本参考适用于 plugin 创建者，以及将组件字段放在 marketplace 条目中的 marketplace 所有者。

这些情况在其他页面上有介绍：

学习构建 plugin：从创建 plugin开始
每个组件在运行时的作用：参见Plugin 组件

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

一个字段：字段表给出每个字段的类型、是否必需、其默认值以及它接受的内容。路径规则涵盖 ./ 前缀和每个组件路径的包含
一个 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.json 中的顶级键。name 是唯一必需的键。如果字段名称是链接，链接的部分有其完整规则。对于组件键（如 commands 和 hooks），组件路径形式显示每个接受的形式及示例，每个路径遵循 ./ 前缀、扩展名和包含的路径规则。

字段	类型	描述
`$schema`	String	用于编辑器自动完成的 JSON Schema URL。Claude Code 在加载时忽略它
`name`	String	Plugin 标识符，必需。使用 kebab-case。每个组件都在其下命名空间
`displayName`	String	在 UI 中显示的名称，代替 `name`
`version`	String	版本字符串。设置它会将用户保持在该版本，直到您更改它
`description`	String	plugin 提供的内容的简短说明
`author`	Object	`name`（必需），加上可选的 `email` 和 `url`
`homepage`	String	文档 URL。必须解析为 URL，否则 plugin 加载失败
`repository`	String	源代码库 URL。未验证
`license`	String	SPDX 标识符，如 `MIT` 或 `Apache-2.0`
`keywords`	Array of strings	发现标签
`metadata`	Object	用于您自己数据的自由形式对象。Claude Code 不读取它
`defaultEnabled`	Boolean	当用户未设置时 plugin 是否在启用时启动。默认为 `true`
`dependencies`	Array of strings or objects	必须为此 plugin 启用的 plugin
`settings`	Object	Claude Code 在 plugin 启用时应用的设置。仅 `agent` 和 `subagentStatusLine` 生效
`userConfig`	Object	Claude Code 在 plugin 启用时提示用户输入的值
`channels`	Array of objects	plugin 提供的消息频道，每个绑定到其 MCP 服务器之一
`skills`	Path, or array of paths	要扫描的目录以查找 skills，每个目录是 `<name>/SKILL.md` 文件夹或直接包含 `SKILL.md` 的一个文件夹。`"."` 命名 plugin 根目录。添加到默认 `skills/` 扫描
`commands`	Path, array of paths, or object	平面 `.md` 命令文件、它们的目录或命令名称到 `source` 或 `content` 的对象映射。替换默认 `commands/` 扫描
`agents`	Path, or array of paths	Agent `.md` 文件。不接受目录。替换默认 `agents/` 扫描
`hooks`	Path, object, or array of either	`.json` hook 文件或内联 hook 配置。与 `hooks/hooks.json` 一起加载
`mcpServers`	Path, object, or array of either	`.json` MCP 配置文件、`.mcpb` 或 `.dxt` 包，或按名称键入的内联服务器配置。与 `.mcp.json` 一起加载；稍后声明的服务器名称替换较早的名称
`lspServers`	Path, object, or array of either	`.json` LSP 配置文件或按名称键入的内联服务器配置。与 `.lsp.json` 一起加载
`outputStyles`	Path, or array of paths	输出样式文件或目录。替换默认 `output-styles/` 扫描
`workflows`	Path, or array of paths	Workflow `.js` 文件或目录。替换默认 `workflows/` 扫描
`experimental`	Object	`themes`、`monitors` 和 `evals` 的容器，其 manifest 形式可能仍会改变
`experimental.themes`	Path, or array of paths	主题文件或目录。替换默认 `themes/` 扫描。顶级 `themes` 键仍然加载，带有 `claude plugin validate` 警告
`experimental.monitors`	Path, or inline array	包含 monitors 数组的 `.json` 文件，或数组本身。默认为 `monitors/monitors.json`。顶级 `monitors` 键仍然加载，带有 `claude plugin validate` 警告。Monitors 仅在交互式会话中运行，不在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上运行
`experimental.evals`	Path, or array of paths	当不是默认 `evals/` 时，保存 plugin 的评估案例的目录。`claude plugin eval --eval-dir` 覆盖它

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

`name`

plugin 标识符。它必须非空，没有空格、@、:、路径分隔符、控制字符或双向格式字符；使用 kebab-case。 Claude Code 在其下命名空间每个组件，因此 plugin deploy-tools 中的 agent reviewer 显示为 deploy-tools:reviewer。

`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 或更高版本。

`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 之一，设置两者或都不设置的条目验证失败。此表中的其他字段是可选的：

字段	类型	描述
`source`	string	命令的 Markdown 文件的路径，相对于 plugin 根目录
`content`	string	命令体的内联 Markdown，而不是 `source`
`description`	string	为命令显示的描述
`argumentHint`	string	在命令名称后显示的参数提示，例如 `[file]`
`model`	string	命令的默认模型
`allowedTools`	array of strings	命令可以使用而无需提示的工具

此映射声明一个来自文件的命令和一个来自内联内容的命令：

{
  "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、内联映射或混合它们的数组。有关服务器配置字段，参见plugin 提供的 MCP 服务器。 Claude Code 首先加载 plugin 根目录处的 .mcp.json，然后按顺序加载每个声明的形式。稍后声明的服务器名称替换较早的名称。 mcpServers 值采用以下形式之一：

形式	示例值	Claude Code 的作用
`.json` 文件路径	`"./mcp/servers.json"`	将文件读取为 `mcpServers` 映射
MCP 包路径	`"./bundle.mcpb"`	将 `.mcpb` 或 `.dxt` 包提取到 plugin 根目录下的 `.mcpb-cache/` 并读取其服务器配置
MCP 包 URL	`"https://example.com/server.mcpb"`	将包下载到 `.mcpb-cache/`，然后读取它
内联映射	`{ "deploy-api": { "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"] } }`	使用映射作为按名称键入的服务器配置

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

`lspServers`

lspServers 采用 .json 文件路径、服务器名称到配置的内联映射，或两者的数组。 Claude Code 首先加载 plugin 根目录处的 .lsp.json，然后按顺序加载每个声明的配置。稍后声明的服务器名称替换较早的名称。每个服务器配置是具有这些字段的严格对象。未知键验证失败。

字段	必需	描述
`command`	Yes	语言服务器二进制文件。除非值以 `/` 开头，否则没有空格；将参数放在 `args` 中
`extensionToLanguage`	Yes	文件扩展名到 LSP 语言 ID 的映射，至少一个条目。键以点开头，例如 `".go"`
`args`	No	传递给服务器的参数
`transport`	No	通信传输：`stdio`（默认）或 `socket`。Claude Code 接受 `socket` 但在 stdio 上运行每个服务器，因此 stdout 协议规则适用于所有服务器
`env`	No	服务器进程的环境变量
`initializationOptions`	No	在初始化请求中发送的选项
`settings`	No	由 `workspace/didChangeConfiguration` 发送的设置
`workspaceFolder`	No	服务器的工作区文件夹路径
`startupTimeout`	No	等待启动的毫秒数，正整数
`shutdownTimeout`	No	等待正常关闭的毫秒数，正整数。当超时时间过去时，Claude Code 终止服务器进程。未设置时，不适用超时
`restartOnCrash`	No	服务器崩溃后是否重新启动。默认为 `true`。设置为 `false` 以使崩溃的服务器停止而不是重新启动
`maxRestarts`	No	放弃前的重新启动尝试，零或更多
`diagnostics`	No	编辑后是否将诊断推送到上下文。默认为 `true`

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

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

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

`monitors`

experimental.monitors 采用 .json 文件路径或内联数组。当您省略该键时，Claude Code 加载 monitors/monitors.json（如果存在）。每个条目是具有这些字段的严格对象。

字段	必需	描述
`name`	Yes	在 plugin 内唯一的标识符
`command`	Yes	Claude Code 在会话工作目录中作为持久后台进程运行的 shell 命令
`description`	Yes	在任务面板和通知摘要中显示的简短摘要
`when`	No	使用 `"always"`（默认），monitor 在会话启动和 plugin 重新加载时启动。使用 `"on-skill-invoke:<skill>"`，它在该 skill 首次运行时启动

此内联数组声明一个在 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

包含和存在

每个组件路径必须在 plugin 根目录内解析并且必须存在。claude plugin validate 不检查 outputStyles、lspServers、monitors 或 themes 路径，因此这些字段中的坏路径仅在 plugin 加载时失败：

包含：在 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

每个键如何与其默认位置结合

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

替换默认值：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。键是由字母、数字和下划线组成的标识符，不能以数字开头。每个值是具有这些字段的严格对象。未知键验证失败。

字段	必需	描述
`type`	Yes	`string`、`number`、`boolean`、`directory` 或 `file` 之一
`title`	Yes	在配置对话框中显示的标签
`description`	Yes	在字段下方显示的帮助文本
`required`	No	如果 `true`，配置对话框不接受空值
`default`	No	当用户不提供任何内容时使用的值：字符串、数字、布尔值或字符串数组
`options`	No	对于 `string`，字段接受的值，在 `/config` 中显示为选择器。参见将字段限制为固定选项。需要 Claude Code v2.1.271 或更高版本
`multiple`	No	对于 `string`，允许字符串数组
`sensitive`	No	如果 `true`，掩盖输入并将值存储在安全存储中而不是 `settings.json`
`min` / `max`	No	`number` 的边界

每个启用的 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。该表显示值如何可以到达这些字段。

字段	值如何到达它
Shell 形式 hook 命令	使用exec 形式与 `args`，或从 hook 的环境读取 `CLAUDE_PLUGIN_OPTION_<KEY>`
Monitor 命令	不通过 Claude Code。Monitor 进程不接收 `CLAUDE_PLUGIN_OPTION_<KEY>`，因此 monitor 脚本必须自己获取值
MCP `headersHelper`	不通过 Claude Code。helper 的环境携带 `CLAUDE_PLUGIN_ROOT`、`CLAUDE_CODE_MCP_SERVER_NAME` 和 `CLAUDE_CODE_MCP_SERVER_URL` 但没有选项值，因此 helper 脚本必须自己获取值

频道

channels 声明 plugin 提供的消息频道，例如到聊天应用的桥接。当您声明一个时，Claude Code 可以在 plugin 启用时提示频道的配置。有关服务器如何注入消息，参见频道参考。每个条目是绑定到 plugin 的 MCP 服务器之一的严格对象，具有这些字段：

字段	必需	描述
`server`	Yes	此 plugin 的 `mcpServers` 中频道绑定到的 MCP 服务器的键
`displayName`	No	在配置对话框标题中显示的名称。默认为服务器名称
`userConfig`	No	要提示的选项，形状与顶级 `userConfig`相同。保存的值替换到服务器 `env` 中的 `${user_config.KEY}` 引用

此 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_PLUGIN_DATA}`	`~/.claude/plugins/data/<id>/`，在首次引用时创建并在 plugin 更新中保留。`<id>` 是 plugin 标识符，其中除字母、数字、`_` 或 `-` 外的每个字符都被替换为 `-`	已安装的依赖项（如 `node_modules`）、生成的代码和缓存
`${CLAUDE_PROJECT_DIR}`	项目根目录	项目本地脚本和配置文件

${CLAUDE_PLUGIN_ROOT} 在 plugin 更新时改变，因此不要在那里写入状态。有关根目录移动的位置和旧目录何时被清理，参见加载页面。当您从最后一个安装它的地方卸载 plugin 时，${CLAUDE_PLUGIN_DATA} 目录被删除，除非您传递 --keep-data。

每个变量解析的位置

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

Plugin 组件	`${...}` 解析的字段	导出到进程
Hook 命令	在 `command` 和 `args` 中的任何地方	`CLAUDE_PLUGIN_ROOT`、`CLAUDE_PLUGIN_DATA`、`CLAUDE_PROJECT_DIR` 和 `CLAUDE_PLUGIN_OPTION_<KEY>`
Monitor 命令	在 `command` 中的任何地方	未导出
MCP `stdio` 服务器	`command`、`args`、`env`	`CLAUDE_PLUGIN_ROOT`、`CLAUDE_PLUGIN_DATA`
MCP `http`、`sse`、`ws` 服务器	`url`、`headers`、`headersHelper`	不适用
LSP 服务器	`command`、`args`、`env`、`workspaceFolder`	`CLAUDE_PLUGIN_ROOT`、`CLAUDE_PLUGIN_DATA`、`CLAUDE_PROJECT_DIR`
Skill、command 和 agent 内容	Markdown 体中的任何地方	不适用

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

引用和路径分隔符

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

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

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

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

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

标准布局

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

组件	默认位置	内容
Manifest	`.claude-plugin/plugin.json`	Plugin 元数据和配置。可选
Skills	`skills/`	每个 skill 一个 `<name>/SKILL.md`。具有 `SKILL.md` 在其根目录、没有 `skills/` 和没有 `skills` 键的 plugin 加载为单个 skill
Commands	`commands/`	平面 Markdown 命令文件。对于新 plugin 更喜欢 `skills/`
Agents	`agents/`	Agent Markdown 文件。子文件夹是agent 名称的一部分
Hooks	`hooks/hooks.json`	Hook 配置
MCP 服务器	`.mcp.json`	MCP 服务器定义
LSP 服务器	`.lsp.json`	LSP 服务器配置
输出样式	`output-styles/`	输出样式 Markdown 文件
Workflows	`workflows/`	Workflow `.js` 文件
主题	`themes/`	主题 JSON 文件
Monitors	`monitors/monitors.json`	monitors 数组
可执行文件	`bin/`	此处的文件在 plugin 启用时位于 Bash 工具的 `PATH` 上，因此 Claude 将它们作为裸命令运行。claude.ai 和 Cowork 不安装具有此目录的 plugin，包括您通过 claude.ai 组织设置分发的 plugin
设置	`settings.json`	在 plugin 启用时应用的 `agent` 和 `subagentStatusLine` 默认值

使用每个默认位置的 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

marketplace 条目接受此页面上的每个字段以及其自己的字段，包括 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 故障排除：每条验证消息及其修复

​Manifest 文件

​无法识别的字段

​验证 manifest

​字段

​name

​displayName

​version

​metadata

​defaultEnabled

​dependencies

​settings

​组件路径形式

​仅路径字段

​commands

​hooks

​mcpServers

​lspServers

​monitors

​路径规则

​包含和存在

​每个键如何与其默认位置结合

​用户配置

​将字段限制为固定选项

​值的存储位置

​引用保存的值

​通过 shell 运行的字段

​频道

​环境变量

​每个变量解析的位置

​引用和路径分隔符

​标准布局

​Marketplace 条目和 manifest

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

​元数据优先级

​后续步骤

Manifest 文件

无法识别的字段

验证 manifest

字段

`name`

`displayName`

`version`

`metadata`

`defaultEnabled`

`dependencies`

`settings`

组件路径形式

仅路径字段

`commands`

`hooks`

`mcpServers`

`lspServers`

`monitors`

路径规则

包含和存在

每个键如何与其默认位置结合

用户配置

将字段限制为固定选项

值的存储位置

引用保存的值

通过 shell 运行的字段

频道

环境变量

每个变量解析的位置

引用和路径分隔符

标准布局

Marketplace 条目和 manifest

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

元数据优先级

后续步骤