Marketplace 参考

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

​

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。已在这样的名称下注册的 marketplace 停止加载，连同其插件。
• 保留名称的另一种拼写：仅因尾部的点，或因用除下划线以外的符号代替连字符，而与保留名称不同的名称，因此 claude.code.plugins 计为 claude-code-plugins。添加 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 或更高版本。
• 每个 JavaScript 对象都具有的成员名称：constructor、hasOwnProperty、isPrototypeOf、propertyIsEnumerable、toLocaleString、toString 和 valueOf。claude plugin marketplace add 会拒绝使用其中之一的市场，错误为 Claude Code reserves this name and cannot register a marketplace under it。此检查需要 Claude Code v2.1.296 或更高版本。
• 以 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。
• 已注册 GitHub 市场的下载文件夹名称 <owner>-<repo>：对于从 github 源（例如 acme/x-tools）添加的市场，无论该市场自身的 name 是什么，Claude Code 都会通过名为 acme-x-tools 的文件夹下载它。当该市场以 acme-x-tools 以外的名称注册时，claude plugin marketplace add 会在下载另一个名为 acme-x-tools 的市场后拒绝它，并报告 Can't use the marketplace name "acme-x-tools"。此检查需要 Claude Code v2.1.290 或更高版本。

​

顶级字段

​

插件条目

​

条目如何与 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

​

显示字段

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

​

严格模式

​

Plugin sources

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

​

Relative path plugin source

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

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

​

Git submodules in the marketplace repository

• 插件位于子模块内：子模块是插件的目录或其上级目录
• 子模块位于插件内：子模块位于插件目录下的任意位置
• 符号链接指向子模块内部：提交到仓库的链接的目标位于子模块中

• 组件目录：根目录下存放插件组件的目录，如 skills/、hooks/ 或 bin/
• 插件配置中的路径：插件的市场条目、其 plugin.json 或配置文件（如 .mcp.json 或 hooks/hooks.json）中的路径
• 符号链接：提交到仓库的链接
• 插件文件中的文本：写在配置文件中或组件目录下某个文件中的子模块路径，如 vendor/tool

• 根目录下的 SKILL.md：此时整个仓库就是一个 skill 的目录
• Claude Code 无法读取的文件：市场文件、插件的某个配置文件或 .gitmodules

​

Bare names under pluginRoot

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

​

github plugin source

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

​

url plugin source

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

​

git-subdir plugin source

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

​

npm plugin source

• package：一个 registry 包名，如 @your-org/formatter；一个附加了版本的名称，如 @your-org/formatter@2.0.0；或一个指向包 tarball 文件的 https 链接
• version：一个版本、一个 semver 范围或一个 dist-tag，在 package 是未附加版本的包名时使用。省略它则获取 latest
• registry：一个不在默认 registry 上的包的 registry URL

• git 地址、文件夹或 file: 路径，或 npm: 别名：对于 git 仓库，请使用 github、url 或 git-subdir 源；对于市场中的文件夹，请使用相对路径；对于别名，请使用包自身的名称
• 位于 github.com、gist.github.com、gitlab.com、bitbucket.org 或 git.sr.ht 上的 tarball 链接：即使该链接是 GitHub release 下载链接也会被拒绝，除非它是 gitlab.com/api/v4/ 下的 GitLab npm registry 链接
• 通过 http 的 tarball 链接：除非它指向安装用户自己的默认 npm registry，否则会被拒绝

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

​

archive plugin source

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

​

command plugin source

• 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
  }
}

​

What the command must do

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

​

Output that fails the install or update

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

​

Copy mode and link mode

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

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

​

Marketplace 源

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

​

按类型的字段

​

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

• hostPattern 和 pathPattern：Claude Code 在获取前针对源测试的正则表达式。
• skills-dir：不是源。如果您设置了 strictKnownMarketplaces 但其中没有 {"source": "skills-dir"} 条目，skills-directory 插件将停止加载。如果您使用 strictPluginOnlyCustomization 锁定了任何自定义类型，无论该条目是否存在，它们都会停止加载。
• owner/*：作为 github repo 值，匹配恰好该 GitHub 所有者下的每个存储库。需要 Claude Code v2.1.223 或更高版本。

​

设置中的源对象

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

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

​

验证消息

​

Invalid input on a source

• 包含 .. 的 npm package
• 不是 plugin sources 之一的 source 类型
• 已知类型缺少必需字段或字段类型错误，例如没有 repo 的 github

​

验证未捕获的失败

​

后续步骤

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