创建和分发插件市场

构建并托管插件市场，在团队和社区中分发 Claude Code 扩展。

插件市场是一份插件目录，可用于向他人分发插件。插件市场提供集中发现、版本跟踪和自动更新能力，并支持 git 仓库、本地路径等多种来源类型。本指南介绍如何创建自己的插件市场，与团队或社区共享插件。

想从现有插件市场安装插件？请参阅发现并安装预构建插件。

概述

创建和分发插件市场需要完成以下工作：

1. 创建插件：使用 Skills、智能体、Hook、MCP 服务器或 LSP 服务器构建一个或多个插件。本指南假定你已经有可供分发的插件；有关插件的创建方法，请参阅创建插件。
2. 创建插件市场文件：定义一个 marketplace.json，列出插件及其所在位置。请参阅创建插件市场文件。
3. 托管插件市场：将其推送到 GitHub、GitLab 或其他 git 托管服务。请参阅托管和分发插件市场。
4. 与用户共享：用户通过 /plugin marketplace add 添加你的插件市场，然后安装其中的各个插件。请参阅发现并安装插件。

插件市场上线后，只需将更改推送到仓库即可进行更新。用户可通过 /plugin marketplace update 刷新本地副本。

演练：创建本地插件市场

以下示例将创建一个包含单个插件的插件市场：用于代码审查的 quality-review Skill。你将依次创建目录结构、添加 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

---
description: 检查代码中的错误、安全性和性能问题
---

审查我选中的代码或最近的更改，重点检查：
- 潜在错误或边界情况
- 安全隐患
- 性能问题
- 可读性改进空间

请简明扼要地给出可操作的建议。

{
  "name": "quality-review-plugin",
  "description": "Adds a quality-review skill for quick code reviews",
  "version": "1.0.0"
}

{
  "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"
    }
  ]
}

/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@my-plugins

/quality-review-plugin:quality-review

要进一步了解插件的能力，包括 Hook、智能体、MCP 服务器和 LSP 服务器，请参阅插件。

创建插件市场文件

在仓库根目录创建 .claude-plugin/marketplace.json。该文件定义插件市场的名称、所有者信息，以及插件及其来源的列表。

每个插件条目至少需要包含 name 和 source；后者告诉 Claude Code 应从哪里获取插件。所有可用字段请参阅下文的完整 schema。

{
  "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"
    }
  ]
}

插件市场 schema

必填字段

所有者字段

可选字段

为了向后兼容，也可以在 metadata 下设置 description 和 version。

插件条目

plugins 数组中的每个条目都描述一个插件及其所在位置。条目可以包含插件清单 schema 中的任意字段，例如 description、version、author、commands 和 hooks；此外还可以包含插件市场专用字段：source、category、tags、strict 和 relevance。

必填字段

可选插件字段

标准元数据字段：

组件配置字段：

插件来源

插件来源告诉 Claude Code 应从哪里获取插件市场中列出的各个插件。它通过 marketplace.json 中每个插件条目的 source 字段设置。

Claude Code 将插件克隆或下载到本地计算机后，会把插件复制到 ~/.claude/plugins/cache 下带版本号的本地插件缓存中。

下文基于 git 的来源类型包括 github、url 和 git-subdir。如果其中任意来源同时设置了 ref 和 sha，则以 sha 作为实际的版本固定依据。Claude Code 会直接获取并检出指定的提交。

在 GitHub、GitLab 和 Bitbucket 等大多数 git 托管服务上，只要该提交在仓库中仍可访问，即使 ref 指定的分支或标签后来已从上游删除，安装仍能成功。AWS CodeCommit 等部分服务器不支持按 SHA 获取提交；在这些服务器上，ref 必须仍然存在，而且必须能通过它访问所固定的提交。

相对路径

对于位于同一仓库中的插件，请使用以 ./ 开头的路径：

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}

路径相对于插件市场根目录解析，也就是包含 .claude-plugin/ 的目录。在上例中，虽然 marketplace.json 位于 <repo>/.claude-plugin/marketplace.json，但 ./plugins/my-plugin 指向的是 <repo>/plugins/my-plugin。不要使用 ../ 引用插件市场根目录之外的路径。

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

可以固定到特定的分支、标签或提交：

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git",
    "ref": "main",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Git 子目录

如果插件位于 git 仓库的某个子目录中，请使用 git-subdir 指向它。Claude Code 会执行稀疏的部分克隆，只获取该子目录，从而降低大型 monorepo 的带宽消耗。

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin"
  }
}

可以固定到特定的分支、标签或提交：

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

url 字段也接受 GitHub 简写形式（owner/repo）或 SSH URL（git@github.com:owner/repo.git）。

npm 软件包

以 npm 软件包形式分发的插件使用 npm install 安装。公共 npm registry 中的任意软件包，以及团队自行托管的私有 registry 都可以使用这种方式。

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin"
  }
}

如需固定到特定版本，请添加 version 字段：

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "2.1.0"
  }
}

如需从私有或内部 registry 安装，请添加 registry 字段：

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}

高级插件条目

下面的示例展示了一个使用大量可选字段的插件条目，其中包括命令、智能体、Hook 和 MCP 服务器的自定义路径：

{
  "name": "enterprise-tools",
  "source": {
    "source": "github",
    "repo": "company/enterprise-plugin"
  },
  "description": "Enterprise workflow automation tools",
  "version": "2.1.0",
  "author": {
    "name": "Enterprise Team",
    "email": "enterprise@example.com"
  },
  "homepage": "https://docs.example.com/plugins/enterprise-tools",
  "repository": "https://github.com/company/enterprise-plugin",
  "license": "MIT",
  "keywords": ["enterprise", "workflow", "automation"],
  "category": "productivity",
  "commands": [
    "./commands/core/",
    "./commands/enterprise/",
    "./commands/experimental/preview.md"
  ],
  "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.md"],
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
          }
        ]
      }
    ]
  },
  "mcpServers": {
    "enterprise-db": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  },
  "strict": false
}

需要注意以下几点：

• commands 和 agents：可以指定多个目录或单个文件。路径相对于插件根目录。
• ${CLAUDE_PLUGIN_ROOT}：在 Hook 和 MCP 服务器配置中使用此变量，引用插件安装目录内的文件。由于插件安装时会被复制到缓存位置，因此必须这样引用。对于需要在插件更新后继续保留的依赖项或状态，请改用 ${CLAUDE_PLUGIN_DATA}。
• strict: false：设为 false 后，插件无需提供自己的 plugin.json，所有内容都由插件市场条目定义。见下文的严格模式。

默认情况下，插件的 Skills 从其 source 下的 skills/ 目录加载。skills 字段中列出的路径会加入扫描范围：

"skills": ["./skills/", "./extra-skills/"]

如果多个插件条目共用插件市场根目录下的同一个 skills/ 文件夹（source: "./"），请列出具体的子目录，确保每个条目只加载自己的 Skills：

"source": "./",
"skills": ["./skills/code-review", "./skills/docs"]

当 source 指向插件市场根目录时，列出的路径就是该条目的完整路径集合，共享 skills/ 文件夹中的其他目录不会被加载。如果列出 ./skills/ 本身或插件根目录，则仍会执行完整扫描。如果列出的路径均不存在，则改为执行默认扫描。

严格模式

strict 字段控制是否由 plugin.json 作为组件定义（Skills、智能体、Hook、MCP 服务器和输出样式）的权威来源。

各模式的适用场景：

• strict: true：插件有自己的 plugin.json，并自行管理组件。插件市场条目可以在此基础上添加额外的 Skills 或 Hook。这是默认设置，适用于大多数插件。
• strict: false：插件市场运营方希望拥有完全控制权。插件仓库提供原始文件，插件市场条目则定义哪些文件以 Skills、智能体、Hook 等形式公开。如果插件市场需要以不同于插件作者原始意图的方式重组或策划插件组件，此模式会很有用。

托管和分发插件市场

托管在 GitHub 上（推荐）

GitHub 是托管和分发插件市场的推荐方式：

1. 创建仓库：为插件市场新建一个仓库
2. 添加插件市场文件：创建包含插件定义的 .claude-plugin/marketplace.json
3. 与团队共享：用户通过 /plugin marketplace add owner/repo 添加插件市场

优势：内置版本控制、问题跟踪和团队协作功能。

托管在其他 git 服务上

GitLab、Bitbucket、自托管服务器等任何 git 托管服务都可以使用。用户通过完整的仓库 URL 添加：

/plugin marketplace add https://gitlab.com/company/plugins.git

私有仓库

Claude Code 支持从私有仓库安装插件。手动安装和更新时，Claude Code 会使用现有的 git 凭据辅助程序，因此通过 gh auth login、macOS Keychain 或 git-credential-store 进行 HTTPS 访问的方式与在终端中相同。SSH 访问要求主机已写入 known_hosts 文件，且密钥已加载到 ssh-agent；这是因为 Claude Code 会禁用有关主机指纹和密钥口令的交互式 SSH 提示。

后台自动更新会在启动时运行，且不使用凭据辅助程序，因为交互式提示会阻止 Claude Code 启动。如需为私有插件市场启用自动更新，请在环境中设置相应的身份验证 Token：

在 shell 配置文件（例如 .bashrc、.zshrc）中设置 Token，或在运行 Claude Code 时传入：

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

分发前进行本地测试

共享插件市场之前，请先在本地进行测试：

/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@my-plugins

添加插件市场所支持的完整命令形式（GitHub、Git URL、本地路径、远程 URL）请参阅添加插件市场。

要求团队使用指定插件市场

你可以配置仓库，让团队成员信任项目文件夹时自动收到安装插件市场的提示。将插件市场添加到 .claude/settings.json：

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

还可以指定默认应启用的插件：

{
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}

完整配置选项请参阅插件设置。

为容器预置插件

对于容器镜像和 CI 环境，可以在构建时预先填充插件目录，使 Claude Code 启动时即可使用插件市场和插件，无需在运行时克隆任何内容。通过 CLAUDE_CODE_PLUGIN_SEED_DIR 环境变量指定该目录。

如需叠加多个种子目录，请在 Unix 上用 : 分隔路径，在 Windows 上用 ; 分隔。Claude Code 会按顺序搜索每个目录，并使用第一个包含相应插件市场或插件缓存的种子目录。

种子目录的结构与 ~/.claude/plugins 一致：

$CLAUDE_CODE_PLUGIN_SEED_DIR/
  known_marketplaces.json
  marketplaces/<name>/...
  cache/<marketplace>/<plugin>/<version>/...

构建种子目录时，在镜像构建期间运行一次 Claude Code，安装所需插件，然后把生成的 ~/.claude/plugins 目录复制到镜像中，并让 CLAUDE_CODE_PLUGIN_SEED_DIR 指向该目录。

如果希望省去复制步骤，可在构建期间将 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，Claude Code 启动时便会从种子中读取数据。

启动时，Claude Code 会把种子 known_marketplaces.json 中的插件市场注册到主配置，并直接使用 cache/ 下的插件缓存，不再重新克隆。交互模式和使用 -p 标志的非交互模式都支持这一功能。

具体行为如下：

• 只读：Claude Code 永远不会写入种子目录。种子插件市场会禁用自动更新，因为只读文件系统上的 git pull 会失败。
• 种子条目优先：每次启动时，种子中声明的插件市场都会覆盖用户配置中的同名条目。如需停用种子插件，请使用 /plugin disable，不要移除插件市场。
• 路径解析：运行时，Claude Code 会检查 $CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/ 来定位插件市场内容，而不会信任种子 JSON 中存储的路径。因此，即使种子的挂载路径与构建路径不同，它仍能正常工作。
• 禁止修改：对种子管理的插件市场运行 /plugin marketplace remove 或 /plugin marketplace update 会失败，并提示联系管理员更新种子镜像。
• 与设置组合使用：如果 extraKnownMarketplaces 或 enabledPlugins 声明了种子中已有的插件市场，Claude Code 会使用种子副本，不再克隆。

托管插件市场限制

对于需要严格控制插件来源的组织，管理员可以使用托管设置中的 strictKnownMarketplaces，限制用户可以添加哪些插件市场。如果还需要禁止使用 CLI 标志在单次运行中旁加载插件、智能体和 MCP 服务器，请同时设置 disableSideloadFlags。

在托管设置中配置 strictKnownMarketplaces 后，限制行为取决于其值：

常见配置

禁止添加任何插件市场：

{
  "strictKnownMarketplaces": []
}

只允许指定的插件市场：

{
  "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 服务器上的所有插件市场。这是 GitHub Enterprise Server 或自托管 GitLab 实例的推荐做法：

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

使用正则表达式匹配路径，以允许指定目录下基于文件系统的插件市场：

{
  "strictKnownMarketplaces": [
    {
      "source": "pathPattern",
      "pathPattern": "^/opt/approved/"
    }
  ]
}

将 pathPattern 设为 ".*"，可以允许任意文件系统路径，同时继续通过 hostPattern 控制网络来源。

限制的工作方式

系统会在执行任何网络或文件系统操作之前检查限制。添加插件市场，以及安装、更新、刷新和自动更新插件时，都会执行这项检查。如果某个插件市场是在策略配置前添加的，而其来源已不再符合允许列表，Claude Code 将拒绝从该市场安装或更新插件。blockedMarketplaces 也采用相同的强制执行方式。

对于大多数来源类型，允许列表使用精确匹配。要允许某个插件市场，所有指定字段都必须完全匹配：

• 对于 GitHub 来源：必须指定 repo；如果允许列表中指定了 ref 或 path，也必须匹配
• 对于 URL 来源：完整 URL 必须完全匹配
• 对于 hostPattern 来源：使用正则表达式匹配插件市场主机
• 对于 pathPattern 来源：使用正则表达式匹配插件市场的文件系统路径

精确匹配不会规范化 URL：末尾斜杠、.git 后缀，以及 ssh:// 与 https:// 形式都会被视为不同的值。如果组织的插件市场可以通过多种 URL 形式克隆，建议使用 hostPattern 条目，而不是字面 URL，以涵盖所有形式。

由于 strictKnownMarketplaces 设置在托管设置中，单个用户和项目配置都无法覆盖这些限制。

完整配置细节（包括所有支持的来源类型，以及与 extraKnownMarketplaces 的比较）请参阅 strictKnownMarketplaces 参考。

版本解析和发布通道

插件版本决定缓存路径和更新检测：如果解析出的版本与用户已有版本相同，/plugin update 和自动更新都会跳过该插件。

Claude Code 按以下优先顺序，使用第一个已设置的值解析插件版本：

1. 插件 plugin.json 中的 version
2. 插件市场条目中的 version
3. 插件来源的 git commit SHA

对于基于 git 的来源类型 github、url 和 git-subdir，以及 git 托管插件市场中的相对路径，可以完全省略 version。此时，每次新提交都会视为一个新版本。对于内部插件或正在积极开发的插件，这是最简单的配置方式。

设置发布通道

如需为插件提供“stable”和“latest”发布通道，可以设置两个指向同一仓库不同 ref 或 SHA 的插件市场，然后通过托管设置将这两个插件市场分配给不同用户组。

示例

{
  "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"
      }
    }
  ]
}

将通道分配给用户组

通过托管设置将每个插件市场分配给相应的用户组。例如，stable 组接收：

{
  "extraKnownMarketplaces": {
    "stable-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/stable-tools"
      }
    }
  }
}

early-access 组则改为接收 latest-tools：

{
  "extraKnownMarketplaces": {
    "latest-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/latest-tools"
      }
    }
  }
}

固定依赖版本

插件可以通过 semver 范围约束依赖项，避免依赖项更新破坏依赖它的插件。有关 {plugin-name}--v{version} git 标签约定、范围语法，以及如何合并针对同一依赖项的多项约束，请参阅约束插件依赖版本。

重命名或移除插件

插件的 name 是其稳定标识符。用户会在 enabledPlugins、pluginConfigs 和 /plugin install 命令中引用它，因此更改名称会破坏所有现有安装。如需在不影响安装的前提下更改 UI 中显示的标签，请设置 displayName，并保持 name 不变。

如果必须更改插件的 name，或者从 plugins 数组中移除插件，请添加顶层 renames 条目，让现有用户能够迁移，而不是遇到 plugin-not-found 错误。自动迁移需要 Claude Code v2.1.193 或更高版本。将每个旧名称映射到当前名称；如果插件已不存在，则映射到 null。以下示例将 formatter 重命名为 code-formatter，并记录 legacy-linter 已被移除：

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "plugins": [
    { "name": "code-formatter", "source": "./plugins/code-formatter" }
  ],
  "renames": {
    "formatter": "code-formatter",
    "legacy-linter": null
  }
}

如果用户启动 Claude Code 时设置中仍使用旧名称，Claude Code 会按照 renames 映射处理：

• 如果条目指向新名称，Claude Code 会以新名称加载插件，并显示一行通知，例如 Renamed to "code-formatter" in the "acme-tools" marketplace。随后，它会在 user、project 和 local 设置 scope 的 enabledPlugins 和 pluginConfigs 中将旧键改写为新键，因此通知只显示一次。
• 对于值为 null 的条目，Claude Code 会删除旧键，并在通知中说明该插件已从插件市场移除。
• 如果重命名后的插件使用 github 或 npm 等远程来源，Claude Code 会在重命名后报告 plugin-cache-miss，用户必须运行一次 /plugin install，以新名称获取插件。

应将 renames 视为只能追加的历史记录：即使预计所有用户都已完成迁移，也要保留旧条目。Claude Code 会沿映射链解析名称，因此以后再把 code-formatter 重命名为 formatter-pro 时，应添加第二个条目，而不是修改第一个条目。仍启用原始名称 formatter 的用户会依次经过两个条目，最终解析为 formatter-pro。

编辑映射后，请运行 claude plugin validate .；如果某条映射链形成循环，或最终没有指向 null 或 plugins 中列出的名称，验证将失败。

早期版本的 Claude Code 会忽略 renames 字段，并针对旧名称报告 plugin-not-found。

验证和测试

共享插件市场之前，请先进行测试。

验证插件市场 JSON 语法：

claude plugin validate .

也可以在 Claude Code 中运行：

/plugin validate .

添加插件市场以供测试：

/plugin marketplace add ./path/to/marketplace

安装一个测试插件，确认一切正常：

/plugin install test-plugin@marketplace-name

完整的插件测试流程请参阅在本地测试插件。技术问题排查请参阅插件参考。

通过 CLI 管理插件市场

Claude Code 提供非交互式 claude plugin marketplace 子命令，可用于编写脚本和实现自动化。它们等同于交互式会话中可用的 /plugin marketplace 命令。

Plugin marketplace add

从 GitHub 仓库、git URL、远程 URL 或本地路径添加插件市场。

claude plugin marketplace add <source> [options]

参数：

• <source>：GitHub owner/repo 简写形式、git URL、指向 marketplace.json 文件的远程 URL，或本地目录路径。如需固定到某个分支或标签，请在 GitHub 简写形式后附加 @ref，或在 git URL 后附加 #ref

URL 必须包含 scheme。从 Claude Code v2.1.196 开始，如果输入的主机未带 scheme（例如 gitlab.example.com/team/plugins），系统会将其作为无效的 owner/repo 简写形式拒绝，并在错误信息中提示添加 https://，或者对本地路径使用 ./。早期版本会将它误识别为 GitHub 仓库路径，并在克隆时因 GitHub 找不到该仓库而失败。

选项：

使用 owner/repo 简写形式从 GitHub 添加插件市场：

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

在 project scope 声明插件市场，以便通过 .claude/settings.json 与团队共享：

claude plugin marketplace add acme-corp/claude-plugins --scope project

对于 monorepo，将 checkout 限制在包含插件内容的目录：

claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins

Plugin marketplace list

列出所有已配置的插件市场。

claude plugin marketplace list [options]

选项：

使用 --json 时，每个条目都包含 name、source 以及来源特有的字段：GitHub 来源使用 repo，git 和 URL 来源使用 url，本地来源使用 path。如果添加 GitHub 或 git 来源的插件市场时固定了分支或标签，条目还会包含 ref 字段。

Plugin marketplace remove

移除已配置的插件市场。也可以使用别名 rm。

claude plugin marketplace remove <name> [options]

参数：

• <name>：要移除的插件市场名称，以 claude plugin marketplace list 显示的名称为准。这是 marketplace.json 中的 name，而不是传给 add 的来源

选项：

Plugin marketplace update

从来源刷新插件市场，以获取新插件和版本变更。

claude plugin marketplace update [name]

参数：

• [name]：要更新的插件市场名称，以 claude plugin marketplace list 显示的名称为准。省略时更新所有插件市场

对只读的种子管理插件市场运行 remove 或 update 都会失败。更新所有插件市场时，系统会跳过种子管理的条目，继续更新其他插件市场。如需更改种子提供的插件，请联系管理员更新种子镜像。请参阅为容器预置插件。

故障排除

插件市场无法加载

症状：无法添加插件市场，或看不到其中的插件

解决方法：

• 确认插件市场 URL 可以访问
• 检查指定路径是否存在 .claude-plugin/marketplace.json
• 使用 claude plugin validate 或 /plugin validate 确认 JSON 语法有效。如需检查 Skill、智能体和命令的 frontmatter，请对每个插件目录运行该命令
• 对于私有仓库，确认你拥有访问权限

插件市场验证错误

在插件市场目录中运行 claude plugin validate . 或 /plugin validate . 检查问题。如果目标是插件市场目录，验证器会检查 marketplace.json 的 schema 错误、重复的插件名称以及来源路径遍历问题。对于 source 是本地路径的每个条目，验证器还会验证相应插件自己的 plugin.json，并在条目的 version 与 plugin.json 中的版本不一致时发出警告。插件 plugin.json 中发现的问题会带有条目索引前缀，格式为 plugins[2] plugin.json →。

从 Claude Code v2.1.196 开始，逐条目检查还会：

• 包括 source 为 . 的插件
• 当 marketplace.json 不在 .claude-plugin 目录中时也会执行，并以文件自身所在目录为基准解析来源
• 即使文件的其他部分存在 schema 错误，也会报告每个条目的问题

早期版本会跳过插件市场根目录中的插件，而且只会从 .claude-plugin/marketplace.json 向下检查。

如需验证单个插件的 plugin.json 及其 Skill、智能体、命令和 Hook 文件，请对插件目录本身运行命令，例如 claude plugin validate ./plugins/my-plugin。常见错误如下：

警告（不会阻止操作）：

• Marketplace has no plugins defined：在 plugins 数组中至少添加一个插件
• No marketplace description provided：添加顶层 description，帮助用户了解该插件市场
• Plugin name "x" is not kebab-case：插件名称包含大写字母、空格或特殊字符。将其重命名为仅含小写字母、数字和连字符的形式（例如 my-plugin）。Claude Code 接受其他形式，但 claude.ai 插件市场同步会拒绝它们。

插件安装失败

症状：插件市场可以显示，但插件安装失败

解决方法：

• 确认插件来源 URL 可以访问
• 检查插件目录是否包含必需文件
• 对于 GitHub 来源，确认仓库是公开的，或你拥有访问权限
• 尝试手动克隆或下载，测试插件来源
• 如果来源同时固定了 ref 和 sha，在 GitHub、GitLab 和 Bitbucket 等大多数 git 托管服务上，即使上游分支或标签已被删除，也不会妨碍安装。对于 AWS CodeCommit 等不支持按 SHA 获取提交的服务器，ref 必须仍然存在，而且必须能通过它访问所固定的提交。如果安装仍然失败，请确认仓库中仍存在所固定的提交

私有仓库身份验证失败

症状：从私有仓库安装插件时出现身份验证错误

解决方法：

对于手动安装和更新：

• 确认已通过 git 提供方完成身份验证（例如，对于 GitHub 可运行 gh auth status）
• 检查凭据辅助程序配置是否正确：git config --global credential.helper
• 尝试手动克隆仓库，确认凭据有效

对于后台自动更新：

• 在环境中设置相应 Token：echo $GITHUB_TOKEN
• 检查 Token 是否具有所需权限（仓库读取权限）
• 对于 GitHub，确认 Token 拥有访问私有仓库所需的 repo scope
• 对于 GitLab，确认 Token 至少拥有 read_repository scope
• 确认 Token 尚未过期

离线环境中的插件市场更新失败

症状：插件市场的 git pull 失败，Claude Code 清空现有缓存，导致插件不可用。

原因：默认情况下，git pull 失败后，Claude Code 会移除过期的克隆并尝试重新克隆。在离线或隔离网络环境中，重新克隆也会失败，最终使插件市场目录为空。

解决方法：设置 CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1，让拉取失败时保留现有缓存，而不是将其清空：

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

设置该变量后，如果 git pull 失败，Claude Code 会保留旧的插件市场克隆，并继续使用上次确认可用的状态。对于仓库始终不可访问的完全离线部署，请使用 CLAUDE_CODE_PLUGIN_SEED_DIR，在构建时预先填充插件目录。

Git 操作超时

症状：安装插件或更新插件市场时出现超时错误，例如“Git clone timed out after 120s”或“Git pull timed out after 120s”。

原因：Claude Code 对所有 git 操作使用 120 秒超时，包括克隆插件仓库和拉取插件市场更新。大型仓库或缓慢的网络连接可能超过这一限制。

解决方法：使用 CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS 环境变量增加超时时间。该值以毫秒为单位：

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000  # 5 分钟

基于 URL 的插件市场无法使用相对路径插件

症状：通过 URL（例如 https://example.com/marketplace.json）添加了插件市场，但来源为 "./plugins/my-plugin" 等相对路径的插件无法安装，并出现“path not found”错误。

原因：基于 URL 的插件市场只会下载 marketplace.json 文件本身，不会从服务器下载插件文件。插件市场条目中的相对路径引用了远程服务器上未被下载的文件。

解决方法：

• 使用外部来源：将插件条目改为使用 GitHub、npm 或 git URL 来源，而不是相对路径：
  Copy

  { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }
• 使用基于 Git 的插件市场：将插件市场托管在 Git 仓库中，并通过 git URL 添加。基于 Git 的插件市场会克隆整个仓库，因此相对路径能够正常工作。

安装后找不到文件

症状：插件可以安装，但文件引用失败，尤其是对插件目录外部文件的引用

原因：插件会被复制到缓存目录，而不是在原位置使用。引用插件目录之外文件的路径（例如 ../shared-utils）将无法工作，因为这些文件不会被复制。

解决方法：可行的处理方式（包括符号链接和目录重组）请参阅插件缓存和文件解析。

其他调试工具和常见问题请参阅调试和开发工具。

另请参阅

• 发现并安装预构建插件 - 从现有插件市场安装插件
• 插件 - 创建自己的插件
• 插件参考 - 完整的技术规范和 schema
• 插件设置 - 插件配置选项
• strictKnownMarketplaces 参考 - 托管插件市场限制