创建和分发 plugin marketplace

​

概述

1. 创建 plugins：使用 skills、agents、hooks、MCP servers 或 LSP servers 构建一个或多个 plugins。本指南假设你已经有要分发的 plugins；有关如何创建 plugins 的详细信息，请参阅创建 plugins。
2. 创建 marketplace 文件：定义一个 marketplace.json，列出你的 plugins 及其位置。请参阅创建 marketplace 文件。
3. 托管 marketplace：推送到 GitHub、GitLab 或其他 git 主机。请参阅托管和分发 marketplaces。
4. 与用户共享：用户使用 /plugin marketplace add 添加你的 marketplace 并安装单个 plugins。请参阅发现和安装 plugins。

​

演练：创建本地 marketplace

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: Review code for bugs, security, and performance
---

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.

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

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

​

创建 marketplace 文件

{
  "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 架构

​

必需字段

​

所有者字段

​

可选字段

​

Plugin 条目

​

必需字段

​

可选 plugin 字段

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

​

Plugin 源

​

相对路径

{
  "name": "my-plugin",
  "source": "./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 子目录

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

​

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

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

​

Zip 存档

{
  "name": "my-plugin",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip"
  }
}

my-plugin.zip          my-plugin.zip
├── .claude-plugin/    └── my-plugin/
│   └── plugin.json        ├── .claude-plugin/
└── commands/              │   └── plugin.json
                           └── commands/

{
  "name": "my-plugin",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip",
    "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1"
  }
}

​

验证存档下载

{
  "name": "my-plugin",
  "description": "Formatting commands for internal services",
  "strict": false,
  "commands": "./commands",
  "source": {
    "source": "archive",
    "url": "https://registry.example.com/plugins/my-plugin-2.1.0.zip"
  },
  "headersHelper": "/opt/bin/mint-registry-token.sh"
}

​

编写 headersHelper 命令

• 命令文本：最多 500 个可打印 ASCII 字符，没有四个或更多空格的运行。
• 输出：在 stdout 上打印一个标头名称和字符串值的 JSON 对象，然后在 10 秒内以 0 退出。
• Shell 和工作目录：Claude Code 通过 sh 运行命令，或在 Windows 上通过 cmd.exe，从配置目录 ~/.claude 或 CLAUDE_CONFIG_DIR。给出绝对路径或 PATH 上的命令，因为相对路径相对于该目录解析，而不是用户的项目。
• Claude Code 移除的变量：从 marketplace.json 条目或项目的 .claude/settings.json 或 .claude/settings.local.json 中设置的命令的环境中，Claude Code 移除每个名称包含 TOKEN、SECRET、KEY 或 AUTH 等词的变量，包括 ANTHROPIC_API_KEY。Claude Code 不对用户设置、--settings 文件或托管设置中设置的命令应用此移除。
• Claude Code 设置的变量：CLAUDE_CODE_MARKETPLACE_URL 和 CLAUDE_CODE_MARKETPLACE_NAME 用于 url 源的命令，以及 CLAUDE_CODE_PLUGIN_NAME 和 CLAUDE_CODE_PLUGIN_ARCHIVE_URL 用于条目的命令。CLAUDE_CODE_MARKETPLACE_NAME 在用户通过 URL 添加 marketplace 后的第一次获取时未设置，因为该获取是提供名称的。

{"Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9"}

​

Claude Code 何时跳过 headersHelper 命令或丢弃其输出

• 命令失败：如果命令以非零退出、运行超过 10 秒或打印除 JSON 字符串值对象之外的任何内容，Claude Code 不进行它运行命令的获取或下载。
• Marketplace URL 不以 https:// 开头：Claude Code 不运行该 url 源的命令，仅发送其 headers 字段中列出的标头。
• 重定向离开源：当下载被重定向离开存档 URL 的源时，Claude Code 丢弃 marketplace url 源和 plugin 条目的 headers 值和命令输出。
• 条目设置路由或身份标头：Claude Code 从条目的 headers 和命令输出中丢弃请求路由和客户端身份名称，例如 Host、Cookie 和 X-Forwarded-*，并保留身份验证名称，例如 Authorization。Claude Code 以这种方式过滤每个 marketplace.json 条目，以及内联设置条目取决于哪个文件声明它。
• 命令在 --add-dir 目录的设置中设置：Claude Code 忽略它，在 url 源和内联 plugin 条目上都一样，仅发送该文件的 headers。
• 托管设置阻止命令：将 disableCommandPluginSources 设置为 true 阻止 headersHelper 命令，allowManagedHooksOnly 也阻止它们，除非 disableCommandPluginSources 明确为 false。在任一阻止下，Claude Code 仍然为托管设置本身声明的 marketplace 运行命令。

​

用户如何接受 headersHelper 命令

• 一次安装多个 plugins、从 plugin 建议或作为另一个 plugin 的依赖项：Claude Code 拒绝具有命令的 plugin 并将用户指向该 plugin 在 /plugin 中的自己的视图。批量安装中的其他 plugins 仍然安装。依赖被拒绝 plugin 的 plugin 无法安装，直到用户自己安装被拒绝的 plugin。
• 后台自动更新，或会话启动用于从未下载其存档的 plugin：Claude Code 在 /plugin 错误选项卡中列出 plugin，以便用户知道手动安装或更新它。找到条目的自动更新仍然宣传已安装版本列表无。

​

Command 源

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

• 目录在其顶级没有 plugin 内容，例如 .claude-plugin/ 目录或 skills/、commands/、agents/ 或 hooks/ 目录
• 目录是 Claude Code 启动的目录，或其父目录之一
• 在 Windows 上，路径是 UNC 路径

​

复制模式和链接模式

​

用户如何接受命令

• 当用户从 /plugin 中的 plugin 详情屏幕安装 plugin，或在交互式终端中使用 claude plugin install 或 claude plugin update 安装或更新它时，Claude Code 首先向他们显示确切的命令字符串，并为该安装记录接受的命令。可以在接受相同命令的记录接受上进行的 claude plugin update 显示无。在非交互式 shell 中，例如配置脚本，传递 --yes 到 claude plugin install 或 claude plugin update 以接受它打印的命令。
• 每条其他路径仅运行用户已接受的命令。这包括从 /plugin 启动的更新和何时 Claude Code 重新运行命令中描述的后台运行。当未接受任何内容时，Claude Code 拒绝运行命令并告诉用户如何查看它。Claude Code 从不将 command 源 plugin 安装为另一个 plugin 的依赖项，所以用户自己先安装它。
• 如果你更改条目的 command 或切换其 mode，用户保留他们已有的版本，Claude Code 停止重新运行命令。在交互式会话中，/plugin 错误选项卡显示新命令，直到用户通过运行 claude plugin update <plugin>@<marketplace> 查看并接受它。

​

Claude Code 何时重新运行命令

• 每次用户安装或更新 plugin 时
• 每个会话一次用于每个启用的 command 源 plugin，在后台，会话启动后不久。此运行不通过 marketplace 自动更新，所以它不依赖 marketplace 的自动更新设置
• 在启动或 /reload-plugins 时，当启用的 plugin 的已安装版本从 plugin 缓存中丢失时

​

高级 plugin 条目

{
  "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：你可以指定多个目录或单个文件。路径相对于 plugin 根目录，必须保持在其内部。
  • Claude Code 拒绝解析到 plugin 目录外的路径，例如 ./../shared.md，带有 path escapes plugin directory 错误，仍然加载 plugin 而不带该组件
• ${CLAUDE_PLUGIN_ROOT}：在 hook 命令和 MCP server 配置中使用此变量来引用 plugin 安装目录中的文件。
  • 查看替换表了解每个服务器类型在哪些配置字段中替换它
  • 对于应该在 plugin 更新后保留的依赖项或状态，请改用 ${CLAUDE_PLUGIN_DATA}
• strict: false：由于这设置为 false，plugin 不需要自己的 plugin.json。marketplace 条目定义了一切。见下面的 Strict 模式。

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

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

​

Strict 模式

• strict: true：plugin 有自己的 plugin.json 并管理自己的组件。marketplace 条目可以在顶部添加额外的 skills 或 hooks。这是默认值，适用于大多数 plugins。
• strict: false：marketplace 操作员想要完全控制。plugin repo 提供原始文件，marketplace 条目定义这些文件中的哪些被公开为 skills、agents、hooks 等。当 marketplace 以不同于 plugin 作者意图的方式重组或策划 plugin 的组件时很有用。

​

托管和分发 marketplaces

​

在 GitHub 上托管（推荐）

1. 创建存储库：为你的 marketplace 设置一个新存储库
2. 添加 marketplace 文件：使用你的 plugin 定义创建 .claude-plugin/marketplace.json
3. 与团队共享：用户使用 /plugin marketplace add owner/repo 添加你的 marketplace

​

在其他 git 服务上托管

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

​

私有存储库

​

你运行的命令

​

后台自动更新

• 设置 CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 以在后台 pull 失败时保留现有克隆，而不是删除并重新克隆。你的 plugins 继续从最后同步的状态工作，使用 /plugin marketplace update 的手动更新仍然使用你的凭证进行 pull。
• 配置 git 凭证助手，例如使用 gh auth setup-git 用于 GitHub，以便重新克隆回退可以在不提示的情况下进行身份验证。

git config --global url."https://x-access-token:YOUR_TOKEN@github.com/acme-corp/plugins".insteadOf "https://github.com/acme-corp/plugins"

​

通过组织设置分发

• marketplace 存储库必须是私有或内部的。组织同步通过 Claude GitHub App 或你的组织的 GitHub Enterprise App 读取它。
• 每个 plugin 源必须是 github、url 或 git-subdir 类型，或相对路径，以 ./ 开头。如果你在 metadata.pluginRoot 下按裸名称列出 plugin，组织同步会将其拒绝为不支持的源，所以写出路径，例如 ./plugins/deploy-tools。
• plugin 源可以在两种情况下是私有的：
  • 与 marketplace 存储库的所有者共享的 github.com 源
  • 在你的组织的 GitHub Enterprise 主机上安装了 GHE App 的源
• 组织同步在没有凭证的情况下获取所有其他源，所以不同所有者下的 github.com 存储库和其他主机上的存储库（例如 GitLab 或 Bitbucket）必须是公开的。

{
  "name": "deploy-tools",
  "source": "./plugins/deploy-tools"
}

​

将可执行文件保留在顶级 bin 目录之外

• Marketplace 同步：组织同步拒绝该 plugin 并同步 marketplace 的其余部分。错误消息以 Plugin contains a top-level bin/ directory 开头。
• 直接上传：如果你改为在组织设置 > Plugins中上传 plugin，claude.ai 会以相同的消息拒绝上传。

​

为你的团队要求 marketplaces

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

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

​

为容器预填充 plugins

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

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

• 只读：种子目录永远不会被写入。由于 git pull 会在只读文件系统上失败，种子 marketplaces 的自动更新被禁用。
• 种子条目优先：在每次启动时，种子中声明的 marketplaces 会覆盖用户配置中的任何匹配条目。要选择退出种子 plugin，请使用 /plugin disable 而不是删除 marketplace。
• 路径解析：Claude Code 通过在运行时探测 $CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/ 来定位 marketplace 内容，而不是信任存储在种子 JSON 内的路径。这意味着即使在与构建时不同的路径上挂载，种子也能正确工作。
• 变更被阻止：针对种子管理的 marketplace 运行 /plugin marketplace remove 或 /plugin marketplace update 会失败，并提示你要求管理员更新种子镜像。
• 与设置组合：如果 extraKnownMarketplaces 或 enabledPlugins 声明的 marketplace 已经存在于种子中，Claude Code 使用种子副本而不是克隆。

​

托管 marketplace 限制

​

常见配置

{
  "strictKnownMarketplaces": []
}

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "anthropics/claude-plugins-official"
    }
  ]
}

• 在机器首次交互启动之前运行的非交互环境。
• Claude Code 已在阻止 marketplace 的策略下以交互方式运行的机器，例如空数组锁定。Claude Code 记录被阻止的尝试，在策略更改后不重试。

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

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/*"
    }
  ]
}

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

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

​

限制如何工作

• 对于 GitHub 源：repo 是必需的，要么命名一个存储库，要么使用所有者通配符形式 owner/* 来覆盖该所有者下的每个存储库。有关通配符条目如何匹配（包括大小写规则），请参阅所有者通配符。对于单个存储库条目，ref 必须完全匹配或在 marketplace 源和允许列表条目中都不存在，相同的规则适用于 path
• 对于 URL 源：完整 URL 必须完全匹配
• 对于 hostPattern 源：marketplace 主机与正则表达式模式匹配
• 对于 pathPattern 源：marketplace 的文件系统路径与正则表达式模式匹配

​

版本解析和发布渠道

​

设置发布渠道

• 部署单独的端点管理设置（例如托管设置文件或 MDM 配置文件）到每个组的设备。Claude Code 如何组合托管源说明每个组的文件或配置文件是否适用于也有组织范围源的设备。
• 为每个组定义一个 Claude apps gateway 策略。网关应用第一个匹配规则适合用户的策略，所以对策略进行排序，以便每个用户到达其组的策略。组策略的 extraKnownMarketplaces 替换全局策略的映射而不是与其合并，所以在组的策略中列出组需要的每个 marketplace，而不仅仅是其渠道 marketplace。

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

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

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

​

固定依赖版本

​

重命名或删除 plugin

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

• 如果条目指向新名称，Claude Code 在其新名称下加载 plugin 并显示一行通知，例如 在"acme-tools" marketplace 中重命名为"code-formatter"。然后它在用户、项目和本地设置范围中为 enabledPlugins 和 pluginConfigs 都将旧键重写为新键，所以通知只出现一次。
• 对于 null 条目，Claude Code 删除旧键，通知报告 plugin 已从 marketplace 中删除。
• 如果重命名的 plugin 使用远程源，例如 github 或 npm，Claude Code 在重命名后报告 plugin-cache-miss，用户必须运行 /plugin install 一次以在新名称下获取它。

​

验证和测试

claude plugin validate .

/plugin validate .

/plugin marketplace add ./path/to/marketplace

/plugin install test-plugin@marketplace-name

​

从 CLI 管理 marketplaces

​

Plugin marketplace add

claude plugin marketplace add <source> [options]

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

claude plugin marketplace add acme-corp/claude-plugins

claude plugin marketplace add acme-corp/claude-plugins@v2.0

claude plugin marketplace add https://gitlab.example.com/team/plugins.git

claude plugin marketplace add https://example.com/marketplace.json

claude plugin marketplace add ./my-marketplace

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

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

​

Plugin marketplace list

claude plugin marketplace list [options]

​

Plugin marketplace remove

claude plugin marketplace remove <name> [options]

• <name>：marketplace 名称要删除，如 claude plugin marketplace list 所示。这是来自 marketplace.json 的 name，而不是你传递给 add 的源

​

Plugin marketplace update

claude plugin marketplace update [name]

• [name]：marketplace 名称要更新，如 claude plugin marketplace list 所示。如果省略，更新所有 marketplaces

​

故障排除

​

Marketplace 未加载

• 验证 marketplace URL 是否可访问
• 检查 .claude-plugin/marketplace.json 是否存在于指定路径
• 使用 claude plugin validate . 或 /plugin validate . 确保 JSON 语法有效。要检查 skill、agent 和 command frontmatter，请参阅验证没有 manifest 的 plugin 或目录
• 对于私有存储库，确认你有访问权限

​

Marketplace 验证错误

• 包括 source 为 . 的 plugins
• 在 marketplace.json 位于 .claude-plugin 目录外时运行，针对文件自己的目录解析源
• 即使文件的另一部分有 schema 错误，也报告每个条目的问题

• Marketplace has no plugins defined：将至少一个 plugin 添加到 plugins 数组
• No marketplace description provided：添加顶级 description 以帮助用户理解你的 marketplace
• Plugin name "x" is not kebab-case：重命名为仅包含小写字母、数字和连字符（例如，my-plugin）。Claude Code 接受其他形式，但 claude.ai marketplace 同步会拒绝它们。
• Marketplace name "x" is reserved in Claude Desktop：marketplace 名称为 org、org-provisioned 或 unknown，任何大小写。Claude Code 接受这些名称，但 Claude Desktop 的托管 marketplace 同步会拒绝整个 marketplace。重命名 marketplace。在 v2.1.221 之前，claude plugin validate 没有运行此检查。
• Marketplace name "x" is not accepted by Claude Desktop 或 Plugin name "x" is not accepted by Claude Desktop：Claude Desktop 接受最多 128 个字符的名称，由字母、数字、.、_ 和 - 组成，以字母或数字开头。Claude Code 接受其他形式，但 Claude Desktop 的托管 marketplace 同步会拒绝名称检查失败的 marketplace，并静默删除名称检查失败的 plugin 条目。重命名 marketplace 或 plugin。在 v2.1.221 之前，claude plugin validate 没有运行这些检查。

​

验证没有 manifest 的 plugin 或目录

• 命名该 skills 目录以检查 plugin 的根 SKILL.md。
• 命名 plugin 目录以检查其余部分。

• plugin 或 .claude 根目录下的链接 skills、agents 或 commands 目录：Claude Code 警告其中没有任何内容被读取。
• skills、agents 或 commands 目录内的链接条目：Claude Code 跳过它并警告，每个目录，它跳过了多少条目，会话会加载。
• 你命名的 skills、agents 或 commands 目录本身是符号链接，或其父 .claude 目录是：Claude Code 报告错误并检查其中的任何内容。改为命名真实目录。

• 其 skills 目录链接到同级 plugin 的 skills 的 plugin：命名同级 plugin 的目录。
• ~/.claude/skills 或 .claude/skills 中的符号链接 skill 条目：Claude Code 在会话中跟随该条目。要检查它，命名一个名为 skills 的目录，该目录包含真实文件夹。

• YAML frontmatter failed to parse: ...：修复 skill、agent 或 command 文件的 frontmatter 块中的 YAML。在你这样做之前，会话从文件中读取不到 frontmatter 字段
• Invalid JSON syntax: ... 在 hooks/hooks.json 上：修复 JSON 语法。在你这样做之前，会话加载 plugin 时不带该文件中的 hooks。Claude Code 仅在 plugin 运行中报告此错误

​

Plugin 安装失败

• 验证 plugin 源 URL 是否可访问
• 检查 plugin 目录是否包含必需的文件
• 对于 GitHub 源，确保存储库是公开的或你有访问权限
• 通过手动克隆/下载来测试 plugin 源
• 如果源同时固定了 ref 和 sha，删除的上游分支或标签不会阻止大多数 git 主机（包括 GitHub、GitLab 和 Bitbucket）上的安装。在不支持通过 SHA 获取提交的服务器上（如 AWS CodeCommit），ref 必须仍然存在，固定的提交必须可从其到达。如果安装仍然失败，请确认固定的提交仍然存在于存储库中

​

私有存储库身份验证失败

• 验证你已使用你的 git 提供商进行身份验证（例如，对于 GitHub 运行 gh auth status）
• 检查你的凭证助手是否配置正确：git config --global credential.helper
• 运行 git ls-remote <marketplace-url> 来测试 git 是否可以自行进行身份验证。如果 git 要求输入用户名或密码，请先存储凭证：对于 GitHub over HTTPS，运行 gh auth setup-git，对于 SSH 远程，将你的密钥加载到 ssh-agent

• 默认情况下，后台刷新会为拉取禁用 git 凭证助手，因此拉取无法通过 HTTPS 进行身份验证。在 ssh-agent 中加载了密钥的 SSH 远程仍然可以进行身份验证。失败的拉取会触发从头重新克隆，这使用你存储的凭证，但在大型存储库上可能超时
• 设置 CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 以在后台拉取失败时保留现有克隆
• 配置 git 凭证助手，例如 gh auth setup-git，以便重新克隆回退可以进行身份验证
• 如果重新克隆在大型存储库上超时，请使用 CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS 增加限制
• 配置一个 git URL 重写 作用于 marketplace 存储库，以便后台拉取直接进行身份验证
• 或使用 /plugin marketplace update <name> 手动更新私有 marketplaces，这使用你的凭证

​

Marketplace 更新在离线环境中失败

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

​

Git 操作超时

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000  # 5 minutes

​

相对路径 Plugins 在基于 URL 的 Marketplaces 中失败

• 使用外部源：将 plugin 条目更改为除相对路径外的任何 plugin 源：
  { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }
  
• 使用基于 Git 的 Marketplace：在 Git 存储库中托管你的 marketplace 并使用 git URL 添加它。基于 Git 的 marketplaces 克隆整个存储库，使相对路径有效。

​

安装后文件未找到

​

另见

• 发现和安装预构建的 plugins - 从现有 marketplaces 安装 plugins
• Plugins - 创建你自己的 plugins
• Plugins 参考 - 完整的技术规范和架构
• Plugin 设置 - Plugin 配置选项
• strictKnownMarketplaces 参考 - 托管 marketplace 限制