Marketplace 参考

marketplace.json 字段、插件条目和插件及 marketplace 源对象的完整参考，包括每个字段的有效位置。

marketplace.json 是定义插件 marketplace 的文件。它包含 marketplace 的名称、所有者和每个插件的一个条目。每个条目的插件源说明 Claude Code 从哪里获取该插件。

marketplace 源是一个单独的对象，说明 Claude Code 从哪里获取 marketplace 文件本身。你在设置中编写一个，或者当你运行 claude plugin marketplace add 时 Claude Code 会构建一个。

本参考适用于需要确切字段名称或值的 marketplace 维护者，以及需要了解哪些 source 值在 extraKnownMarketplaces、strictKnownMarketplaces 和 blockedMarketplaces 中有效的管理员。

查找你正在编写或读取的内容的部分：

• marketplace 文件：顶级字段 和 插件条目
• 条目的 source：插件源
• 设置中的 source 对象：Marketplace 源
• 来自 claude plugin validate <path> 的输出：验证消息，它将每条消息映射到它命名的字段

Marketplace 文件

将 marketplace 文件保存在 marketplace 目录中的 .claude-plugin/marketplace.json。如果你将文件保存在存储库中的其他位置，用户必须在 extraKnownMarketplaces 中声明 marketplace，并在其源上设置 path，因为 claude plugin marketplace add 没有该选项。

包含 .claude-plugin/ 的目录称为 marketplace 根目录，每个相对插件源都从它解析，而不是从 .claude-plugin/。

每个用户为每个 name 注册一个 marketplace，因此用户不能同时注册两个同名的 marketplace。

Claude Code 忽略未知的顶级键或插件条目键，而不是拒绝它，因此拼写错误会静默加载。claude plugin validate 将每个未知键报告为警告。

保留名称

你不能给你的 marketplace 以下任何名称：

• 官方 marketplace 名称：claude-code-marketplace、claude-code-plugins、claude-plugins-official、anthropic-marketplace、anthropic-plugins、agent-skills、anthropic-agent-skills、life-sciences、knowledge-work-plugins、claude-for-legal、claude-for-financial-services、financial-services-plugins、first-party-plugins 和 claude-tag-plugins。除非 marketplace 来自 github.com/anthropics/ 下的 github 或 git marketplace 源，否则保留。
• 社区 marketplace 名称：claude-community、claude-plugins-community 和 healthcare。保留规则与官方名称相同。
• 插件目录名称：anthropic-plugin-directory 和 claude-plugin-directory。保留规则与官方名称相同。
• 冒充官方 marketplace 的名称：名称如 official-claude-plugins 或 claude-plugins-v2，以及任何包含非 ASCII 字符的名称。错误是 Marketplace name impersonates an official Anthropic/Claude marketplace。名称中的控制或双向格式化字符也会报告 Marketplace name cannot contain control or bidirectional-formatting characters。
• 保留名称的另一种拼写：与保留名称仅在尾部点或用除下划线以外的符号代替连字符的名称，因此 claude.code.plugins 计为 claude-code-plugins。claude plugin validate 接受这样的名称；添加 marketplace 失败，错误为 is another spelling of "<reserved>", a reserved marketplace name，已在一个下注册的 marketplace 停止加载。此检查需要 Claude Code v2.1.280 或更高版本。
• Claude Code 用于不来自 marketplace 的插件的名称：inline 用于使用 --plugin-dir 加载的插件，builtin 用于内置插件，skills-dir 用于从 .claude/skills/ 自动加载的插件，synced 用于从你的 claude.ai 账户同步的插件。claude-plugin-test 也被保留。skills-dir 也显示为 {"source": "skills-dir"}，在 strictKnownMarketplaces 和 blockedMarketplaces 中，如 仅在策略列表中有效的源值 下所述。
• npm、pip、uv、cargo、github 和 gh：以任何大小写保留。此检查需要 Claude Code v2.1.275 或更高版本。
• 以 claudeai- 开头的名称：为托管在 claude.ai 上的 marketplace 保留。claude plugin marketplace add 拒绝任何其他使用一个的 marketplace，错误为 Cannot add marketplace "<name>": names starting with "claudeai-" are reserved for marketplaces hosted on claude.ai。

顶级字段

该表列出 Claude Code 从 marketplace.json 读取的每个键。name、owner 和 plugins 是必需的。

插件条目

marketplace.json 的顶级 plugins 数组中的每个对象命名一个插件并说明从哪里获取它。name 和 source 是必需的。

条目也接受每个 plugin.json 字段，如 description、version、author、commands 和 hooks。有关这些字段何时适用，请参阅 条目如何与 plugin.json 结合。

该表列出条目自己的字段和清单字段，其含义在条目中改变。

条目如何与 plugin.json 结合

条目的字段对获取的具有自己的 .claude-plugin/plugin.json 的插件和没有的插件的应用方式不同：

• 没有 plugin.json：条目是清单，无论 strict 如何。条目中的每个清单字段都适用，包括 mcpServers、lspServers、userConfig 和 channels。
• plugin.json 存在：plugin.json 是清单。严格模式 决定条目的六个组件字段 commands、agents、skills、hooks、outputStyles 和 themes 是与其结合还是作为冲突被拒绝。条目 mcpServers、lspServers、userConfig 和 channels 不适用。在 plugin.json 中声明它们。

条目中的 Hooks

将条目 hooks 写成内联对象，将 hook 事件名称映射到匹配器数组。如果你写文件路径或数组，claude plugin validate 会通过。这些 hooks 永远不会运行，Claude Code 为插件报告 not yet supported in a marketplace entry 错误。将基于文件的 hooks 放在插件自己的 hooks/hooks.json 或 plugin.json 中。

显示字段

条目和插件自己的 plugin.json 都可以设置显示字段 displayName、description、author、homepage、repository、license 和 keywords。用户在插件列表和详情中看到这些值，在安装前后：

• 对于你在条目上设置的字段，用户看到条目的值，即使 plugin.json 设置了不同的值。
• 对于条目未设置的字段，用户看到 plugin.json 值。

在安装前，Claude Code 只能为具有 相对路径源 的条目读取 plugin.json，其插件文件在 marketplace 内。对于具有任何其他源类型的条目，用户在安装插件之前只看到条目自己的字段。

严格模式

strict 决定当获取的插件具有自己的 plugin.json 且条目也声明任何 组件字段 时会发生什么：commands、agents、skills、hooks、outputStyles 或 themes。使用 strict: true（默认值），Claude Code 将条目的组件字段附加到 plugin.json，除了 hooks，其匹配器替换清单的每个事件。使用 strict: false，声明任何组件字段的条目是冲突，插件加载失败。该表显示 strict、plugin.json 和条目的组件字段的每个组合。

Plugin sources

一个插件条目的 source 说明 Claude Code 从哪里获取该插件。它要么是一个相对路径字符串，要么是一个对象，其自身的 source 键命名类型，所以一个条目看起来像 "source": { "source": "github", "repo": "your-org/formatter" }。

该表列出了每种插件源类型及其字段。

名称 url 和 github 也是marketplace 源类型，其中 url 表示直接链接到 marketplace.json 文件而不是 git 仓库。git 仅作为 marketplace 源存在，npm 既作为 marketplace 源也作为插件源存在。git-subdir、archive 和 command 仅作为插件源存在。

对于 marketplace 仓库本身的子目录中的插件，使用相对路径。对于其他仓库的子目录，使用 git-subdir。

github、url 和 git-subdir 源共享 ref 和 sha 字段：

• ref：一个分支或标签。默认为仓库的默认分支。
• sha：一个完整的 40 字符小写提交 SHA。当你同时设置 ref 和 sha 时，Claude Code 检出 sha。在大多数 git 主机上，包括 GitHub、GitLab 和 Bitbucket，这意味着即使上游的分支或标签已被删除，只要提交仍然可从仓库到达，安装就会成功。某些服务器（如 AWS CodeCommit）不支持按 SHA 获取提交。在这些服务器上，ref 必须仍然存在，固定的提交必须可从它到达。

有关每种类型如何获取、缓存和版本化的信息，请参阅 Plugin loading reference。

Relative path plugin source

路径从 marketplace 根目录解析。./plugins/formatter 是 <root>/plugins/formatter，即使 marketplace 文件在 <root>/.claude-plugin/ 中。

包含 .. 的路径会验证失败。在 macOS 和 Linux 上，Claude Code 拒绝条目路径在前导 ./ 之后的任何地方包含反斜杠，所以用正斜杠写路径。

{ "name": "formatter", "source": "./plugins/formatter" }

相对路径仅在 Claude Code 拥有 marketplace 文件时才能解析，所以检查 marketplace 源类型：

• github、git、file 和 directory：Claude Code 拥有 marketplace 的文件。
• url：Claude Code 仅获取 marketplace.json，所以相对路径无法解析。给每个插件一个对象源，如 github 或 git-subdir。
• settings：相对路径被直接拒绝。

Bare names under pluginRoot

裸名是一个没有 / 的单个目录名，如 "formatter"。要写裸名而不是 ./ 路径，设置 metadata.pluginRoot 为它们解析的目录。使用 "pluginRoot": "./plugins"，"source": "formatter" 解析为 ./plugins/formatter。需要 Claude Code v2.1.239 或更高版本。

metadata.pluginRoot 有这些限制：

• 它本身必须是 marketplace 内的相对路径。
• 它对已经以 ./ 开头的源没有影响。
• 包含 / 的源，如 team-a/formatter，不是裸名，即使设置了 metadata.pluginRoot 也仍然需要 ./ 前缀。

github plugin source

repo 采用 owner/repo 格式。ref 和 sha 是可选的。

{
  "name": "formatter",
  "source": {
    "source": "github",
    "repo": "your-org/formatter",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

url plugin source

url 是一个完整的 git URL：https://、http://、file:// 或 git@。不需要 .git 后缀，所以 Azure DevOps 和 AWS CodeCommit URL 可以按原样工作。此类型不采用 owner/repo 简写。

{
  "name": "formatter",
  "source": {
    "source": "url",
    "url": "https://gitlab.example.com/your-group/formatter.git",
    "ref": "main"
  }
}

git-subdir plugin source

url 接受完整的 git URL 或 GitHub owner/repo 简写。path 是保存插件的子目录，Claude Code 仅下载该子目录。

{
  "name": "formatter",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/your-org/monorepo.git",
    "path": "tools/formatter"
  }
}

npm plugin source

一个 npm 源采用这些字段：

• package：一个包名，或一个作用域名，如 @your-org/formatter
• version：一个版本或范围
• registry：一个不在默认 registry 上的包的 registry URL

Claude Code 使用你的 npm 客户端获取包。包的安装脚本，如 preinstall 或 postinstall，永远不会运行，其依赖项在获取期间不会被安装。如果包在其 package.json 旁边有一个支持的 lockfile，Claude Code 在单独的步骤中安装这些 Node.js 包依赖项，也禁用脚本。

{
  "name": "formatter",
  "source": {
    "source": "npm",
    "package": "@your-org/formatter",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}

archive plugin source

url 必须使用 https://，不能指向环回、链接本地或云元数据主机。

插件根可能在 zip 的顶部或下一个目录。

sha256 是存档的摘要，为 64 个十六进制字符，大写或小写。当你设置它时，Claude Code 拒绝不匹配的下载。

{
  "name": "formatter",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/formatter-2.0.0.zip",
    "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1"
  }
}

command plugin source

当安装在用户机器上的工具生成插件目录时，使用 command 源，如一个为用户选择的工具链呈现其插件的 IDE。Claude Code 在用户安装或更新插件时运行该命令，并每个会话再运行一次，所以用户无需重新安装就能获得工具的更改输出。

一个 command 源采用这些字段：

• command：一个 shell 命令，打印插件目录的绝对路径作为一行并退出 0。Claude Code 在运行前向用户显示整个字符串以供审查。将其写为可打印的 ASCII，最多 500 个字符，没有四个或更多空格的连续。
• timeout：从 1 到 600 的整数秒数。默认为 60。
• mode：copy（默认）或 link。参见 Copy mode and link mode。

{
  "name": "formatter",
  "source": {
    "source": "command",
    "command": "my-tool claude-plugin-path",
    "timeout": 120
  }
}

有关用户如何接受命令的信息，请参阅 Install from your shell。有关你更改它后用户看到的内容，请参阅 Change the command of a command source。管理员使用 disableCommandPluginSources 关闭命令源。

What the command must do

编写命令以满足这些要求：

• Shell 和工作目录：Claude Code 通过 sh 运行命令，或在 Windows 上通过 cmd.exe，从用户的主目录。给出绝对路径或 PATH 上的命令。
• 输出：在 stdout 上打印恰好一行，插件目录的绝对路径，并在 timeout 秒内退出 0。
• 目录内容：该目录在命令退出时保存完整的插件。路径可能因运行而异。

Output that fails the install or update

当命令退出非零、运行时间超过 timeout 或打印除一个绝对路径之外的任何内容时，安装或更新失败。当打印的目录是以下之一时，它也会失败：

• 没有插件内容：打印的目录在其顶级没有插件内容，如 .claude-plugin/ 目录或 skills/、commands/、agents/ 或 hooks/ 目录。
• 会话自己的目录：打印的目录是 Claude Code 启动的目录，或其父目录之一。
• 网络路径：在 Windows 上，打印的路径是 UNC 路径。
• 太大而无法复制：在复制模式下，目录大于 256 MiB 或有超过 20,000 个条目。

Copy mode and link mode

mode 决定 Claude Code 是复制打印的目录还是就地使用它：

• copy：Claude Code 将目录复制到插件缓存中，并从复制文件的哈希值派生插件版本。你的工具可以在命令退出后删除或重写目录。产生相同文件的重新运行计为最新。
• link：Claude Code 用指向打印目录的每个顶级条目的链接填充插件的缓存条目，并就地加载文件。不复制任何内容，文件内容不被哈希，大小限制不适用。对于太大而无法复制的目录（如呈现的 SDK 导出），使用它。

链接模式插件有这些要求：

• 保持目录就位：Claude Code 在每次启动时通过链接加载插件，所以打印的目录必须保持在原位，只要插件保持安装。
• 打印不同的路径以表示新内容：版本来自打印目录的真实路径及其顶级条目，而不是其中的文件。
• 保持顶级符号链接在目录内：如果顶级条目是指向打印目录外的符号链接，安装失败。
• 包含 node_modules：Claude Code 跳过链接模式插件的 Node.js 包依赖项安装，所以打印一个已经包含插件需要的包的目录。
• 在目录内启动的会话：在打印目录或其下方任何地方启动的会话不加载插件。
• 不在 Windows 上：Claude Code 拒绝在 Windows 上安装链接模式插件。在那里声明 "mode": "copy"。

Marketplace 源

marketplace 源说明 Claude Code 从哪里获取 marketplace.json。CLI 在你添加 marketplace 时为你构建一个，你在设置中自己编写一个：

• claude plugin marketplace add：Claude Code 从你传递的字符串构建源。
• extraKnownMarketplaces：你自己将源写成 source 对象。
• strictKnownMarketplaces 和 blockedMarketplaces：管理员在这两个策略列表中编写源。strictKnownMarketplaces 是允许列表，blockedMarketplaces 是阻止列表。

类型名称 url、git 和 github 在 marketplace 源中的含义与在 插件源 中不同：

该表列出每个 marketplace 源类型及其字段、产生它的 claude plugin marketplace add 输入，以及它在三个设置键中的作用。

按类型的字段

该表列出每个具有默认值、约束或特定于其类型的含义的 marketplace 源字段。

仅在策略列表中有效的源值

hostPattern、pathPattern、skills-dir 和 repo 的 owner/* 形式仅在两个策略列表中有效，strictKnownMarketplaces 和 blockedMarketplaces：

• hostPattern 和 pathPattern：Claude Code 在获取前针对源测试的正则表达式。
• skills-dir：不是源。如果你设置 strictKnownMarketplaces，skills-directory 插件 停止加载，直到你将 {"source": "skills-dir"} 添加到该列表。
• owner/*：作为 github repo 值，匹配恰好该 GitHub 所有者下的每个存储库。需要 Claude Code v2.1.223 或更高版本。

有关匹配顺序、精确 ref 语义和配方，请参阅 为你的组织管理插件。

设置中的源对象

extraKnownMarketplaces 值是从 marketplace 名称到具有 source 的对象的映射。此条目从其 main 分支的 git 存储库注册 marketplace：

{
  "extraKnownMarketplaces": {
    "your-marketplace": {
      "source": {
        "source": "git",
        "url": "https://git.example.com/your-org/your-marketplace.git",
        "ref": "main"
      }
    }
  }
}

strictKnownMarketplaces 和 blockedMarketplaces 是源对象的数组。此允许列表允许一个 GitHub 所有者和一个内部主机：

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "your-org/*" },
    { "source": "hostPattern", "hostPattern": "^git\\.example\\.com$" }
  ]
}

验证消息

claude plugin validate <path> 接受 marketplace 根目录或 marketplace 文件本身。它打印错误和警告。有关退出代码和 --strict，请参阅 plugin validate。

消息通过索引命名插件条目，写作 plugins.1.source 或 plugins[1].source。

以条目索引和 plugin.json → 为前缀的消息，例如 plugins[2] plugin.json →，涉及该插件自己的文件。claude plugin validate 报告错误 列出这些消息及其修复。

提及 Claude Desktop 标志名称的警告，这些名称 Claude Code 接受但 Claude Desktop 拒绝，因为 Claude Desktop 的名称规则更严格。

该表将 marketplace 级别的消息映射到每个消息所涉及的字段。

Invalid input on a source

source 上的 Invalid input 意味着该对象与任何源类型都不匹配。检查这些原因：

• 不以 ./ 开头的相对路径，除了 "." 或 metadata.pluginRoot 下的裸名称
• 包含 .. 的 npm package
• 不是 plugin sources 之一的 source 类型
• 已知类型缺少必需字段或字段类型错误，例如没有 repo 的 github

验证未捕获的失败

claude plugin validate 不会报告每个失败。写作文件路径或数组的条目 hooks 通过验证，错误仅在插件加载时出现，如 Hooks in an entry 所述。获取 source 的错误也仅在安装后出现，不在验证中出现。

claude plugin list 显示加载失败的插件及其错误，Troubleshoot plugins 涵盖加载时字符串。

后续步骤

• 创建 marketplace：从这些字段构建 marketplace 并在本地安装
• 托管和维护 marketplace：放置文件的位置以及用户如何接收更改
• 插件清单参考：条目可以覆盖的 plugin.json 字段
• 为你的组织管理插件：使用这些源值的允许列表和阻止列表配方