Claude Code 外掛市集：打包與發佈指南

Claude Code 外掛是一個目錄，它將技能（skills）、代理（agents）、掛鉤（hooks）和 MCP 伺服器捆綁在一起，讓 Claude Code 能將它們作為一個單元安裝。而市集則是一個 Git 儲存庫，其中包含一個 .claude-plugin/marketplace.json 檔案，用於列出這些外掛。

外掛的設定清單中只需要「名稱」（name），而市集檔案中則需要「名稱」（name）、「擁有者」（owner）和「外掛」（plugins）。如果儲存庫是私有的，那麼市集也是私有的。本文中的所有指令和欄位都已根據目前的 Claude Code 文件和 claude plugin --help（版本 2.1.299）進行了驗證。

總而言之，外掛是一種打包方式，能將技能、代理、掛鉤和 MCP 伺服器以單一名稱和版本一起安裝。.claude-plugin/plugin.json 僅包含設定清單，其他所有內容都位於外掛的根目錄。發佈一個包含 .claude-plugin/marketplace.json 的儲存庫，使用者即可執行 /plugin marketplace add owner/repo，然後執行 /plugin install name@marketplace 來安裝。更新只會在版本變更時才會生效。

對於團隊，可以在受管設定或儲存庫的 .claude/settings.json 中使用 extraKnownMarketplaces 和 enabledPlugins。請注意，外掛會以您的權限執行程式碼，因此在安裝前務必閱讀其掛鉤、.mcp.json 和 bin/ 目錄。

技能、子代理、掛鉤和 MCP 伺服器都可以獨立運作。~/.claude/skills/ 中的技能在您機器上的每個專案中都可用。當您希望將多個組件一起安裝、與隊友共享或以版本發佈時，才需要建立外掛。

外掛中的技能和代理會以外掛名稱作為前綴，因此兩個外掛即使都包含一個 hello 技能也不會衝突。關於層級問題，請參閱 MCP vs CLI vs skills 的說明。

| 項目 | 說明 | 是否執行程式碼？ | 儲存位置 | 可共享形式 |

|---|---|---|---|---|

| 技能 | Claude 在相關時載入的 SKILL.md 指令，也可作為指令執行 | 否，它引導 Claude | skills/<name>/SKILL.md | 資料夾，或外掛內部 |

| MCP 伺服器 | Claude Code 連接的工具伺服器 | 是，stdio 伺服器是您機器上的一個程序 | .mcp.json | 設定檔，或外掛內部 |

| 掛鉤 | Claude Code 在生命週期事件時執行的指令 | 是，具有您權限的 shell 指令 | settings.json 或 hooks/hooks.json | 設定片段，或外掛內部 |

| 外掛 | 捆綁上述任何組合與設定清單的目錄 | 如果包含掛鉤、MCP 伺服器、監控器或 bin/ | 外掛根目錄，可選 .claude-plugin/plugin.json | 市集條目、zip 檔案或 --plugin-dir |

啟用外掛會產生一個成本：它會成為每個會話的一部分。每個技能、代理和 Claude 可以自行調用的指令的名稱和描述，在每個回合中都會存在於上下文（context）中，即使外掛中的任何內容都沒有執行，也會計入使用量。Claude Max API 點數規劃器會顯示較重的上下文佔用量對每月預算造成的影響。

外掛目錄的佈局在一個地方是嚴格的：只將 plugin.json 放在 .claude-plugin/ 內部。儲存在那裡的組件不會被載入。其他所有目錄都位於外掛的根目錄，例如：

```

deploy-tools/

├.claude-plugin/

│ └，plugin.json

├，skills/

│ └，deploy/

│ └，SKILL.md

├，agents/

│ └，reviewer.md

├，hooks/

│ └，hooks.json

├，bin/ (啟用時在 Bash 工具 PATH 中)

└.mcp.json

```

設定清單是可選的。如果沒有它，Claude Code 會從這些預設位置載入組件，並從市集條目或目錄中獲取名稱。您可以編寫一個設定清單來包含中繼資料、版本，或將組件放在預設位置之外。

值得了解的欄位包括：name（唯一必填鍵，使用 kebab-case，所有組件都會在其下命名空間，例如外掛 deploy-tools 中的代理 reviewer 會顯示為 deploy-tools:reviewer）、version（字串，不檢查 semver，設定後會將使用者固定到該版本，直到您更改它）、description、author（物件，name 必填）、homepage（必須解析為 URL，否則外掛載入失敗）、repository、license、keywords 和 displayName。

還有 skills、commands、agents、hooks、mcpServers（用於預設位置之外的組件的路徑或內聯設定，路徑以 ./ 開頭並保持在外掛根目錄內），以及 dependencies 和 userConfig（Claude Code 會提示輸入的值，sensitive: true 會將機密資訊排除在 settings.json 之外）。

技能位於 skills/<name>/SKILL.md，並作為 /plugin-name:skill-name 執行。代理是 agents/ 中的 Markdown 檔案。掛鉤位於 hooks/hooks.json，MCP 伺服器位於 .mcp.json。

外掛根目錄下的 CLAUDE.md 不會作為上下文載入，因此請將說明放在技能中。以 claude- 或 anthropic- 開頭的名稱會驗證失敗。未知的頂層鍵會被移除，並僅發出警告。

hooks/hooks.json 和 settings.json 中的掛鉤，其事件、匹配器和處理程序的巢狀結構是相同的。兩個主要差異在於：外掛掛鉤檔案將事件映射包裝在頂層的 "hooks" 鍵中，而裸露的事件映射則無法載入，但 plugin.json 中的內聯掛鉤沒有包裝器。

此外，捆綁的腳本是透過 ${CLAUDE_PLUGIN_ROOT} 引用，它會在每次更新時更改（對於必須在更新後保留的狀態，請使用 ${CLAUDE_PLUGIN_DATA}）。

外掛掛鉤會與您的使用者和專案掛鉤合併。掛鉤沒有前綴，因此如果一個掛鉤被遷移到外掛中，但仍保留在 settings.json 中，它將會執行兩次。

市集是一個包含 .claude-plugin/marketplace.json 的目錄或儲存庫。必填的頂層鍵是 name、owner（包含 name）和 plugins。每個外掛條目都需要 name 和 source。

```json

{

"name": "team-tools",

"description": "Plugins for my team",

"owner": {

"name": "Your Name"

},

"plugins": [

{

"name": "no-bypass",

"source": "./plugins/no-bypass",

"description": "Blocks git --no-verify and teaches commit hygiene"

}

]

}

```

source 是從市集根目錄（包含 .claude-plugin/ 的目錄，不能包含 ..）的相對路徑，或者是一個物件，可以是 github（repo、ref、sha）、url、git-subdir、npm、archive（透過 HTTPS 的 zip 檔案，可選 sha256 釘選）或 command。

請確保條目名稱與外掛 plugin.json 中的名稱相同，否則透過設定清單名稱安裝時會報告找不到外掛。像 claude-plugins-official 和 claude-community 這樣的名稱僅適用於來自 github.com/anthropics/ 的市集。

使用者只需註冊一次市集，然後即可按名稱安裝。在會話中：/plugin marketplace add your-org/your-marketplace，然後 /plugin install no-bypass@team-tools。

從 shell 中：claude plugin marketplace add 和 claude plugin install no-bypass@team-tools。add 指令接受 GitHub owner/repo、git URL、託管的 marketplace.json URL 或本地路徑。

附加 #<ref> 可以釘選分支或標籤。簡寫形式始終表示 github.com，因此 GitLab 使用者需要完整的 URL。URL 託管的市集只會下載 JSON，因此相對路徑條目在那裡會失敗。

這就是人們會花費一個下午的地方。使用者只有在計算出的版本變更時才會獲得新副本。如果您設定 "version": "1.0.0"，然後推送十個提交，claude plugin update 會報告外掛已經是最新版本。要麼在每次發佈時提高版本號，要麼從 plugin.json 和市集條目中省略它，讓提交 SHA 來決定。切勿在兩者中都設定版本：plugin.json 會默默地獲勝。

自動更新預設是關閉的，marketplace.json 中也沒有相關欄位。每個使用者可以在 /plugin 中的「市集」下啟用它，或者管理員在受管設定中設定 "autoUpdate": true。否則，使用者需要執行 claude plugin update name@marketplace。

透過條目上的 ref 或 40 個字元的 sha 來釘選發佈版本。claude plugin tag 會建立一個 {name}--v{version} 的 git 標籤。切勿重新命名已發佈的外掛；請改為在市集中添加 renames 映射。

對於團隊，一個私有的 GitHub 儲存庫就足夠了：任何可以複製它的人都可以從中安裝。Claude Code 沒有自己的 git 權杖，marketplace.json 也沒有憑證欄位，因此安裝會使用機器的 git 憑證。對於 HTTPS，gh auth login 然後 gh auth setup-git 會儲存一個。

如果沒有 GitHub SSH 金鑰，請設定 CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1。問題是：針對私有儲存庫的自動更新需要儲存的憑證，而必須提示的輔助程式會默默地失敗。

要為一個儲存庫註冊市集，請執行 claude plugin marketplace add your-org/your-marketplace --scope project 並提交它寫入的 .claude/settings.json。一旦貢獻者信任該資料夾，它就會生效。對於全公司範圍，已驗證的設定名稱會放在受管設定中：

```json

{

"extraKnownMarketplaces": {

"team-tools": {

"source": {

"source": "github",

"repo": "your-org/team-tools"

},

"autoUpdate": true

}

},

"enabledPlugins": {

"no-bypass@team-tools": true

}

}

```

受管設定會勝過所有其他範圍，因此使用者禁用外掛並不會阻止它載入；在受管 enabledPlugins 中設定 false 會在所有地方阻止外掛。strictKnownMarketplaces（別名 allowedMarketplaces）是一個允許列表，blockedMarketplaces 是一個優先檢查的阻止列表，而 disableSideloadFlags 會拒絕 --plugin-dir。

空的允許列表會阻止所有來源，包括官方市集，任何允許列表也會阻止 ~/.claude/skills/ 下的外掛，除非您添加 {"source": "skills-dir"}。這些別名需要 v2.1.232 或更高版本。

Claude Code 在首次互動式啟動時會註冊官方市集（claude-plugins-official），除非受管政策阻止它。社群和演示市集不會自動添加。要觸及所有人，請發佈一個公共市集儲存庫並分享這兩個指令，或者提交到 Anthropic 的目錄 claude.ai/directory/manage（需要付費的 claude.ai 方案；它會透過帳戶同步以 name@synced 的形式到達 Claude Code）。官方市集不接受透過該入口網站提交的內容。

Anthropic 將市集分為官方、社群和第三方層級，並表示名稱說明了誰發佈了目錄，而不是每個外掛的功能。

使用 claude --plugin-dir ./my-plugin（可重複，也接受 .zip 檔案）為一個會話載入外掛。將它指向單個外掛的根目錄，而不是市集根目錄，否則什麼都不會載入，也不會收到錯誤。編輯後，執行 /reload-plugins。

然後：claude plugin validate ./my-plugin 會檢查設定清單和每個技能、代理和指令的前置資料。在 CI 中添加 --strict。claude plugin validate ./my-marketplace 會檢查 JSON 和每個條目。

將相對路徑指向不存在的目錄會通過驗證，但在安裝時失敗。claude plugin marketplace add ./my-marketplace 並從中安裝。claude plugin details my-plugin 會列印組件清單。

文件將 CLAUDE_CONFIG_DIR 命名為 Claude Code 用來代替 ~/.claude 的設定目錄，但沒有發佈隔離安裝的逐步說明，因此請先在測試機器上嘗試。

Anthropic 的措辭是：外掛可以以您的使用者權限在您的機器上執行任意程式碼。掛鉤、監控器、MCP 伺服器和 LSP 伺服器在沙盒外執行，不受您的權限規則限制。技能和代理作為指令進入上下文。請像閱讀安裝腳本一樣閱讀外掛。對於容器方面，請參閱沙盒化 Claude Code 和 Codex。

來源：claude plugin marketplace list 會列印每個市集的來源。掛鉤：從頭到尾閱讀 hooks/hooks.json。詳細資訊窗格會顯示掛鉤存在，但不會顯示它執行什麼。MCP：閱讀 .mcp.json，了解每個伺服器的指令或 URL。

bin/：那裡的所有內容都會進入 Bash 工具的 PATH。清單：在複製的目錄上執行 claude --plugin-dir <dir> plugin details <name> 會列出技能、代理、帶有事件的掛鉤和伺服器。更新：如果開啟自動更新，審查過的文件可能會更改。

對於您不控制的市集，請釘選一個 SHA。使用 claude plugin uninstall 在您安裝的範圍內卸載；快取檔案會在 ~/.claude/plugins/cache/ 下保留 14 天。

一個儲存庫、一個市集、一個名為 no-bypass 的外掛，包含一個技能和一個 PreToolUse 掛鉤，用於阻止 git ... --no-verify。