SpyBara
Go Premium

plugins/manifest-reference.md 2026-09-24 22:57 UTC to 2026-09-25 23:58 UTC

This page contains 710 additions and 0 deletions.

2026
Fri 25 23:58

Plugin manifest 參考

plugin.json 的完整參考：每個欄位的類型和預設值、接受的路徑形式，以及 userConfig 和環境變數架構。

Plugin manifest 是位於 plugin 的 .claude-plugin/ 目錄中的 plugin.json 檔案。它包含 plugin 的中繼資料和 Claude Code 提示使用者輸入的 userConfig 值。它也宣告任何您內聯定義或保留在其預設位置之外的元件。

本參考適用於 plugin 建立者，以及將元件欄位放在 marketplace 項目中的 marketplace 擁有者。

從符合您要查詢內容的部分開始：

  • 一個欄位：欄位表提供每個欄位的類型、是否必需、其預設值和接受的內容。路徑規則涵蓋 ./ 前綴和每個元件路徑的包含
  • 一個 userConfig 選項或一個 channels 項目：使用者設定和頻道架構
  • ${CLAUDE_PLUGIN_ROOT} 或 plugin 可以參考的另一個變數：環境變數
  • 每個元件的檔案位置：標準配置
  • 來自 claude plugin validate 的訊息：疑難排解頁面列出每條訊息及其修正，並連結到本頁的相關部分

Manifest 檔案

manifest 是選用的。沒有它，Claude Code 會載入它在標準配置中找到的元件。然後 plugin 名稱來自 marketplace 項目，或在您使用 --plugin-dir 載入 plugin 時來自目錄名稱。

當您想要中繼資料、預設目錄外的元件、userConfig 或內聯元件定義時，請寫入 manifest。

將 manifest 儲存在 plugin 根目錄下的 .claude-plugin/plugin.json。將所有其他 plugin 檔案放在 plugin 根目錄，而不是 .claude-plugin/ 內。這包括 skills/、commands/ 和 hooks/。

以下範例設定欄位表中的大多數鍵。它在包含每個參考路徑的 plugin 目錄中通過驗證。

{
  "name": "deploy-tools",
  "displayName": "Deploy Tools",
  "version": "1.2.0",
  "description": "Deployment commands, a review agent, and a status monitor",
  "author": {
    "name": "Example Team",
    "email": "dev@example.com",
    "url": "https://example.com"
  },
  "homepage": "https://example.com/docs/deploy-tools",
  "repository": "https://github.com/example/deploy-tools",
  "license": "MIT",
  "keywords": ["deployment", "ci"],
  "defaultEnabled": true,
  "dependencies": ["secrets-vault"],
  "metadata": { "catalogId": "cat-123" },
  "skills": ["./extra-skills/"],
  "commands": {
    "status": {
      "source": "./commands/status.md",
      "description": "Show the current deployment status"
    },
    "about": {
      "content": "Explain what the deploy-tools plugin provides.",
      "description": "Describe this plugin"
    }
  },
  "agents": ["./agents/reviewer.md"],
  "hooks": "./config/extra-hooks.json",
  "mcpServers": {
    "deploy-api": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  },
  "lspServers": "./.lsp.json",
  "outputStyles": "./styles/",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./config/monitors.json"
  },
  "userConfig": {
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "Token for the deployment API",
      "sensitive": true
    }
  }
}

無法識別的欄位

無法識別的頂層鍵會被移除，而 userConfig 選項、channels 項目、lspServers 設定或 monitors 項目內無法識別的鍵會被拒絕：

  • 頂層欄位：欄位被移除，plugin 載入。claude plugin validate 將每個無法識別的頂層欄位報告為警告
  • 嚴格物件：userConfig 選項、channels 項目、lspServers 設定和 monitors 項目是嚴格的。其中的未知鍵是錯誤，plugin 不會載入

驗證 manifest

claude plugin validate 是 manifest 的權威檢查。從您的 shell 針對 plugin 目錄執行它：

claude plugin validate ./my-plugin

該命令報告以下結果之一：

  • Validation passed：manifest 載入
  • Validation passed with warnings：manifest 載入，但驗證器發現需要修正的內容，例如 Claude Code 移除的未知頂層欄位、不是 kebab-case 的 name，或缺少 version、description 或 author。傳遞 --strict 以在 CI 中將警告轉換為失敗
  • Validation failed：manifest 有類型不匹配、缺少或逃逸 plugin 根目錄的路徑，或 userConfig 選項、channels 項目、lspServers 設定或 monitors 項目內的未知鍵。Claude Code 在載入 plugin 時報告相同的問題

欄位

表格列出 plugin.json 中的頂層鍵。name 是唯一必需的鍵。其中欄位名稱是連結的地方，連結的部分有其完整規則。

對於元件鍵（例如 commands 和 hooks），元件路徑形式顯示每個接受的形式及範例，每個路徑都遵循 ./ 前綴、副檔名和包含的路徑規則。

欄位 類型 說明
$schema String JSON Schema URL 用於編輯器自動完成。Claude Code 在載入時忽略它
name String Plugin 識別碼，必需。使用 kebab-case。每個元件都在其下命名空間
displayName String 在 UI 中顯示的名稱，代替 name
version String 版本字串。設定它會將使用者保留在該版本，直到您變更它
description String plugin 提供內容的簡短說明
author Object name（必需），加上選用的 email 和 url
homepage String 文件 URL。必須解析為 URL，否則 plugin 無法載入
repository String 來源儲存庫 URL。未驗證
license String SPDX 識別碼，例如 MIT 或 Apache-2.0
keywords Array of strings 探索標籤
metadata Object 您自己資料的自由形式物件。Claude Code 不讀取它
defaultEnabled Boolean 當使用者未設定時，plugin 是否在啟用時啟動。預設為 true
dependencies Array of strings or objects 必須啟用此 plugin 才能運作的 plugin
settings Object Claude Code 在 plugin 啟用時應用的設定。只有 agent 和 subagentStatusLine 生效
userConfig Object Claude Code 在 plugin 啟用時提示使用者輸入的值
channels Array of objects plugin 提供的訊息頻道，每個繫結到其 MCP 伺服器之一
skills Path, or array of paths 要掃描的目錄以尋找 skills，每個目錄都是 <name>/SKILL.md 資料夾或直接保存 SKILL.md 的資料夾。"." 命名 plugin 根目錄。新增到預設 skills/ 掃描
commands Path, array of paths, or object 平面 .md 命令檔案、它們的目錄，或命令名稱到 source 或 content 的物件對應。取代預設 commands/ 掃描
agents Path, or array of paths Agent .md 檔案。不接受目錄。取代預設 agents/ 掃描
hooks Path, object, or array of either .json hook 檔案或內聯 hook 設定。與 hooks/hooks.json 一起載入
mcpServers Path, object, or array of either .json MCP 設定檔案、.mcpb 或 .dxt 套件，或按名稱鍵入的內聯伺服器設定。與 .mcp.json 一起載入；稍後宣告的伺服器名稱取代較早的名稱
lspServers Path, object, or array of either .json LSP 設定檔案或按名稱鍵入的內聯伺服器設定。與 .lsp.json 一起載入
outputStyles Path, or array of paths 輸出樣式檔案或目錄。取代預設 output-styles/ 掃描
workflows Path, or array of paths Workflow .js 檔案或目錄。取代預設 workflows/ 掃描
experimental Object themes、monitors 和 evals 的容器，其 manifest 形式可能仍會變更
experimental.themes Path, or array of paths 主題檔案或目錄。取代預設 themes/ 掃描。頂層 themes 鍵仍會載入，並帶有 claude plugin validate 警告
experimental.monitors Path, or inline array 保存 monitors 陣列的 .json 檔案，或陣列本身。預設為 monitors/monitors.json。頂層 monitors 鍵仍會載入，並帶有 claude plugin validate 警告。Monitors 僅在互動式工作階段中執行，不在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上執行
experimental.evals Path, or array of paths 當它不是預設 evals/ 時，保存 plugin 的 eval 案例的目錄。claude plugin eval --eval-dir 覆蓋它

在「類型」欄中，路徑是相對於 plugin 根目錄的字串，例如 "./custom/commands"。

`name`

Plugin 識別碼。它必須非空，沒有空格、@、:、路徑分隔符、控制字元或雙向格式化字元；使用 kebab-case。

Claude Code 在其下命名空間每個元件，因此 plugin deploy-tools 中的 agent reviewer 顯示為 deploy-tools:reviewer。

`displayName`

在 UI 中顯示的名稱，代替 name。它可能包含空格和任何大小寫，它不用於命名空間或查詢。

對於 marketplace 安裝的 plugin，marketplace 項目上的 displayName 優先於此值。

`version`

版本字串，不根據 semver 檢查。設定它會將 plugin 固定到該版本，直到您變更它；請參閱版本和更新。具有command 來源的 plugin、來自託管在 claude.ai 上的 marketplace 的 plugin，以及就地載入的 plugin（來自作為本機目錄新增的 marketplace）不受此欄位固定。

`metadata`

您自己資料的自由形式物件，例如目錄或權利欄位。Claude Code 不讀取它。需要 Claude Code v2.1.222 或更新版本。

`defaultEnabled`

當使用者未在 enabledPlugins 中設定時，plugin 是否在啟用時啟動。預設為 true。啟用的 plugin 所依賴的 plugin 無論如何都會啟用。marketplace 項目中的相同欄位覆蓋此欄位。

一旦寫入使用者的 enabledPlugins 項目，它會在 plugin 更新中持續存在，因此在稍後版本中變更 defaultEnabled 不會變更現有使用者的設定。

`dependencies`

必須啟用此 plugin 才能運作的 plugin。每個項目是 "name"、"name@marketplace" 或 { "name": "...", "marketplace": "...", "version": "..." }。裸名稱針對此 plugin 自己的 marketplace 解析。請參閱依賴性約束。

`settings`

Claude Code 在 plugin 啟用時應用的設定。只有 agent 和 subagentStatusLine 生效；其他鍵在載入時被丟棄。plugin 根目錄的 settings.json 優先於此鍵。請參閱預設設定。

元件路徑形式

每個元件鍵接受相對於 plugin 根目錄的路徑。hooks、mcpServers、lspServers 和 experimental.monitors 也接受內聯設定，commands 也接受物件對應，mcpServers 也接受 MCP 套件路徑和 URL。以下範例各顯示一次每個接受的形式。有關每個元件在執行時的作用，請參閱 Plugin 元件。

僅路徑欄位

agents、skills、outputStyles、workflows 和 experimental.themes 採用一個路徑或路徑陣列。agents 項目必須是 .md 檔案，skills 項目必須是目錄。其他三個接受目錄或檔案。

{
  "agents": ["./custom-agents/reviewer.md", "./custom-agents/tester.md"],
  "skills": ["./extra-skills/", "."],
  "outputStyles": "./styles/"
}

`commands`

commands 採用路徑、路徑陣列或物件對應。路徑命名平面 .md 命令檔案或目錄。在物件對應中，每個鍵在 plugin 前綴後成為命令名稱。例如，plugin deploy-tools 中的 "about" 執行為 /deploy-tools:about。

每個值恰好設定 source 或 content 之一，設定兩者或都不設定的項目無法驗證。此表中的其他欄位是選用的：

欄位 類型 說明
source string 命令的 Markdown 檔案路徑，相對於 plugin 根目錄
content string 命令主體的內聯 Markdown，而不是 source
description string 為命令顯示的說明
argumentHint string 命令名稱後顯示的引數提示，例如 [file]
model string 命令的預設模型
allowedTools array of strings 命令可以使用而無需提示的工具

此對應宣告一個來自檔案的命令和一個來自內聯內容的命令：

{
  "commands": {
    "status": { "source": "./commands/status.md", "argumentHint": "[env]" },
    "about": { "content": "Explain what this plugin provides." }
  }
}

`hooks`

hooks 採用 .json 檔案路徑、與 settings.json 中的 hooks 相同形式的內聯 hooks 物件，或混合兩者的陣列。有關 hook 事件和處理程式欄位，請參閱 hooks 參考。

Claude Code 在該檔案存在時將您宣告的內容與 hooks/hooks.json 合併。

{
  "hooks": [
    "./config/extra-hooks.json",
    {
      "PostToolUse": [
        {
          "matcher": "Write|Edit",
          "hooks": [
            { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/format.sh" }
          ]
        }
      ]
    }
  ]
}

`mcpServers`

mcpServers 採用 .json 檔案路徑、MCP 套件路徑或 URL、內聯對應，或混合它們的陣列。有關伺服器設定欄位，請參閱 plugin 提供的 MCP 伺服器。

Claude Code 首先載入 plugin 根目錄的 .mcp.json，然後按順序載入每個宣告的形式。稍後宣告的伺服器名稱取代較早的名稱。

mcpServers 值採用以下形式之一：

形式 範例值 Claude Code 的作用
.json 檔案路徑 "./mcp/servers.json" 將檔案讀取為 mcpServers 對應
MCP 套件路徑 "./bundle.mcpb" 將 .mcpb 或 .dxt 套件提取到 plugin 根目錄下的 .mcpb-cache/ 並讀取其伺服器設定
MCP 套件 URL "https://example.com/server.mcpb" 將套件下載到 .mcpb-cache/，然後讀取它
內聯對應 { "deploy-api": { "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"] } } 使用對應作為按名稱鍵入的伺服器設定

套件路徑或 URL 必須以 .mcpb 或 .dxt 結尾。任何其他副檔名無法驗證。

`lspServers`

lspServers 採用 .json 檔案路徑、伺服器名稱到設定的內聯對應，或兩者的陣列。

Claude Code 首先載入 plugin 根目錄的 .lsp.json，然後按順序載入每個宣告的設定。稍後宣告的伺服器名稱取代較早的名稱。

每個伺服器設定是具有這些欄位的嚴格物件。未知鍵無法驗證。

欄位 必需 說明
command Yes Language server 二進位檔。除非值以 / 開頭，否則沒有空格；將引數放在 args 中
extensionToLanguage Yes 檔案副檔名到 LSP 語言 ID 的對應，至少一個項目。鍵以點開頭，例如 ".go"
args No 傳遞給伺服器的引數
transport No 通訊傳輸：stdio（預設）或 socket。Claude Code 接受 socket 但在 stdio 上執行每個伺服器，因此 stdout 協定規則適用於所有伺服器
env No 伺服器程序的環境變數
initializationOptions No 在初始化請求中傳送的選項
settings No 由 workspace/didChangeConfiguration 傳送的設定
workspaceFolder No 伺服器的工作區資料夾路徑
startupTimeout No 等待啟動的毫秒數，正整數
shutdownTimeout No 等待正常關閉的毫秒數，正整數。當逾時經過時，Claude Code 終止伺服器程序。未設定時，不適用逾時
restartOnCrash No 伺服器崩潰後是否重新啟動。預設為 true。設定為 false 以保持崩潰的伺服器停止而不是重新啟動
maxRestarts No 放棄前的重新啟動嘗試，零或更多
diagnostics No 編輯後是否將診斷推送到上下文。預設為 true

此內聯設定為 .go 檔案執行 gopls：

{
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": { ".go": "go" }
    }
  }
}

有關 Anthropic 發佈為 plugin 的語言伺服器以及伺服器在執行時的行為，請參閱程式碼智慧。

`monitors`

experimental.monitors 採用 .json 檔案路徑或內聯陣列。當您省略鍵時，Claude Code 會載入 monitors/monitors.json（如果存在）。

每個項目是具有這些欄位的嚴格物件。

欄位 必需 說明
name Yes 在 plugin 內唯一的識別碼
command Yes Claude Code 在工作階段工作目錄中作為持續背景程序執行的 Shell 命令
description Yes 在工作面板和通知摘要中顯示的簡短摘要
when No 使用 "always"（預設），monitor 在工作階段啟動和 plugin 重新載入時啟動。使用 "on-skill-invoke:<skill>"，它在該 skill 首次執行時啟動

此內聯陣列宣告一個 monitor，在 deploy skill 首次執行時啟動：

{
  "experimental": {
    "monitors": [
      {
        "name": "deploy-status",
        "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
        "description": "Deployment status changes",
        "when": "on-skill-invoke:deploy"
      }
    ]
  }
}

Monitor command 無法參考 ${user_config.*}。請參閱通過 shell 執行的欄位。

路徑規則

manifest 中的每個元件路徑相對於 plugin 根目錄，必須以 ./ 開頭。路徑（例如 commands/foo.md）無法驗證。skills 和 mcpServers 各接受該規則外的一種形式：

  • skills：也接受 "."。"." 和 "./" 都表示 plugin 根目錄。在 v2.1.221 之前，"." 無法通過 manifest 驗證，因此當 plugin 必須在較早版本上載入時使用 "./"
  • mcpServers：也接受 https:// 套件 URL

包含和存在

每個元件路徑必須解析到 plugin 根目錄內並且必須存在。claude plugin validate 不檢查 outputStyles、lspServers、monitors 或 themes 路徑，因此這些欄位中的錯誤路徑僅在 plugin 載入時失敗：

  • 包含：解析到 plugin 根目錄外的路徑不會載入，/plugin Errors 標籤顯示 <component> path escapes plugin directory: <path>。包含 .. 的路徑是常見情況，claude plugin validate 將其報告為 Path contains ".." which could be a path traversal attempt
  • 存在：不存在的路徑不會載入，/plugin Errors 標籤顯示 <component> path not found: <path>。claude plugin validate 將其報告為 Path not found

每個鍵如何與其預設位置結合

每個元件鍵要麼取代其預設位置，要麼新增到它，要麼與它合併：

  • 取代預設：commands、agents、outputStyles、workflows、experimental.themes、experimental.monitors。當您設定 commands 時，預設 commands/ 目錄不會被掃描。要保留預設並新增更多，明確列出它："commands": ["./commands/", "./extras/"]
  • 新增到預設：skills。skills/ 目錄仍會被掃描，列出的目錄與它一起載入
  • 合併：hooks、mcpServers、lspServers。預設檔案首先載入，manifest 宣告的內容合併到它中，如元件路徑形式下所述

如果 plugin 有預設資料夾（例如 commands/）並且也設定了取代它的 manifest 鍵，Claude Code 會載入 manifest 路徑而不是資料夾。claude plugin list 和 /plugin 介面然後顯示警告 Default <folder>/ folder is ignored because the manifest sets "<key>"。

要避免警告，將鍵設定為該資料夾內的路徑："commands": ["./commands/deploy.md"] 命名預設資料夾中的檔案，不會產生警告。

使用者設定

userConfig 宣告當外掛程式啟用時 Claude Code 提示使用者輸入的值，讓使用者不需要自行編輯 settings.json。

鍵是由字母、數字和底線組成的識別碼，且不能以數字開頭。

每個值都是一個嚴格的物件，包含以下欄位。未知的鍵會導致驗證失敗。

欄位 必需 說明
type 是 string、number、boolean、directory 或 file 之一
title 是 在設定對話框中顯示的標籤
description 是 在欄位下方顯示的說明文字
required 否 如果為 true，設定對話框不接受空值
default 否 當使用者未提供任何值時使用的值：字串、數字、布林值或字串陣列
options 否 對於 string，欄位接受的值，在 /config 中顯示為選擇器。請參閱將欄位限制為固定選項。需要 Claude Code v2.1.271 或更新版本
multiple 否 對於 string，允許字串陣列
sensitive 否 如果為 true，會遮蔽輸入並將值儲存在安全儲存空間中，而不是 settings.json
min / max 否 number 的邊界

每個已啟用外掛程式的每個選項也會在 /config 面板中顯示為一列，除了 sensitive 選項和 multiple 清單。/config 列需要 Claude Code v2.1.269 或更新版本。

此 userConfig 宣告一個端點和一個遮蔽的權杖：

{
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "API endpoint",
      "description": "Your team's API endpoint"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "API authentication token",
      "sensitive": true
    }
  }
}

將欄位限制為固定選項

在 userConfig 欄位上設定 options，讓使用者從固定清單中選擇其值。

若要將 tone 欄位限制為三個選項，請在 options 中列出它們，並將 default 設定為其中之一：

{
  "userConfig": {
    "tone": {
      "type": "string",
      "title": "Tone",
      "description": "Voice for generated replies",
      "options": ["neutral", "warm", "formal"],
      "default": "neutral"
    }
  }
}

如果您在任何欄位上宣告 options，使用 Claude Code v2.1.271 之前版本的使用者將無法載入外掛程式。

options 適用於不是 multiple 或 sensitive 的 string 欄位。將 default 設定為列出的值之一，或設定 required: true 讓使用者必須選擇一個。每個選項是 1 到 64 個字元的純標籤，您在殼層中執行的 claude plugin validate 會報告它拒絕的任何其他內容。選項違反這些規則的外掛程式將無法載入。

值的儲存位置

非敏感值會儲存在使用者 settings.json 中的 pluginConfigs 下。敏感值則改為儲存在平台的安全認證存放區中。設定頁面列出了讀取 pluginConfigs 的設定檔。

參考已儲存的值

在外掛程式需要的地方參考已儲存的值，有以下兩種形式：

  • ${user_config.KEY}：在 MCP 伺服器設定、LSP 伺服器設定、exec 形式 hook args 和技能與代理程式內容中替換。在技能和代理程式內容中，只有非敏感值會被替換，敏感值會變成預留位置
  • CLAUDE_PLUGIN_OPTION_<KEY>：匯出到每個選項的 hook 程序，其中 <KEY> 為大寫。shell 形式的 hook 會讀取 $CLAUDE_PLUGIN_OPTION_API_TOKEN 以取得 api_token

通過殼層執行的欄位

Shell 形式的 hook 命令、監視命令和 MCP headersHelper 拒絕 ${user_config.*}。在這些欄位之一中參考它的元件會因錯誤而失敗，而不是執行，因為欄位的值會傳遞到會重新解析替換值的殼層。

下表顯示該值如何可以到達這些欄位。

欄位 值如何到達它
Shell 形式的 hook 命令 使用exec 形式搭配 args，或從 hook 的環境中讀取 CLAUDE_PLUGIN_OPTION_<KEY>
監視命令 不通過 Claude Code。監視程序不會接收 CLAUDE_PLUGIN_OPTION_<KEY>，所以監視指令碼必須自行取得該值
MCP headersHelper 不通過 Claude Code。協助程式的環境包含 CLAUDE_PLUGIN_ROOT、CLAUDE_CODE_MCP_SERVER_NAME 和 CLAUDE_CODE_MCP_SERVER_URL，但沒有選項值，所以協助程式指令碼必須自行取得該值

頻道

channels 宣告 plugin 提供的訊息頻道，例如到聊天應用程式的橋接。當您宣告一個時，Claude Code 可以在 plugin 啟用時提示頻道的設定。有關伺服器如何注入訊息，請參閱頻道參考。

每個項目是繫結到 plugin 的 MCP 伺服器之一的嚴格物件，具有這些欄位：

欄位 必需 說明
server Yes 此 plugin 的 mcpServers 中頻道繫結到的 MCP 伺服器的鍵
displayName No 在設定對話方塊標題中顯示的名稱。預設為伺服器名稱
userConfig No 要提示的選項，形式與頂層 userConfig 相同。儲存的值替換到伺服器 env 中的 ${user_config.KEY} 參考

此 manifest 將頻道繫結到 plugin 的 telegram MCP 伺服器，並提示替換到伺服器 env 中的機器人令牌：

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": { "BOT_TOKEN": "${user_config.bot_token}" }
    }
  },
  "channels": [
    {
      "server": "telegram",
      "displayName": "Telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        }
      }
    }
  ]
}

環境變數

Claude Code 為 plugin 元件提供三個路徑變數。在每個變數解析的位置下列出的欄位中將它們參考為 ${NAME}，並在接收它們的程序中將它們讀取為環境變數。

變數 解析為 用途
${CLAUDE_PLUGIN_ROOT} plugin 已安裝版本的絕對路徑 與 plugin 捆綁的指令碼、二進位檔和設定檔案
${CLAUDE_PLUGIN_DATA} ~/.claude/plugins/data/<id>/，在首次參考時建立並在 plugin 更新中保留。<id> 是 plugin 識別碼，其中除字母、數字、_ 或 - 外的每個字元都被 - 取代 已安裝的依賴項（例如 node_modules）、產生的程式碼和快取
${CLAUDE_PROJECT_DIR} 專案根目錄 專案本機指令碼和設定檔案

${CLAUDE_PLUGIN_ROOT} 在 plugin 更新時變更，因此不要在那裡寫入狀態。有關根目錄移動的位置和舊目錄何時被清理，請參閱載入頁面。

當您從最後安裝 plugin 的地方卸載它時，${CLAUDE_PLUGIN_DATA} 目錄會被刪除，除非您傳遞 --keep-data。

每個變數解析的位置

在每個 plugin 元件中，${...} 參考在特定欄位中內聯解析，某些元件也在其程序環境中接收變數：

Plugin 元件 ${...} 解析的欄位 匯出到程序
Hook 命令 在 command 和 args 中的任何位置 CLAUDE_PLUGIN_ROOT、CLAUDE_PLUGIN_DATA、CLAUDE_PROJECT_DIR 和 CLAUDE_PLUGIN_OPTION_<KEY>
Monitor 命令 在 command 中的任何位置 未匯出
MCP stdio 伺服器 command、args、env CLAUDE_PLUGIN_ROOT、CLAUDE_PLUGIN_DATA
MCP http、sse、ws 伺服器 url、headers、headersHelper 不適用
LSP 伺服器 command、args、env、workspaceFolder CLAUDE_PLUGIN_ROOT、CLAUDE_PLUGIN_DATA、CLAUDE_PROJECT_DIR
Skill、command 和 agent 內容 Markdown 主體中的任何位置 不適用

變數不存在於 Claude 通過 Bash 工具在主工作階段或子代理中執行的命令環境中。在 skill、command 和 agent 內容中，在 Markdown 主體中寫入 ${...} 參考，Claude Code 在載入內容時內聯替換路徑。

引用和路徑分隔符

保持每個替換的路徑為單一引數：

  • Hook 命令：使用exec 形式與 args 以便每個路徑是一個沒有引用的引數
  • Shell 形式 hooks 和 monitor 命令：用雙引號包裝變數，以便帶有空格的路徑保持為一個字

此 shell 形式 hook 執行與 plugin 捆綁的指令碼：

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/process.sh"
          }
        ]
      }
    ]
  }
}

在 Windows 上，替換的路徑使用正斜杠，因此 shell 不會將反斜杠讀取為逃逸。

標準配置

每個元件類型在 plugin 根目錄下有預設位置，當 manifest 不指向其他位置時使用。

元件 預設位置 內容
Manifest .claude-plugin/plugin.json Plugin 中繼資料和設定。選用
Skills skills/ 每個 skill 一個 <name>/SKILL.md。具有其根目錄的 SKILL.md、沒有 skills/ 和沒有 skills 鍵的 plugin 作為單一 skill 載入
Commands commands/ 平面 Markdown 命令檔案。對於新 plugin 偏好 skills/
Agents agents/ Agent Markdown 檔案。子資料夾是代理名稱的一部分
Hooks hooks/hooks.json Hook 設定
MCP 伺服器 .mcp.json MCP 伺服器定義
LSP 伺服器 .lsp.json LSP 伺服器設定
輸出樣式 output-styles/ 輸出樣式 Markdown 檔案
Workflows workflows/ Workflow .js 檔案
主題 themes/ 主題 JSON 檔案
Monitors monitors/monitors.json Monitors 陣列
可執行檔 bin/ 此處的檔案在 plugin 啟用時位於 Bash 工具的 PATH 上，因此 Claude 將它們作為裸命令執行。claude.ai 和 Cowork 不安裝具有此目錄的 plugin，包括您通過 claude.ai 組織設定分發的 plugin
設定 settings.json 在 plugin 啟用時應用的 agent 和 subagentStatusLine 預設值

使用每個預設位置的 plugin，加上其 hooks 呼叫的 scripts/ 資料夾，配置如下：

deploy-tools/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── deploy/
│       └── SKILL.md
├── commands/
│   └── status.md
├── agents/
│   └── reviewer.md
├── hooks/
│   └── hooks.json
├── monitors/
│   └── monitors.json
├── output-styles/
│   └── terse.md
├── themes/
│   └── dracula.json
├── workflows/
│   └── release-audit.js
├── bin/
│   └── deploy-tool
├── scripts/
│   └── format.sh
├── settings.json
├── .mcp.json
└── .lsp.json

要點擊此配置並讀取每個檔案的作用，請開啟 plugin 探索器。

plugin 根目錄的 CLAUDE.md 不作為上下文載入，claude plugin validate 在找到一個時發出警告。要包含載入到 Claude 上下文中的指示，請將它們放在 skill 中。

Marketplace 項目和 manifest

marketplace 項目接受此頁面上的每個欄位以及其自己的欄位，包括 strict。

strict 欄位決定項目是否可以將元件新增到具有自己 plugin.json 的 plugin。它預設為 true。

項目欄位如何與 `plugin.json` 結合

項目要麼作為 manifest，要麼將元件新增到它，要麼與它衝突：

  • 沒有 plugin.json：項目是 manifest，無論 strict 如何。項目 hooks 僅以內聯物件形式載入。對於檔案路徑或陣列，/plugin Errors 標籤顯示 not yet supported in a marketplace entry 錯誤
  • plugin.json 存在，strict 未設定或 true：Claude Code 載入 manifest 並將項目的 commands、agents、skills、outputStyles 和 themes 附加到它。對於 hooks，項目的事件匹配器取代 manifest 對該相同事件的匹配器，只有 manifest 宣告的事件保留其
  • plugin.json 存在，strict: false：宣告 commands、agents、skills、hooks、outputStyles 或 themes 的項目是衝突，plugin 無法載入，出現 Plugin <name> has conflicting manifests

當其 source 是 marketplace 根目錄的 marketplace 項目列出特定 skills 子目錄時，只有這些子目錄載入，plugin 的預設 skills/ 目錄不會被掃描。manifest 中的 skills 鍵改為新增到預設。

中繼資料優先順序

某些中繼資料欄位有固定的優先順序，無論 strict 如何：

  • defaultEnabled 和顯示欄位：項目的 defaultEnabled 和其顯示欄位（例如 displayName）覆蓋 manifest 的
  • version：manifest 的 version 覆蓋項目的
  • name：當項目在與 manifest 不同的 name 下列出 plugin 時，enabledPlugins 使用項目名稱，元件在 manifest 名稱下命名空間

有關完整優先順序表，請參閱嚴格模式。

後續步驟