创建一个 marketplace

从 marketplace.json 文件构建一个 plugin marketplace，并在托管之前在本地测试它。

plugin marketplace 是一个目录或仓库，包含一个 .claude-plugin/marketplace.json 文件，该文件列出你的 plugins 以及从哪里获取每一个。你将目录推送到 git 主机，任何有权限的人都可以用一个命令在 Claude Code 中注册它，并从中安装你的 plugins。

当你想让一个你选择的群体（例如你的团队或组织）安装你的 plugins 并继续从你控制的目录接收更新时，创建你自己的 marketplace。该仓库可以是私有的，可以列出任意数量的 plugins，管理员可以在每台机器上要求它。

从创建一个 marketplace 开始，在你自己的机器上构建一个并从中安装一个 plugin，然后添加更多 plugin 条目。

创建一个 marketplace

以下步骤在你的机器上创建一个 marketplace，向其中添加一个 plugin，在 Claude Code 中注册它，并从中安装该 plugin。这是整个循环，也是你的用户一旦你在他们可以访问的地方托管 marketplace 后所经历的相同循环。从你想要创建 my-marketplace/ 的目录在你的 shell 中运行每个命令。

你需要一个 plugin 来列出。该示例使用来自创建你的第一个 plugin 的 my-first-plugin，这是一个具有一个 skill 的 plugin，你可以将其作为 /my-first-plugin:hello 运行；如果你还没有 plugin，请先构建它。要使用你自己的 plugin，请在步骤说 my-first-plugin 的地方替换其目录和其 name。有关 plugin 目录可以包含的内容，请参阅plugin 目录浏览器。

mkdir -p my-marketplace/.claude-plugin my-marketplace/plugins
cp -r my-first-plugin my-marketplace/plugins/

claude plugin validate ./my-marketplace/plugins/my-first-plugin

{
"name": "my-marketplace",
"description": "Plugins for my team",
"owner": {
"name": "Your Name"
},
"plugins": [
{
"name": "my-first-plugin",
"source": "./plugins/my-first-plugin",
"description": "A greeting plugin to learn the basics"
}
]
}

claude plugin validate ./my-marketplace

claude plugin marketplace add ./my-marketplace

claude plugin install my-first-plugin@my-marketplace

claude plugin list

claude plugin details my-first-plugin

添加 plugin 条目

你分发的每个 plugin 都是 marketplace.json 的 plugins 数组中的一个对象。要添加第二个 plugin，请添加第二个对象。这些字段涵盖了大多数条目：

• name：人们在安装时在 @ 之前输入的标识符。它不能包含空格。
• source：Claude Code 从哪里获取 plugin。对于 marketplace 目录内的 plugin，写一个相对路径字符串，如演练中所示，或对于目录外的 plugin，写一个源对象。请参阅选择 plugin 源。
• description：人们在 /plugin 中浏览你的 marketplace 时在 plugin 旁边看到的行。

有关完整的字段列表，请参阅Plugin 条目。

条目也可以设置任何 plugin.json 字段。有关条目的 plugin.json 字段何时应用于具有自己的 plugin.json 的 plugin，请参阅条目和 plugin.json。

Plugin 条目的规则

来自新 marketplace 的大多数失败安装来自于从错误目录编写的相对路径，或来自与 plugin 的 plugin.json 中的 name 不同的条目名称。

从 marketplace 根目录编写相对路径

marketplace 根目录是包含 .claude-plugin/ 的目录。在演练中，那是 my-marketplace/，所以条目的 source 是 "./plugins/my-first-plugin"。该路径不是从 .claude-plugin/ 内部开始的，所以不要使用 .. 来离开它。

包含 .. 的路径和指向不存在目录的路径在不同的命令处失败：

• 包含 .. 的路径：claude plugin validate 将条目报告为无效。消息以 Path contains "..": ./../plugins/my-first-plugin 开头。
• 指向不存在目录的路径：claude plugin validate 通过。claude plugin install 失败，显示 Source path does not exist: <path>，其中 <path> 是 Claude Code 检查的绝对位置。

保持条目名称和清单名称相同

marketplace plugin 在 marketplace.json 中有一个条目 name 和在其自己的 plugin.json 中有一个 name，称为清单名称。每个名称出现在不同的地方：

• 条目名称：安装 id，<entry-name>@<marketplace>。这是人们输入来安装的内容，claude plugin list 显示的内容，以及 Claude Code 在他们的设置文件中的 enabledPlugins 下写入的键。
• 清单名称：plugin 的 skills 上的前缀，以及 claude plugin details 接受的名称。

当两个名称不同且有人按清单名称安装时，Claude Code 报告 Plugin "<manifest-name>" not found in marketplace "<marketplace>"。保持两个名称相同。有关 Claude Code 如何使用这两个名称的更多信息，请参阅Plugin 加载参考。

选择 plugin 源

marketplace.json 中的每个 plugin 条目都有一个 source，告诉 Claude Code 从哪里获取那个 plugin。根据 plugin 文件的存储位置选择源。该表列出了大多数 marketplace 所有者使用的源。

在 git-subdir 源中，url 接受 git URL 或 owner/repo GitHub 简写。

plugin 也可以来自以下源类型之一：

• url：任何主机上的 git 仓库 URL
• archive：通过 HTTPS 下载的 zip 文件
• npm：npm 包
• command：通过在安装 plugin 的机器上运行命令生成的目录

有关每种源类型的字段，以及将基于 git 的源固定到 ref 或 sha，请参阅Plugin 源。

验证和测试

当你添加 plugins 时，在每次编辑后在你的 shell 中运行 claude plugin validate ./my-marketplace，并在分享之前从你自己机器上的 marketplace 安装。验证和安装会捕获不同的问题。

验证报告的问题

claude plugin validate 仅读取 marketplace 目录内的文件。它报告：

• JSON 语法错误，如 json: Invalid JSON syntax: <reason>
• 缺少必需字段，例如 owner: Invalid input
• 包含空格、非 ASCII 字符或模仿官方 Anthropic marketplace 形式的 marketplace 名称，例如 claude-official
• 包含 .. 的相对 source
• 顶级或 plugin 条目中的未知字段，作为警告
• 每个相对路径 plugin 的 plugin.json 中的问题，如 plugins[N] plugin.json → <field>: <message>

有关 validate 可以打印的每条消息，请参阅验证消息。有关其标志和退出代码，请参阅 plugin validate。

添加或安装时出现的问题

claude plugin validate 不报告的问题在你添加 marketplace 或从中安装时出现：

• 当你添加 marketplace 时：确切的官方 marketplace 名称，例如 claude-plugins-official，通过验证。当你添加具有其中一个名称的 marketplace 时，Claude Code 拒绝它，消息以 The name '<name>' is reserved for official Anthropic marketplaces 开头。
• 当你安装一个 plugin 时：
  • Claude Code 在你安装 plugin 时首先获取 github、git-subdir 或其他远程源，所以错误的 repo 或 path 会在那时出现。
  • 一个相对 source 的目录不存在也会在安装时失败，显示 Source path does not exist: <path>。

测试对 plugin 的编辑

在演练中，你从具有相对路径 source 的本地目录添加了 my-marketplace。使用该设置，Claude Code 直接从 my-marketplace/plugins/ 读取 plugin 的文件。你的编辑在下一个会话开始时或当你在会话中运行 /reload-plugins 时生效，无需更改 plugin 的 version。

从你托管的 marketplace 安装的人会在 plugin 缓存中获得一个副本。有关他们如何接收新版本，请参阅保持用户最新。

删除 marketplace 以重新开始

要删除所有内容并重新开始，在你的 shell 中运行 claude plugin marketplace remove my-marketplace。该命令删除 marketplace 并卸载其 plugins。

托管你的 marketplace

一旦你可以从你自己机器上的 marketplace 安装 plugin，如创建一个 marketplace 中所示，将 marketplace 目录推送到 git 主机。

你的队友然后在他们的 shell 中为 GitHub 仓库运行 claude plugin marketplace add <owner>/<repo>，或使用仓库 URL 运行相同的命令。然后他们按名称安装 plugin，如演练中所示。

有关私有仓库访问、更新、版本控制以及重命名或删除条目，请参阅托管和维护 marketplace。

后续步骤

• 托管和维护 marketplace：选择一个主机、保持用户最新并安全地重命名或删除 plugins
• Marketplace 参考：marketplace.json 字段和源类型
• 为你的组织管理 plugins：在每台机器上要求你的 marketplace 及其 plugins
• 按相关性建议 plugins：当会话匹配时，让 Claude Code 建议来自你的 marketplace 的 plugin