SpyBara
Go Premium

plugins/marketplace-reference.md 2026-09-28 22:59 UTC to 2026-09-29 17:02 UTC

This page contains 535 additions and 0 deletions.

2026
Tue 29 17:57

Marketplace 參考

marketplace.json 欄位、外掛程式項目和外掛程式與 marketplace 來源物件的完整參考，包括每個欄位的有效位置。

marketplace.json 是定義外掛程式 marketplace 的檔案。它包含 marketplace 的名稱、其擁有者，以及每個外掛程式的一個項目。每個項目的外掛程式來源說明 Claude Code 從何處擷取該外掛程式。

marketplace 來源是一個單獨的物件，說明 Claude Code 從何處擷取 marketplace 檔案本身。您在設定中寫入一個，或當您執行 claude plugin marketplace add 時 Claude Code 會建立一個。

此參考適用於需要確切欄位名稱或值的 marketplace 維護者，以及需要知道哪些 source 值在 extraKnownMarketplaces、strictKnownMarketplaces 和 blockedMarketplaces 中有效的管理員。

尋找您正在寫入或讀取的部分：

Marketplace 檔案

在您的 marketplace 目錄中的 .claude-plugin/marketplace.json 處儲存 marketplace 檔案。如果您將檔案保存在存放庫中的其他位置，使用者必須在 extraKnownMarketplaces 中宣告 marketplace，並在其來源上設定 path，因為 claude plugin marketplace add 沒有此選項。

包含 .claude-plugin/ 的目錄稱為 marketplace 根目錄，每個相對外掛程式來源都從它解析，而不是從 .claude-plugin/。

每個使用者每個 name 註冊一個 marketplace，因此使用者一次不能有兩個同名的已註冊 marketplace。

Claude Code 會忽略未知的頂層鍵或外掛程式項目鍵，而不是拒絕它，因此拼寫錯誤會無聲地載入。claude plugin validate 將每個未知鍵報告為警告。

保留名稱

您不能為您的 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。claude plugin validate 接受此類名稱；新增 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 也在 strictKnownMarketplaces 和 blockedMarketplaces 中顯示為 {"source": "skills-dir"}，在 Source values valid only in policy lists 下描述。
  • npm、pip、uv、cargo、github 和 gh：以任何大小寫保留。此檢查需要 Claude Code v2.1.275 或更新版本。
  • 以 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。

當已註冊的 marketplace 因其名稱模仿官方名稱而停止載入時，claude plugin list 和 /plugin 報告 Claude Code refuses the marketplace name "<name>"。該訊息告訴您移除 marketplace。移除它也會解除安裝其外掛程式並刪除其已儲存的資料。此具名拒絕訊息需要 Claude Code v2.1.282 或更新版本。

頂層欄位

該表列出 Claude Code 從 marketplace.json 讀取的每個鍵。name、owner 和 plugins 是必需的。

欄位 類型 描述
name 字串 Marketplace 識別碼。沒有空格、控制字元或雙向格式化字元，沒有 / 或 \，沒有 ..，不是 .。請參閱 Reserved names。使用者在安裝外掛程式時在 @ 後輸入它
owner 物件 維護者資訊。name 是必需的；email 和 url 是可選的
plugins 陣列 Plugin entries。每個項目都單獨驗證，因此一個無效項目不會導致 marketplace 失敗
$schema 字串 JSON Schema URL 用於編輯器自動完成。在載入時忽略
description 字串 向使用者顯示的 Marketplace 描述。claude plugin validate 在缺少時發出警告
version 字串 Marketplace 資訊清單版本
metadata.description、metadata.version 字串 description 和 version 的替代位置
metadata.pluginRoot 字串 裸外掛程式來源名稱解析的目錄。請參閱 Relative path plugin source。需要 Claude Code v2.1.239 或更新版本
forceRemoveDeletedPlugins 布林值 當 true 時，您從 plugins 中移除的外掛程式會在使用者的機器上解除安裝。請參閱 Host and maintain a marketplace
allowCrossMarketplaceDependenciesOn 字串陣列 其外掛程式可能被安裝為此 marketplace 外掛程式依賴項的 Marketplace 名稱。當您安裝外掛程式時，只有該外掛程式自己的 marketplace 中的清單適用於其整個依賴鏈。請參閱 Plugin dependencies
renames 物件 從前一個外掛程式 name 到其目前名稱的對應，或對於您移除的外掛程式為 null。需要 Claude Code v2.1.193 或更新版本。請參閱 Host and maintain a marketplace

外掛程式項目

marketplace.json 的頂層 plugins 陣列中的每個物件命名一個外掛程式並說明從何處擷取它。name 和 source 是必需的。

項目也接受每個 plugin.json 欄位，例如 description、version、author、commands 和 hooks。有關這些欄位何時適用，請參閱 How an entry combines with plugin.json。

該表列出項目自己的欄位和資訊清單欄位，其含義在項目中改變。

欄位 類型 描述
name 字串 外掛程式識別碼，沒有空格、控制字元或雙向格式化字元。使用者在安裝時在 @ 前輸入它，即使外掛程式自己的 plugin.json 設定了不同的 name
source 字串或物件 從何處擷取外掛程式。請參閱 Plugin sources
description 字串 在 /plugin 清單和詳細資訊中顯示
version 字串 外掛程式的版本字串。當 plugin.json 也設定 version 時，plugin.json 優先，claude plugin validate 發出警告。請參閱 Plugin loading reference
category 字串 用於組織目錄的自由格式類別
tags 字串陣列 用於搜尋的自由格式標籤
strict 布林值 預設 true。plugin.json 是否是外掛程式元件的決定性來源。請參閱 Strict mode
relevance 物件 告訴 Claude Code 何時建議外掛程式的訊號。請參閱 Recommend plugins for your org
dependencies 陣列 必須為此外掛程式啟用的外掛程式。每個項目是 "name"、"name@marketplace" 或物件。請參閱 Plugin dependencies
defaultEnabled 布林值 預設 true。當使用者未在 enabledPlugins 中設定時，外掛程式是否在啟用時啟動。項目值優先於 plugin.json
displayName 字串 在 UI 中顯示的人類可讀名稱。當項目和外掛程式的 plugin.json 都未設定時，使用者看到外掛程式的 name
metadata 物件 用於您自己欄位的自由格式物件。Claude Code 不讀取它。需要 Claude Code v2.1.222 或更新版本
headers 物件 Claude Code 在下載此項目的 archive 時發送的 HTTP 標頭。此處設定的標頭替換來自 marketplace 來源的 headers 的同名標頭。需要 Claude Code v2.1.238 或更新版本
headersHelper 字串 列印此項目的存檔下載標頭的命令，作為一個 JSON 物件，用於過期的認證。項目也必須設定 "strict": false。需要 Claude Code v2.1.238 或更新版本。請參閱 Authenticate archive downloads

項目如何與 plugin.json 結合

項目的欄位以不同方式應用於已擷取的外掛程式，該外掛程式有自己的 .claude-plugin/plugin.json 和沒有的外掛程式：

  • 沒有 plugin.json：無論 strict 如何，項目都是資訊清單。項目中的每個資訊清單欄位都適用，包括 mcpServers、lspServers、userConfig 和 channels。
  • plugin.json 存在：plugin.json 是資訊清單。Strict mode 決定項目的六個元件欄位 commands、agents、skills、hooks、outputStyles 和 themes 是與其結合還是作為衝突被拒絕。項目 mcpServers、lspServers、userConfig 和 channels 不適用。在 plugin.json 中宣告它們。

項目中的 Hooks

將項目 hooks 寫為內聯物件，將 hook 事件名稱對應到匹配器陣列。如果您寫入檔案路徑或陣列，claude plugin validate 會通過它。這些 hooks 永遠不會執行，Claude Code 為外掛程式報告 not yet supported in a marketplace entry 錯誤。將基於檔案的 hooks 放在外掛程式自己的 hooks/hooks.json 或 plugin.json 中。

顯示欄位

項目和外掛程式自己的 plugin.json 都可以設定顯示欄位 displayName、description、author、homepage、repository、license 和 keywords。使用者在外掛程式清單和詳細資訊中看到這些值，在安裝前後：

  • 對於您在項目上設定的欄位，使用者看到項目的值，即使 plugin.json 設定了不同的值。
  • 對於項目未設定的欄位，使用者看到 plugin.json 值。

在安裝前，Claude Code 只能為具有 relative-path source 的項目讀取 plugin.json，其外掛程式檔案在 marketplace 內。對於具有任何其他來源類型的項目，使用者在安裝外掛程式之前只看到項目自己的欄位。

Strict mode

strict 決定當已擷取的外掛程式有自己的 plugin.json 且項目也宣告任何 component fields 時會發生什麼：commands、agents、skills、hooks、outputStyles 或 themes。使用 strict: true（預設值），Claude Code 將項目的元件欄位附加到 plugin.json，除了 hooks，其匹配器替換資訊清單的每個事件。使用 strict: false，宣告任何元件欄位的項目是衝突，外掛程式無法載入。該表顯示 strict、plugin.json 和項目的元件欄位的每個組合。

strict plugin.json 項目元件欄位 結果
任何 不存在 任何 項目是資訊清單
true（預設值） 存在 任何 plugin.json 是權威。Claude Code 將項目的元件欄位附加到它，除了 hooks，其匹配器 replace the manifest's per event
false 存在 無 plugin.json 是資訊清單，與 true 相同
false 存在 一個或多個 衝突。外掛程式無法載入，錯誤為 Plugin <name> has conflicting manifests: both plugin.json and marketplace entry specify components

Plugin 來源

Plugin 項目的 source 說明 Claude Code 從何處取得該 plugin。它可以是相對路徑字串，或是一個物件，其 source 鍵名指定類型，因此項目看起來像 "source": { "source": "github", "repo": "your-org/formatter" }。

下表列出每個 plugin 來源類型及其欄位。

類型 欄位 備註
相對路徑 字串本身 marketplace 內的目錄，從 marketplace 根目錄解析。必須以 ./ 開頭，除非您在 metadata.pluginRoot 下寫入裸名。"." 本身表示根目錄
github repo、ref、sha GitHub 儲存庫，格式為 owner/repo
url url、ref、sha 任何 git 儲存庫的 URL
git-subdir url、path、ref、sha git 儲存庫的一個子目錄，使用稀疏部分複製取得
npm package、version、registry npm 套件，使用您的 npm 用戶端取得並解包，不執行安裝指令碼
archive url、sha256 HTTPS 上的 Zip 檔案。需要 Claude Code v2.1.224 或更新版本
command command、timeout、mode 由 Claude Code 在使用者機器上執行的命令列印的目錄。需要 Claude Code v2.1.229 或更新版本

名稱 url 和 github 也是 marketplace 來源 類型，其中 url 表示直接連結到 marketplace.json 檔案，而非 git 儲存庫。git 僅作為 marketplace 來源存在，npm 同時作為兩者存在。git-subdir、archive 和 command 僅作為 plugin 來源存在。

對於 marketplace 儲存庫本身子目錄中的 plugin，使用相對路徑。對於其他儲存庫的子目錄，使用 git-subdir。

github、url 和 git-subdir 來源共享 ref 和 sha 欄位：

  • ref：分支或標籤。預設為儲存庫的預設分支。
  • sha：完整的 40 字元小寫提交 SHA。當您同時設定 ref 和 sha 時，Claude Code 會檢出 sha。在大多數 git 主機上，包括 GitHub、GitLab 和 Bitbucket，這表示即使上游的分支或標籤已被刪除，只要提交仍可從儲存庫到達，安裝就會成功。某些伺服器（例如 AWS CodeCommit）不支援按 SHA 取得提交。在這些伺服器上，ref 仍必須存在，且固定的提交必須可從其到達。

有關每種類型如何取得、快取和版本化的資訊，請參閱 Plugin 載入參考。

相對路徑 plugin 來源

路徑從 marketplace 根目錄解析。./plugins/formatter 是 <root>/plugins/formatter，即使 marketplace 檔案在 <root>/.claude-plugin/ 中。

包含 .. 的路徑會驗證失敗。在 macOS 和 Linux 上，Claude Code 拒絕在前導 ./ 之後任何位置包含反斜線的項目路徑，因此請使用正斜線寫入路徑。

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

相對路徑僅在 Claude Code 擁有 marketplace 檔案時才會解析，因此請檢查 marketplace 來源 類型：

  • github、git、file 和 directory：Claude Code 擁有 marketplace 檔案。
  • url：Claude Code 僅取得 marketplace.json，因此相對路徑無法解析。為每個 plugin 提供物件來源，例如 github 或 git-subdir。
  • settings：相對路徑被直接拒絕。

pluginRoot 下的裸名

裸名是單個目錄名稱，不含 /，例如 "formatter"。若要寫入裸名而非 ./ 路徑，請將 metadata.pluginRoot 設定為它們解析的目錄。使用 "pluginRoot": "./plugins"，"source": "formatter" 解析為 ./plugins/formatter。需要 Claude Code v2.1.239 或更新版本。

metadata.pluginRoot 有以下限制：

  • 它本身必須是 marketplace 內的相對路徑。
  • 它對已以 ./ 開頭的來源無效。
  • 包含 / 的來源（例如 team-a/formatter）不是裸名，即使設定了 metadata.pluginRoot 也仍需要 ./ 前綴。

github plugin 來源

repo 採用 owner/repo 格式。ref 和 sha 是選用的。

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

url plugin 來源

url 是完整的 git URL：https://、http://、file:// 或 git@。不需要 .git 後綴，因此 Azure DevOps 和 AWS CodeCommit URL 可以按原樣使用。此類型不採用 owner/repo 簡寫。

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

git-subdir plugin 來源

url 接受完整的 git URL 或 GitHub owner/repo 簡寫。path 是保存 plugin 的子目錄，Claude Code 僅下載該子目錄。

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

npm plugin 來源

npm 來源採用以下欄位：

  • package：套件名稱，或範圍名稱，例如 @your-org/formatter
  • version：版本或範圍
  • registry：不在預設登錄中的套件的登錄 URL

Claude Code 使用您的 npm 用戶端取得套件。套件的安裝指令碼（例如 preinstall 或 postinstall）永遠不會執行，其相依性在取得期間不會安裝。如果套件在其 package.json 旁有支援的鎖定檔案，Claude Code 會在單獨的步驟中安裝這些 Node.js 套件相依性，同樣禁用指令碼。

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

archive plugin 來源

url 必須使用 https://，且不能指向環回、連結本地或雲端中繼資料主機。

plugin 根目錄可能在 zip 的頂部或下一個目錄。

sha256 是檔案的摘要，為 64 個十六進位字元，大寫或小寫。當您設定它時，Claude Code 拒絕不符合的下載。

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

command plugin 來源

當安裝在使用者機器上的工具產生 plugin 目錄時，使用 command 來源，例如為使用者選擇的工具鏈呈現其 plugin 的 IDE。Claude Code 在使用者安裝或更新 plugin 時執行命令，並每個工作階段執行一次，因此使用者無需重新安裝即可獲得工具的變更輸出。

command 來源採用以下欄位：

  • command：shell 命令，列印 plugin 目錄的絕對路徑作為一行並退出 0。Claude Code 在執行前向使用者顯示整個字串以供審查。將其寫為可列印的 ASCII，最多 500 個字元，不含四個或更多空格的連續。
  • timeout：1 到 600 秒的整數。預設為 60。
  • mode：copy（預設）或 link。請參閱複製模式和連結模式。
{
  "name": "formatter",
  "source": {
    "source": "command",
    "command": "my-tool claude-plugin-path",
    "timeout": 120
  }
}

有關使用者如何接受命令的資訊，請參閱從您的 shell 安裝。有關您變更命令後使用者看到的內容，請參閱變更 command 來源的命令。管理員使用 disableCommandPluginSources 關閉 command 來源。

命令必須執行的操作

編寫命令以符合以下要求：

  • Shell 和工作目錄：Claude Code 通過 sh 或在 Windows 上通過 cmd.exe 從使用者的主目錄執行命令。提供絕對路徑或 PATH 上的命令。
  • 輸出：在 stdout 上列印恰好一行，即 plugin 目錄的絕對路徑，並在 timeout 秒內退出 0。
  • 目錄內容：目錄在命令退出時保存完整的 plugin。路徑可能因執行而異。

導致安裝或更新失敗的輸出

當命令退出非零、執行時間超過 timeout 或列印除一個絕對路徑以外的任何內容時，安裝或更新失敗。當列印的目錄是以下之一時，它也會失敗：

  • 無 plugin 內容：列印的目錄在其頂層沒有 plugin 內容，例如 .claude-plugin/ 目錄或 skills/、commands/、agents/ 或 hooks/ 目錄。
  • 工作階段自己的目錄：列印的目錄是 Claude Code 啟動的目錄或其父目錄之一。
  • 網路路徑：在 Windows 上，列印的路徑是 UNC 路徑。
  • 太大而無法複製：在複製模式中，目錄大於 256 MiB 或有超過 20,000 個項目。

mode 決定 Claude Code 是複製列印的目錄還是就地使用它：

  • copy：Claude Code 將目錄複製到 plugin 快取中，並從複製檔案的雜湊衍生 plugin 版本。您的工具可以在命令退出後刪除或重寫目錄。產生相同檔案的重新執行計為最新。
  • link：Claude Code 使用列印目錄的每個頂層項目的連結填充 plugin 的快取項目，並就地載入檔案。不複製任何內容，不雜湊檔案內容，大小限制不適用。將其用於太大而無法複製的目錄，例如呈現的 SDK 匯出。

連結模式 plugin 有以下要求：

  • 保持目錄就位：Claude Code 在每次啟動時通過連結載入 plugin，因此列印的目錄必須保持在原位，只要 plugin 保持安裝狀態。
  • 列印不同的路徑以表示新內容：版本來自列印目錄的真實路徑及其頂層項目，而非其內部的檔案。
  • 保持頂層符號連結在目錄內：如果頂層項目是指向列印目錄外的符號連結，安裝失敗。
  • 包含 node_modules：Claude Code 跳過連結模式 plugin 的 Node.js 套件相依性安裝，因此列印已包含 plugin 需要的套件的目錄。
  • 在目錄內啟動的工作階段：在列印目錄或其下方任何位置啟動的工作階段不載入 plugin。
  • 不在 Windows 上：Claude Code 拒絕在 Windows 上安裝連結模式 plugin。在那裡宣告 "mode": "copy"。

Marketplace 來源

marketplace 來源說明 Claude Code 從何處擷取 marketplace.json。CLI 在您新增 marketplace 時為您建立一個，您自己在設定中寫入一個：

類型名稱 url、git 和 github 在 marketplace 來源中的含義與在 plugin source 中不同：

類型名稱 作為 marketplace 來源 作為外掛程式來源
url 直接連結到 marketplace.json 檔案，具有欄位 url、headers 和 headersHelper 要複製的 git 存放庫，具有欄位 url、ref 和 sha
git 要複製的 git 存放庫，具有欄位 url、ref、path 和 sparsePaths 不存在
github GitHub 存放庫，具有欄位 repo、ref、path 和 sparsePaths GitHub 存放庫，具有欄位 repo、ref 和 sha，沒有 path

該表列出每個 marketplace 來源類型及其欄位、產生它的 claude plugin marketplace add 輸入，以及它在三個設定鍵中的作用。

類型 欄位 marketplace add 輸入 extraKnownMarketplaces strictKnownMarketplaces blockedMarketplaces
url url、headers、headersHelper 不匹配 git 形式的 http:// 或 https:// URL 載入 允許相同的 URL 封鎖相同的 URL
github repo、ref、path、sparsePaths owner/repo、owner/repo@ref 或 owner/repo#ref 載入 允許相同的 repo、ref 和 path。repo 可能是 owner/* 封鎖相同的，以及到相同存放庫的 git URL
git url、ref、path、sparsePaths user@host:path URL，或以 .git 結尾、包含 /_git/ 或命名 github.com 或 gitlab.com 存放庫的 https:// URL。#ref 固定 ref 載入 允許相同的 URL、ref 和 path 封鎖相同的，以及相同 github.com 存放庫的其他拼寫
npm package 未產生 無法載入：NPM marketplace sources not yet implemented 解析但不匹配任何內容，因為沒有任何內容註冊 npm marketplace 解析但不匹配任何內容
file path .json 檔案的路徑 載入 允許相同的路徑 封鎖相同的路徑
directory path 目錄的路徑 載入 允許相同的路徑 封鎖相同的路徑
settings name、plugins、owner 未產生 載入 允許具有相同 name 和相同 plugins 的項目 封鎖相同的 name
skills-dir 無 未產生 無法載入：Unsupported marketplace source type 保持 skills-directory plugins 在設定允許清單時載入。請參閱 Source values valid only in policy lists 停止 skills-directory 外掛程式載入
hostPattern hostPattern 未產生 無法載入：Unsupported marketplace source type 允許主機匹配的 github、git 和 url 來源 封鎖這些來源
pathPattern pathPattern 未產生 無法載入：Unsupported marketplace source type 允許 path 匹配的 file 和 directory 來源 封鎖這些來源

按類型的欄位

該表列出每個 marketplace 來源欄位，該欄位具有預設值、約束或特定於其類型的含義。

欄位 類型 描述
url url 連結到 marketplace.json 檔案。Claude Code 僅下載該檔案，因此 marketplace 的外掛程式無法使用 relative-path sources
url git 要複製的 git 存放庫
headers url Claude Code 使用擷取發送的 HTTP 標頭對應，用於已驗證的主機
headersHelper url 列印標頭的命令，其值太短暫而無法在 headers 中列出。需要 Claude Code v2.1.238 或更新版本。請參閱 Authenticate archive downloads
repo github 在 marketplace add 和 extraKnownMarketplaces 中，repo 必須命名一個存放庫。marketplace add 拒絕 owner/* 作為無效的 owner/repo 簡寫；在 extraKnownMarketplaces 中 Claude Code 按字面意思取用，複製失敗
ref github、git 分支或標籤。預設為存放庫的預設分支
path github、git marketplace 檔案在存放庫內的路徑。預設為 .claude-plugin/marketplace.json
path file marketplace 檔案本身。Claude Code 就地讀取它，並將上面兩個級別的目錄作為 marketplace 根目錄，因此將檔案保存在 <root>/.claude-plugin/marketplace.json
path directory marketplace 根目錄，包含 .claude-plugin/marketplace.json 的目錄
sparsePaths github、git 用於稀疏簽出的目錄陣列，例如 [".claude-plugin", "plugins"]。claude plugin marketplace add --sparse 設定它
skipLfs github、git 接受且無效果。請參閱 Keep plugin files out of Git LFS
name settings 必須等於 extraKnownMarketplaces 鍵，不能是 reserved name
plugins settings 內聯目錄，沒有託管檔案。每個項目採用 name、source、description、version、strict、headers 和 headersHelper。將每個項目的 source 寫為物件類型，因為相對路徑沒有要解析的存放庫

僅在政策清單中有效的來源值

hostPattern、pathPattern、skills-dir 和 repo 的 owner/* 形式僅在兩個政策清單中有效，strictKnownMarketplaces 和 blockedMarketplaces：

  • hostPattern 和 pathPattern：Claude Code 在擷取前針對來源測試的正規表達式。
  • skills-dir：不是來源。如果您根本設定 strictKnownMarketplaces，skills-directory plugins 停止載入，直到您將 {"source": "skills-dir"} 新增到該清單。
  • owner/*：作為 github repo 值，匹配恰好該 GitHub 擁有者下的每個存放庫。需要 Claude Code v2.1.223 或更新版本。

有關匹配順序、確切 ref 語義和配方，請參閱 Manage plugins for your organization。

設定中的來源物件

extraKnownMarketplaces 值是從 marketplace 名稱到具有 source 的物件的對應。此項目從其 main 分支的 git 存放庫註冊 marketplace：

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

strictKnownMarketplaces 和 blockedMarketplaces 是來源物件的陣列。此允許清單允許一個 GitHub 擁有者和一個內部主機：

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

驗證訊息

claude plugin validate <path> 接受 marketplace 根目錄或 marketplace 檔案本身。它會列印錯誤和警告。如需結束代碼和 --strict，請參閱 plugin validate。

訊息會以索引命名外掛程式項目，寫作 plugins.1.source 或 plugins[1].source。

以項目索引和 plugin.json → 為前綴的訊息，例如 plugins[2] plugin.json →，是關於該外掛程式自身的檔案。claude plugin validate 報告錯誤列出這些訊息及其修正方式。

提及 Claude Desktop 旗標名稱的警告，這些名稱 Claude Code 接受但 Claude Desktop 拒絕，因為 Claude Desktop 的名稱規則更嚴格。

下表將 marketplace 層級的訊息對應到各自相關的欄位。

訊息 層級 欄位
Marketplace must have a name 錯誤 name 為空
Marketplace name cannot contain spaces. Use kebab-case (e.g., "my-marketplace") 錯誤 name
Marketplace name cannot contain path separators (/ or \), ".." sequences, or be "." 錯誤 name
Marketplace name impersonates an official Anthropic/Claude marketplace 錯誤 name。請參閱保留名稱
Marketplace name cannot contain control or bidirectional-formatting characters 錯誤 name 包含控制字元（例如逸出或換行符）或 Unicode 雙向格式化字元
Marketplace name "inline" is reserved for --plugin-dir session plugins, and the builtin, skills-dir, synced, claude-plugin-test, npm, pip, uv, cargo, github, and gh variants 錯誤 name
Author name cannot be empty 錯誤 owner.name
Plugin name cannot contain spaces. Use kebab-case (e.g., "my-plugin") 錯誤 plugins[i].name
Plugin name cannot contain control or bidirectional-formatting characters 錯誤 plugins[i].name
Duplicate plugin name "x" found in marketplace 錯誤 兩個項目共享一個 name
plugins.i.source: Invalid input 錯誤 該項目的 source 不符合任何類型。請參閱來源上的無效輸入
plugins[i].source: Path contains "..": <path> 錯誤 逃逸 marketplace 根目錄的相對 source
source.source: 'unsupported' is a parse-time placeholder and cannot be authored 錯誤 plugins[i].source
Plugin "x" sets headersHelper but is not "strict": false 錯誤 plugins[i].headersHelper，在 archive 項目上
chain does not resolve (<reason>) — target must be a name in plugins[], a key in renames, or null 錯誤 renames.<old>
target "x" is not a valid plugin name (PluginIdSchema) 錯誤 renames.<old>
Unknown field 'x'. Claude Code ignores it at load time. 警告 頂層、metadata 下、項目中或項目 relevance 下的命名鍵
Marketplace has no plugins defined 警告 plugins 為空
Plugin "x" sets headers/headersHelper, which only apply to "archive" sources; they have no effect on this entry. 警告 plugins[i].headers 或 plugins[i].headersHelper，在 source 不是 archive 的項目上
Plugin "x" fetches its archive with a headersHelper but sets no sha256 pin 警告 plugins[i].source.sha256
Header "x" is a request-routing/identity header that catalog entries may not set; Claude Code drops it at download time. 警告 plugins[i].headers.<name>
Local source "x" is or traverses a symlink, so <path> was not read 警告 plugins[i].source
No marketplace description provided. Adding a description helps users understand what this marketplace offers 警告 description
Entry declares version "x" but <path>/plugin.json says "y". At install time, plugin.json wins 警告 plugins[i].version，在相對路徑項目上
'relevance' must be an object containing topic and signals; got <type>. It will be ignored at load time. 警告 plugins[i].relevance
'metadata' must be a free-form object; got <type>. It will be ignored at load time. 警告 plugins[i].metadata
'experimental' must be an object containing component declarations; got <type>. It will be ignored at load time. 警告 plugins[i].experimental
Marketplace name "x" is reserved in Claude Desktop 警告 name 是 org、org-provisioned 或 unknown。Claude Desktop 拒絕 marketplace
Marketplace name "x" is not accepted by Claude Desktop (letters, digits, ".", "_", "-"; must start alphanumeric; max 128 chars) 警告 name。Claude Desktop 拒絕 marketplace
Plugin name "x" is not accepted by Claude Desktop (letters, digits, ".", "_", "-"; must start alphanumeric; max 128 chars) 警告 plugins[i].name。Claude Desktop 捨棄該項目

來源上的無效輸入

source 上的 Invalid input 表示該物件不符合任何來源類型。檢查這些原因：

  • 不以 ./ 開頭的相對路徑，除了 "." 或 bare name
  • 包含 .. 的 npm package
  • 不是外掛程式來源之一的 source 類型
  • 已知類型但缺少必需欄位或類型錯誤，例如沒有 repo 的 github

驗證未捕捉的失敗

claude plugin validate 不會報告每個失敗。寫成檔案路徑或陣列的項目 hooks 通過驗證，錯誤僅在外掛程式載入時出現，如項目中的 Hooks 所述。擷取 source 的錯誤也僅在安裝後出現，不在驗證中。

claude plugin list 顯示載入失敗的外掛程式及其錯誤，疑難排解外掛程式涵蓋載入時間字串。

後續步驟