Claude Code 插件市场创建 - 团队 / 社区分发完整指南
构建和托管 plugin marketplace，以在团队和社区中分发 Claude Code 扩展——支持 GitHub、Git URL、本地路径和远程 URL。
plugin marketplace 是一个目录，让你能够将 plugins 分发给他人。Marketplace 提供集中式发现、版本跟踪、自动更新以及对多种源类型（git 存储库、本地路径等）的支持。本指南展示了如何创建自己的 marketplace，与你的团队或社区共享 plugins。
想要从现有 marketplace 安装 plugins？请参阅 发现和安装预构建的 plugins。
概述
创建和分发 marketplace 涉及：
- 创建 plugins：使用 skills、agents、hooks、MCP servers 或 LSP servers 构建一个或多个 plugins
- 创建 marketplace 文件：定义一个
marketplace.json，列出你的 plugins 及其位置 - 托管 marketplace：推送到 GitHub、GitLab 或其他 git 主机
- 与用户共享：用户使用
/plugin marketplace add添加你的 marketplace 并安装单个 plugins
一旦你的 marketplace 上线，你可以通过推送更改到你的存储库来更新它。用户使用 /plugin marketplace update 刷新他们的本地副本。
演练：创建本地 marketplace
此示例创建一个包含一个 plugin 的 marketplace：一个用于代码审查的 quality-review skill。
创建目录结构
mkdir -p my-marketplace/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/skills/quality-review
创建 skill
创建一个 SKILL.md 文件，定义 quality-review skill 的功能。
---
description: Review code for bugs, security, and performance
disable-model-invocation: true
---
Review the code I've selected or the recent changes for:
- Potential bugs or edge cases
- Security concerns
- Performance issues
- Readability improvements
Be concise and actionable.
创建 plugin manifest
创建一个 plugin.json 文件，描述该 plugin。
{
"name": "quality-review-plugin",
"description": "Adds a quality-review skill for quick code reviews",
"version": "1.0.0"
}
ℹ️ 设置
version意味着用户仅在你更改此字段时才会收到更新，因此在每次发布时都要提升版本号。如果你省略version并在 git 中托管此 marketplace，每次提交都会自动计为新版本。
创建 marketplace 文件
创建列出你的 plugin 的 marketplace 目录。
{
"name": "my-plugins",
"owner": {
"name": "Your Name"
},
"plugins": [
{
"name": "quality-review-plugin",
"source": "./plugins/quality-review-plugin",
"description": "Adds a quality-review skill for quick code reviews"
}
]
}
添加和安装
添加 marketplace 并安装 plugin。
/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@my-plugins
尝试一下
在编辑器中选择一些代码并运行你的新 skill。Plugin skills 使用 plugin 名称进行命名空间划分。
/quality-review-plugin:quality-review
要了解更多关于 plugins 可以做什么的信息，包括 hooks、agents、MCP servers 和 LSP servers，请参阅 Plugins。
ℹ️ plugins 如何安装：当用户安装 plugin 时，Claude Code 将 plugin 目录复制到缓存位置。这意味着 plugins 无法使用
../shared-utils之类的路径引用其目录外的文件，因为这些文件不会被复制。
创建 marketplace 文件
在你的存储库根目录中创建 .claude-plugin/marketplace.json。此文件定义你的 marketplace 的名称、所有者信息以及包含其源的 plugins 列表。
每个 plugin 条目至少需要一个 name 和 source（从哪里获取它）。
{
"name": "company-tools",
"owner": {
"name": "DevTools Team",
"email": "devtools@example.com"
},
"plugins": [
{
"name": "code-formatter",
"source": "./plugins/formatter",
"description": "Automatic code formatting on save",
"version": "2.1.0",
"author": {
"name": "DevTools Team"
}
},
{
"name": "deployment-tools",
"source": {
"source": "github",
"repo": "company/deploy-plugin"
},
"description": "Deployment automation tools"
}
]
}
Marketplace 架构
必需字段
| 字段 | 类型 | 描述 | 示例 |
|---|---|---|---|
name | string | Marketplace 标识符（kebab-case，无空格） | "acme-tools" |
owner | object | Marketplace 维护者信息 | |
plugins | array | 可用 plugins 列表 | 见下文 |
ℹ️ 保留名称：以下 marketplace 名称为 Anthropic 官方使用保留：
claude-code-marketplace、claude-code-plugins、claude-plugins-official、anthropic-marketplace、anthropic-plugins、agent-skills、knowledge-work-plugins、life-sciences。
所有者字段
| 字段 | 类型 | 必需 | 描述 |
|---|---|---|---|
name | string | 是 | 维护者或团队的名称 |
email | string | 否 | 维护者的联系电子邮件 |
可选字段
| 字段 | 类型 | 描述 |
|---|---|---|
$schema | string | 用于编辑器自动完成和验证的 JSON Schema URL |
description | string | 简短的 marketplace 描述 |
version | string | Marketplace 清单版本 |
metadata.pluginRoot | string | 前置到相对 plugin 源路径的基目录 |
allowCrossMarketplaceDependenciesOn | array | 此 marketplace 中的 plugins 可能依赖的其他 marketplaces |
Plugin 条目
plugins 数组中的每个 plugin 条目描述一个 plugin 及其位置。
必需字段
| 字段 | 类型 | 描述 |
|---|---|---|
name | string | Plugin 标识符（kebab-case，无空格） |
source | string|object | 从哪里获取 plugin |
可选 plugin 字段
标准元数据字段：
| 字段 | 类型 | 描述 |
|---|---|---|
description | string | 简短的 plugin 描述 |
version | string | Plugin 版本 |
author | object | Plugin 作者信息 |
homepage | string | Plugin 主页或文档 URL |
repository | string | 源代码存储库 URL |
license | string | SPDX 许可证标识符 |
keywords | array | 用于 plugin 发现和分类的标签 |
category | string | Plugin 类别以供组织 |
tags | array | 用于可搜索性的标签 |
strict | boolean | 控制 plugin.json 是否是组件定义的权威（默认：true） |
Plugin 源
Plugin 源告诉 Claude Code 在你的 marketplace 中列出的每个单独 plugin 从哪里获取。
| 源 | 类型 | 字段 | 注释 |
|---|---|---|---|
| 相对路径 | string（例如 "./my-plugin"） | 无 | marketplace repo 中的本地目录。必须以 ./ 开头 |
github | object | repo、ref?、sha? | |
url | object | url、ref?、sha? | Git URL 源 |
git-subdir | object | url、path、ref?、sha? | git repo 中的子目录 |
npm | object | package、version?、registry? | 通过 npm install 安装 |
相对路径
对于同一存储库中的 plugins，使用以 ./ 开头的路径：
{
"name": "my-plugin",
"source": "./plugins/my-plugin"
}
ℹ️ 相对路径仅在用户通过 Git（GitHub、GitLab 或 git URL）添加你的 marketplace 时有效。如果用户通过直接 URL 添加你的 marketplace 到
marketplace.json文件，相对路径将无法正确解析。
GitHub 存储库
{
"name": "github-plugin",
"source": {
"source": "github",
"repo": "owner/plugin-repo"
}
}
你可以固定到特定的分支、标签或提交：
{
"name": "github-plugin",
"source": {
"source": "github",
"repo": "owner/plugin-repo",
"ref": "v2.0.0",
"sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
}
}
Git 存储库
{
"name": "git-plugin",
"source": {
"source": "url",
"url": "https://gitlab.com/team/plugin.git"
}
}
Git 子目录
使用 git-subdir 指向位于 git 存储库子目录中的 plugin。Claude Code 使用稀疏的部分克隆来仅获取子目录，最小化大型 monorepos 的带宽。
{
"name": "my-plugin",
"source": {
"source": "git-subdir",
"url": "https://github.com/acme-corp/monorepo.git",
"path": "tools/claude-plugin"
}
}
npm 包
{
"name": "my-npm-plugin",
"source": {
"source": "npm",
"package": "@acme/claude-plugin"
}
}
要固定到特定版本：
{
"name": "my-npm-plugin",
"source": {
"source": "npm",
"package": "@acme/claude-plugin",
"version": "2.1.0"
}
}
要从私有或内部 registry 安装：
{
"name": "my-npm-plugin",
"source": {
"source": "npm",
"package": "@acme/claude-plugin",
"version": "^2.0.0",
"registry": "https://npm.example.com"
}
}
Strict 模式
strict 字段控制 plugin.json 是否是组件定义的权威。
| 值 | 行为 |
|---|---|
true（默认） | plugin.json 是权威。marketplace 条目可以用额外的组件补充它，两个源都被合并 |
false | marketplace 条目是完整的定义。如果 plugin 也有声明组件的 plugin.json，那就是冲突，plugin 无法加载 |
托管和分发 marketplaces
在 GitHub 上托管（推荐）
GitHub 提供最简单的分发方法：
- 创建存储库：为你的 marketplace 设置一个新存储库
- 添加 marketplace 文件：使用你的 plugin 定义创建
.claude-plugin/marketplace.json - 与团队共享：用户使用
/plugin marketplace add owner/repo添加你的 marketplace
优点：内置版本控制、问题跟踪和团队协作功能。
在其他 git 服务上托管
任何 git 托管服务都可以工作，例如 GitLab、Bitbucket 和自托管服务器。用户使用完整的存储库 URL 添加：
/plugin marketplace add https://gitlab.com/company/plugins.git
私有存储库
Claude Code 支持从私有存储库安装 plugins。对于手动安装和更新，Claude Code 使用你现有的 git 凭证助手。
后台自动更新在启动时运行，不使用凭证助手。要为私有 marketplaces 启用自动更新，请在你的环境中设置适当的身份验证令牌：
| 提供商 | 环境变量 | 注释 |
|---|---|---|
| GitHub | GITHUB_TOKEN 或 GH_TOKEN | 个人访问令牌或 GitHub App 令牌 |
| GitLab | GITLAB_TOKEN 或 GL_TOKEN | 个人访问令牌或项目令牌 |
| Bitbucket | BITBUCKET_TOKEN | 应用密码或存储库访问令牌 |
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
在分发前本地测试
在共享前本地测试你的 marketplace：
/plugin marketplace add ./my-local-marketplace
/plugin install test-plugin@my-local-marketplace
为你的团队要求 marketplaces
你可以配置你的存储库，以便当团队成员信任项目文件夹时，他们会自动被提示安装你的 marketplace。将你的 marketplace 添加到 .claude/settings.json：
{
"extraKnownMarketplaces": {
"company-tools": {
"source": {
"source": "github",
"repo": "your-org/claude-plugins"
}
}
}
}
你也可以指定默认应启用哪些 plugins：
{
"enabledPlugins": {
"code-formatter@company-tools": true,
"deployment-tools@company-tools": true
}
}
为容器预填充 plugins
对于容器镜像和 CI 环境，你可以在构建时预填充 plugins 目录，以便 Claude Code 启动时已经有 marketplaces 和 plugins 可用，无需在运行时克隆任何内容。设置 CLAUDE_CODE_PLUGIN_SEED_DIR 环境变量以指向此目录。
种子目录镜像 ~/.claude/plugins 的结构：
$CLAUDE_CODE_PLUGIN_SEED_DIR/
known_marketplaces.json
marketplaces/<name>/...
cache/<marketplace>/<plugin>/<version>/...
要构建种子目录，请在镜像构建期间运行 Claude Code 一次，安装你需要的 plugins，然后将生成的 ~/.claude/plugins 目录复制到你的镜像中。
要跳过复制步骤，请在构建期间将 CLAUDE_CODE_PLUGIN_CACHE_DIR 设置为你的目标种子路径：
CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/plugins
CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install my-tool@your-plugins
然后在你的容器的运行时环境中设置 CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed。
托管 marketplace 限制
对于需要严格控制 plugin 源的组织，管理员可以使用托管设置中的 strictKnownMarketplaces 设置限制用户允许添加哪些 plugin marketplaces。
当在托管设置中配置 strictKnownMarketplaces 时，限制行为取决于值：
| 值 | 行为 |
|---|---|
| 未定义（默认） | 无限制。用户可以添加任何 marketplace |
空数组 [] | 完全锁定。用户无法添加任何新 marketplaces |
| 源列表 | 用户只能添加与允许列表完全匹配的 marketplaces |
常见配置
禁用所有 marketplace 添加：
{
"strictKnownMarketplaces": []
}
仅允许特定 marketplaces：
{
"strictKnownMarketplaces": [
{
"source": "github",
"repo": "acme-corp/approved-plugins"
},
{
"source": "github",
"repo": "acme-corp/security-tools",
"ref": "v2.0"
},
{
"source": "url",
"url": "https://plugins.example.com/marketplace.json"
}
]
}
使用主机上的正则表达式模式匹配允许来自内部 git 服务器的所有 marketplaces：
{
"strictKnownMarketplaces": [
{
"source": "hostPattern",
"hostPattern": "^github\\.example\\.com$"
}
]
}
使用路径上的正则表达式模式匹配允许来自特定目录的基于文件系统的 marketplaces：
{
"strictKnownMarketplaces": [
{
"source": "pathPattern",
"pathPattern": "^/opt/approved/"
}
]
}
版本解析和发布渠道
Plugin 版本确定缓存路径和更新检测：如果解析的版本与用户已有的版本匹配，/plugin update 和自动更新会跳过该 plugin。
Claude Code 从以下第一个设置的内容解析 plugin 的版本：
- plugin 的
plugin.json中的version - plugin 的 marketplace 条目中的
version - plugin 源的 git 提交 SHA
对于 git 源类型 github、url、git-subdir 和 git 托管 marketplace 内的相对路径，你可以完全省略 version，每个新提交都被视为新版本。
⚠️ 设置
version会固定 plugin。如果plugin.json声明"version": "1.0.0"，推送新提交而不改变该字符串对现有用户没有任何作用。在每个发布时提升该字段，或省略它以使用提交 SHA。避免在
plugin.json和 marketplace 条目中都设置version。plugin.json值总是无声地获胜。
设置发布渠道
要为你的 plugins 支持”稳定”和”最新”发布渠道，你可以设置两个指向同一 repo 的不同 refs 或 SHAs 的 marketplaces。然后，你可以通过托管设置将两个 marketplaces 分配给不同的用户组。
⚠️ 每个渠道必须解析为不同的版本。
示例
{
"name": "stable-tools",
"plugins": [
{
"name": "code-formatter",
"source": {
"source": "github",
"repo": "acme-corp/code-formatter",
"ref": "stable"
}
}
]
}
{
"name": "latest-tools",
"plugins": [
{
"name": "code-formatter",
"source": {
"source": "github",
"repo": "acme-corp/code-formatter",
"ref": "latest"
}
}
]
}
固定依赖版本
Plugin 可以将其依赖约束到 semver 范围，以便对依赖的更新不会破坏依赖的 plugin。有关 {plugin-name}--v{version} git 标签约定、范围语法以及如何组合对同一依赖的多个约束，请参阅 约束 plugin 依赖版本。
验证和测试
验证你的 marketplace JSON 语法：
claude plugin validate .
或从 Claude Code 内：
/plugin validate .
添加 marketplace 进行测试：
/plugin marketplace add ./path/to/marketplace
安装测试 plugin 以验证一切正常：
/plugin install test-plugin@marketplace-name
从 CLI 管理 marketplaces
Claude Code 提供非交互式 claude plugin marketplace 子命令用于脚本编写和自动化。
Plugin marketplace add
从 GitHub 存储库、git URL、远程 URL 或本地路径添加 marketplace。
claude plugin marketplace add <source> [options]
选项：
| 选项 | 描述 | 默认值 |
|---|---|---|
--scope <scope> | 声明 marketplace 的位置：user、project 或 local | user |
--sparse <paths...> | 通过 git sparse-checkout 限制检出到特定目录 |
示例：
# 从 GitHub 使用 owner/repo 简写添加 marketplace
claude plugin marketplace add acme-corp/claude-plugins
# 使用 @ref 固定到特定分支或标签
claude plugin marketplace add acme-corp/claude-plugins@v2.0
# 从非 GitHub 主机上的 git URL 添加
claude plugin marketplace add https://gitlab.example.com/team/plugins.git
# 从直接提供 marketplace.json 文件的远程 URL 添加
claude plugin marketplace add https://example.com/marketplace.json
# 从本地目录添加以进行测试
claude plugin marketplace add ./my-marketplace
# 在项目范围声明 marketplace
claude plugin marketplace add acme-corp/claude-plugins --scope project
# 对于 monorepo，限制检出到包含 plugin 内容的目录
claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins
Plugin marketplace list
列出所有配置的 marketplaces。
claude plugin marketplace list [options]
Plugin marketplace remove
删除配置的 marketplace。别名 rm 也被接受。
claude plugin marketplace remove <name>
⚠️ 删除 marketplace 也会卸载你从它安装的任何 plugins。
Plugin marketplace update
从其源刷新 marketplaces 以检索新 plugins 和版本更改。
claude plugin marketplace update [name]
故障排除
Marketplace 未加载
症状：无法添加 marketplace 或从中看到 plugins
解决方案：
- 验证 marketplace URL 是否可访问
- 检查
.claude-plugin/marketplace.json是否存在于指定路径 - 使用
claude plugin validate或/plugin validate确保 JSON 语法有效且 frontmatter 格式正确 - 对于私有存储库，确认你有访问权限
Marketplace 验证错误
从你的 marketplace 目录运行 claude plugin validate . 或 /plugin validate . 来检查问题。常见错误：
| 错误 | 原因 | 解决方案 |
|---|---|---|
File not found: .claude-plugin/marketplace.json | 缺少 manifest | 使用必需字段创建 .claude-plugin/marketplace.json |
Invalid JSON syntax: Unexpected token... | JSON 语法错误 | 检查缺少的逗号、多余的逗号或未引用的字符串 |
Duplicate plugin name "x" found in marketplace | 两个 plugins 共享相同的名称 | 给每个 plugin 一个唯一的 name 值 |
plugins[0].source: Path contains ".." | 源路径包含 .. | 使用相对于 marketplace 根目录的路径，不包含 .. |
Plugin 安装失败
症状：Marketplace 出现但 plugin 安装失败
解决方案：
- 验证 plugin 源 URL 是否可访问
- 检查 plugin 目录是否包含必需的文件
- 对于 GitHub 源，确保存储库是公开的或你有访问权限
私有存储库身份验证失败
对于手动安装和更新：
- 验证你已使用你的 git 提供商进行身份验证
- 检查你的凭证助手是否配置正确：
git config --global credential.helper - 尝试手动克隆存储库以验证你的凭证有效
对于后台自动更新：
- 在你的环境中设置适当的令牌
- 检查令牌是否具有所需的权限（对存储库的读取访问权限）
Marketplace 更新在离线环境中失败
症状：Marketplace git pull 失败，Claude Code 清除现有缓存。
解决方案：设置 CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 以在拉取失败时保留现有缓存：
export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1
Git 操作超时
症状：Plugin 安装或 marketplace 更新失败，出现超时错误。
解决方案：使用 CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS 环境变量增加超时：
export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000 # 5 minutes
相对路径 Plugins 在基于 URL 的 Marketplaces 中失败
症状：通过 URL 添加了 marketplace，但具有相对路径源的 plugins 无法安装。
原因：基于 URL 的 marketplaces 仅下载 marketplace.json 文件本身。
解决方案：
- 使用外部源：将 plugin 条目更改为使用 GitHub、npm 或 git URL 源
- 使用基于 Git 的 Marketplace：在 Git 存储库中托管你的 marketplace 并使用 git URL 添加它
另见
- 发现和安装预构建的 plugins - 从现有 marketplaces 安装 plugins
- Plugins - 创建你自己的 plugins
- Plugins 参考 - 完整的技术规范和架构
本文翻译自 Anthropic Claude Code 官方文档，最近一次同步：2025-05-01。