Plugins 參考

Claude Code plugin 系統的完整技術參考，包括 schemas、CLI 命令和元件規格。

plugin 是一個自包含的目錄，包含擴展 Claude Code 功能的元件。Plugin 元件包括 skills、agents、hooks、MCP servers、LSP servers 和 monitors。

Plugin 元件參考

Skills

Plugins 會將 skills 新增至 Claude Code，建立 /name 快捷方式供您或 Claude 叫用。

位置：plugin 根目錄中的 skills/ 或 commands/ 目錄，或 plugin 根目錄中的單一 SKILL.md 檔案

檔案格式：Skills 是包含 SKILL.md 的目錄；commands 是簡單的 markdown 檔案

Skill 結構：

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (optional)
│   └── scripts/ (optional)
└── code-reviewer/
    └── SKILL.md

當 plugin 安裝時，Skills 和 commands 會自動被發現。

如果 plugin 沒有 skills/ 目錄且沒有 skills manifest 欄位，plugin 根目錄中的 SKILL.md 會被載入為單一 skill。設定 frontmatter name 欄位以控制 skill 的叫用名稱。沒有設定的話，Claude Code 會回退到安裝目錄名稱，對於從 marketplace 安裝的 plugins，這是一個在每次更新時都會改變的版本字串。對於提供多個 skills 的 plugins，請使用上面所示的 skills/ 目錄配置。

在 plugin skills 和 commands 中，Boolean frontmatter 欄位（例如 disable-model-invocation）接受 yes、no、on、off、1 和 0（任何字母大小寫），以及 true 和 false。在 v2.1.218 之前，Claude Code 只識別 true 和 false。

如需完整詳細資訊，請參閱 Skills。

Agents

Plugins 可以提供專門的子代理程式來執行特定任務，Claude 可以在適當時自動叫用。

位置：plugin 根目錄中的 agents/ 目錄

檔案格式：描述代理程式功能的 Markdown 檔案

Agent 結構：

---
name: agent-name
description: What this agent specializes in and when Claude should invoke it
model: sonnet
effort: medium
maxTurns: 20
disallowedTools: Write, Edit
---

Detailed system prompt for the agent describing its role, expertise, and behavior.

Plugin agents 支援 name、description、model、effort、maxTurns、tools、disallowedTools、skills、memory、background 和 isolation frontmatter 欄位。唯一有效的 isolation 值是 "worktree"。基於安全考量，plugin 提供的 agents 不支援 hooks、mcpServers 和 permissionMode。

Claude Code 會載入 plugin agent，即使其 frontmatter 沒有 name 或無法解析：

• 沒有 name：Claude Code 會根據檔案名稱為 agent 命名，所以名為 my-plugin 的 plugin 中的 agents/reviewer.md 會載入為 my-plugin:reviewer
• 無法解析的 Frontmatter：Claude Code 會根據檔案名稱為 agent 命名，使用 Agent from my-plugin plugin 作為其描述，並忽略檔案中的每個欄位

相比之下，Claude Code 會跳過其 frontmatter 沒有 name 或無法解析的專案、使用者或受管理的 agent 檔案。

若要找到 plugin 預設 agents/ 目錄中 frontmatter 無法解析的檔案，請執行 claude plugin validate。您傳遞的路徑取決於 plugin 是否有 manifest，兩個範例都使用 ./my-plugin 作為 plugin 目錄：

• 具有 manifest 的 plugin：claude plugin validate ./my-plugin
• 沒有 manifest 的 plugin：claude plugin validate ./my-plugin/agents。需要 Claude Code v2.1.233 或更新版本。

Agents 會在 @-mention 類型提前 中以其範圍名稱（例如 my-plugin:code-reviewer）出現，一旦 plugin 被啟用。

如需完整詳細資訊，請參閱 Subagents。

Hooks

Plugins 可以提供事件處理程式，自動回應 Claude Code 事件。

位置：plugin 根目錄中的 hooks/hooks.json，或 plugin.json 中的內聯

格式：具有事件匹配器和動作的 JSON 設定

Hook 設定：

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

Plugin hooks 回應與 使用者定義的 hooks 相同的生命週期事件：

Hook 類型：

• command：執行 shell 命令或指令碼
• http：將事件 JSON 作為 POST 請求傳送到 URL
• mcp_tool：在已設定的 MCP server 上呼叫工具
• prompt：使用 LLM 評估提示（使用 $ARGUMENTS 預留位置作為內容）
• agent：執行具有工具的代理程式驗證器以進行複雜驗證任務

針對 plugin 自己的 bundled MCP server 的 Hooks 必須使用其範圍名稱。工具匹配器和 if 欄位採用範圍工具名稱 mcp__plugin_<plugin-name>_<server-name>__<tool>，而 mcp_tool hook 的 server 欄位採用 plugin:<plugin-name>:<server-name>。針對裸伺服器金鑰編寫的匹配器永遠不會觸發。請參閱 Match MCP tools 和 Plugin-provided MCP servers。

MCP servers

Plugins 可以捆綁 Model Context Protocol (MCP) 伺服器，以將 Claude Code 與外部工具和服務連接。

位置：plugin 根目錄中的 .mcp.json，或 plugin.json 中的內聯

格式：標準 MCP 伺服器設定

MCP 伺服器設定：

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"]
    }
  }
}

整合行為：

• Plugin MCP 伺服器在 plugin 啟用時自動啟動
• 伺服器在 Claude 的工具組中顯示為標準 MCP 工具
• Plugin 伺服器可以獨立於使用者 MCP 伺服器進行設定
• 如果您在工作階段中執行 /reload-plugins，Claude Code 會保持其設定未變更的伺服器的即時連接

LSP servers

Plugins 可以提供 Language Server Protocol (LSP) 伺服器，以在處理您的程式碼庫時為 Claude 提供 即時程式碼智慧。

位置：plugin 根目錄中的 .lsp.json，或 plugin.json 中的內聯

格式：將語言伺服器名稱對應到其設定的 JSON 設定

.lsp.json 檔案格式：

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

在 plugin.json 中內聯：

{
  "name": "my-plugin",
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": {
        ".go": "go"
      }
    }
  }
}

必需欄位：

選用欄位：

restartOnCrash 和 shutdownTimeout 需要 Claude Code v2.1.205 或更新版本。在 v2.1.205 之前，設定結構描述接受兩個選項，但設定其中任一個會導致 Claude Code 在啟動時完全跳過該 LSP 伺服器，原因只在 claude --debug 輸出中可見。

同一副檔名的多個伺服器：當多個已啟用的 LSP 伺服器在 extensionToLanguage 中宣告相同的檔案副檔名時，無論伺服器來自一個 plugin 還是來自不同的 plugins，第一個註冊的伺服器會處理具有該副檔名的檔案，其他伺服器永遠不會啟動。/plugin 介面會顯示一個警告，命名其伺服器為作用中的 plugin。

無法初始化的伺服器：Claude Code 會跳過其設定無效的伺服器，例如缺少 command 或 extensionToLanguage 的伺服器，其他已設定的伺服器仍會啟動。執行 claude --debug 以查看伺服器被跳過的原因。

被跳過的伺服器不會宣告其檔案副檔名，因此宣告相同副檔名的另一個有效伺服器（來自相同或不同的 plugin）仍會處理這些檔案。

將日誌輸出傳送到 stderr，而不是 stdout：Claude Code 將伺服器的 stdout 讀取為協定訊息，並接受最多 64 KiB 的訊息標頭和最多 32 MiB 的訊息本文。Claude Code 會斷開超過任一限制或將非協定輸出寫入 stdout 的伺服器，並將斷開連接計為 restartOnCrash 和 maxRestarts 的當機。當您使用 --debug 執行時，Claude Code 會將命名原因的錯誤寫入偵錯日誌。

可用的 LSP plugins：

先安裝語言伺服器，然後從 marketplace 安裝 plugin。

Monitors

Plugins 可以宣告背景監視器，Claude Code 在 plugin 啟用時自動啟動。每個監視器在工作階段的生命週期內執行 shell 命令，並將每個 stdout 行傳遞給 Claude 作為通知，因此 Claude 可以對日誌項目、狀態變更或輪詢事件做出反應，而無需被要求自己啟動監視。

Plugin monitors 使用與 Monitor tool 相同的機制，並共享其可用性限制。它們僅在互動式 CLI 工作階段中執行，以與 hooks 相同的信任層級在未沙箱化的環境中執行，並在 Monitor tool 不可用的主機上被跳過。

位置：plugin 根目錄中的 monitors/monitors.json，或 plugin.json 中的內聯

格式：監視器項目的 JSON 陣列

以下 monitors/monitors.json 監視部署狀態端點和本機錯誤日誌：

[
  {
    "name": "deploy-status",
    "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
    "description": "Deployment status changes"
  },
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log",
    "when": "on-skill-invoke:debug"
  }
]

若要內聯宣告監視器，請在 plugin.json 中將 experimental.monitors 設定為相同的陣列。若要從非預設路徑載入，請將 experimental.monitors 設定為相對路徑字串，例如 "./config/monitors.json"。Monitors 是 experimental component。

必需欄位：

選用欄位：

command 值支援 路徑替換 ${CLAUDE_PLUGIN_ROOT}、${CLAUDE_PLUGIN_DATA} 和 ${CLAUDE_PROJECT_DIR}，加上環境中的任何 ${ENV_VAR}。如果指令碼需要從 plugin 自己的目錄執行，請在命令前加上 cd "${CLAUDE_PLUGIN_ROOT}" && 。

Monitor command 無法參考 ${user_config.*} 值。命令透過 shell 執行，因此 Claude Code 會以 error 拒絕監視器，而不是替換值。Monitor 程序不會接收 CLAUDE_PLUGIN_OPTION_<KEY> 環境變數，因此讓監視器指令碼從它擁有的設定檔讀取值。

如果您在工作階段中停用 plugin，Claude Code 不會停止已在執行的監視器；它們在工作階段結束時停止。

Themes

Plugins 可以提供顏色主題，這些主題在 /theme 中與內建預設值和使用者的本機主題一起出現。主題是 themes/ 中的 JSON 檔案，具有 base 預設值和稀疏的 overrides 顏色權杖對應。Themes 是 experimental component。

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555",
    "success": "#50fa7b"
  }
}

當使用者選擇 plugin 主題時，Claude Code 會在其設定中儲存 custom:<plugin-name>:<slug>。Plugin 主題是唯讀的：當使用者在 /theme 中按下 Ctrl+E 時，Claude Code 會將其複製到 ~/.claude/themes/ 中，以便他們可以編輯副本。

Plugin 安裝範圍

當您安裝 plugin 時，您可以選擇一個範圍，決定 plugin 在何處可用以及誰可以使用它：

Plugin 使用與其他 Claude Code 設定相同的範圍系統。如需安裝說明和範圍旗標，請參閱 Install plugins。如需範圍的完整說明，請參閱 Configuration scopes。

Skills-directory plugins

任何 skills 目錄下的資料夾，如果包含 .claude-plugin/plugin.json 清單，就會在下一個工作階段中以 <name>@skills-dir 的名稱載入為 plugin，無需市集且無需安裝步驟。使用 plugin init 來建立一個。與複製的市集安裝不同，plugin 是在原地被發現而不是被複製到 plugin 快取中。

skills 目錄樹支援三種不同的東西：

選擇 plugin 從何處載入

專案範圍的 plugin 被簽入到儲存庫中，並到達每個複製它的協作者。因為該內容來自儲存庫而不是來自你，它只有在與 .claude/settings.json 中的專案允許規則相同的信任閘道後才會載入，所以信任父資料夾或使用 -p 執行是不夠的，執行程式碼的元件會受到進一步限制：

• 它宣告的 MCP 伺服器會經過與專案 .mcp.json 相同的 每個伺服器批准
• LSP 伺服器只有在你信任工作區後才會啟動
• 背景監視器 不會載入

個人範圍的 plugins 沒有這些限制。

編輯、重新載入和停用 skills-directory plugin

你對 skill 的 SKILL.md 所做的更改會立即在目前工作階段中生效。對 plugin 的其他元件（例如 hooks/、.mcp.json、agents/ 和 output-styles/）的更改則不會。執行 /reload-plugins 或重新啟動 Claude Code 來取得這些更改。請參閱 Live change detection。

要停止載入 skills-directory plugin，請刪除其資料夾或按名稱停用它。沒有 uninstall 步驟，因為沒有從市集安裝任何東西。

claude plugin disable my-tool@skills-dir

從 claude.ai 同步的外掛程式

在 Cowork 和雲端工作階段中，Claude Code 會將為您的 claude.ai 帳戶啟用的外掛程式下載到工作階段自身環境中的 ~/.claude/plugins/synced/，並將每個外掛程式載入為 <name>@synced，沒有 marketplace 也沒有安裝記錄。Claude Code 不會在您於自己的終端機中啟動的工作階段中載入它們。在該 Cowork 或雲端環境內，claude plugin list 會在 Synced from claude.ai 標題下顯示下載的副本。在 v2.1.239 之前，Claude Code 將這些外掛程式載入為 <name>@inline，這是 --plugin-dir 外掛程式使用的身分。

使用 claude plugin list 列印的 <name>@synced ID 來管理同步的外掛程式：

• 關閉其中一個：在同步的工作階段中，執行 claude plugin disable <name>@synced，或要求 Claude 執行它。Claude Code 會將選擇儲存為該環境使用者層級 enabledPlugins 中的 "<name>@synced": false。若要重新開啟外掛程式，請在同一工作階段中執行 claude plugin enable <name>@synced。若要將外掛程式排除在每個同步工作階段之外，請為您的 claude.ai 帳戶關閉它。若要將它排除在一個專案在每個環境中的同步工作階段之外，請在該專案已提交的 .claude/settings.json 中的 enabledPlugins 下設定 "<name>@synced": false。
• 在 claude.ai 上管理外掛程式本身：claude plugin install、update 和 uninstall 不適用於同步的外掛程式。若要移除一個，請為您的 claude.ai 帳戶關閉該外掛程式；下一個同步工作階段將在沒有它的情況下啟動。

當來自任何其他來源的已啟用外掛程式（例如 marketplace 安裝、技能目錄外掛程式或 --plugin-dir 外掛程式）與同步外掛程式的名稱相符時，Claude Code 會載入該外掛程式並報告同步副本未被載入。若要改用 claude.ai 副本，請停用您自己的副本。在 v2.1.239 之前，Claude Code 會載入同步副本而不是同名的 marketplace 安裝。

Plugin 資訊清單架構

.claude-plugin/plugin.json 檔案定義了您的 plugin 的中繼資料和設定。

資訊清單是選用的。如果省略，Claude Code 會在預設位置自動探索元件，並從目錄名稱衍生 plugin 名稱。當您需要提供中繼資料或自訂元件路徑時，請使用資訊清單。

完整架構

{
  "name": "plugin-name",
  "displayName": "Plugin Name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "metadata": { "catalogId": "cat-123", "tier": "pro" },
  "skills": "./custom/skills/",
  "commands": ["./custom/commands/special.md"],
  "agents": ["./custom/agents/reviewer.md"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./monitors.json",
    "evals": "quality/evals"
  },
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

必要欄位

如果您包含資訊清單，name 是唯一必要的欄位。

此名稱用於元件命名空間。例如，在 UI 中，名稱為 plugin-dev 的 plugin 的代理程式 agent-creator 將顯示為 plugin-dev:agent-creator。

無法識別的欄位

Claude Code 會忽略它無法識別的頂層欄位。您可以在 plugin.json 中保留來自另一個生態系統的中繼資料，plugin 仍會載入。這使得維護一個資訊清單變得實用，該資訊清單可同時用作 VS Code 或 Cursor 擴充功能資訊清單、npm package.json 或 MCPB/DXT 套件資訊清單。

claude plugin validate 會將無法識別的欄位報告為警告，而非錯誤。如果欄位與已識別的欄位相差一或兩個字元，警告會建議可能的預期名稱。只有無法識別欄位警告的 plugin 仍會通過驗證並在執行時載入。

Claude Code 如何處理已識別欄位但值類型錯誤的情況取決於該欄位：

• 大多數欄位：plugin 無法載入。例如，keywords 值為字串而非陣列是載入錯誤，claude plugin validate 會將其報告為錯誤。
• experimental 和 metadata：Claude Code 會忽略非物件值，claude plugin validate 會報告警告。

傳遞 --strict 以將警告視為錯誤。在 CI 中使用它來在發佈前捕捉拼寫錯誤的欄位名稱或來自另一個工具資訊清單的遺留欄位，即使 plugin 在執行時會載入。

claude plugin validate ./my-plugin --strict

中繼資料欄位

預設啟用

在 plugin.json 中設定 defaultEnabled: false 以發佈已停用安裝的 plugin。使用者可使用 claude plugin enable <plugin> 或 /plugin 介面將其開啟。對於新增成本或使用者應選擇加入的 plugin（例如連接到外部服務的 plugin），請使用此選項。

defaultEnabled 是當沒有其他因素決定 plugin 狀態時的後備選項。有兩件事優先於它：

• 使用者的設定：任何設定範圍中 enabledPlugins 中的 plugin 項目。一旦寫入，它會在 plugin 更新和重新安裝中持續存在，因此在後續版本中變更 defaultEnabled 不會翻轉現有使用者。
• 相依性要求：當 plugin 由另一個啟用的 plugin 所需時，Claude Code 會在安裝或啟用時為其寫入 true。這給了它明確的設定，因此它自己的預設不再適用。請參閱啟用或停用具有相依性的 plugin。

相同欄位也可以出現在 plugin 的市集項目中，其優先於 plugin.json 中的值。請參閱選用 plugin 欄位。

元件路徑欄位

實驗性元件

experimental 金鑰下的元件 themes 和 monitors 具有資訊清單架構，該架構可能在版本之間變更，同時它們穩定。您宣告它們的位置是一個單獨的遷移：頂層仍然有效，claude plugin validate 發出警告，未來版本將需要 experimental.*。

使用者設定

userConfig 欄位宣告當 plugin 啟用時 Claude Code 提示使用者的值。使用此選項而不是要求使用者手動編輯 settings.json。

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

金鑰必須是有效的識別碼。每個選項支援這些欄位：

每個值都可用於在 MCP 和 LSP 伺服器設定以及 hook 命令中替換為 ${user_config.KEY}。非敏感值也可以在 skill 和代理程式內容中替換。所有值都會匯出到 hook 程序作為 CLAUDE_PLUGIN_OPTION_<KEY> 環境變數，其中 <KEY> 是選項金鑰的大寫版本。

在 shell 中執行的欄位會拒絕 ${user_config.*}：將設定的值替換到 shell 命令中會讓 shell 執行該值包含的任何內容，因此元件會失敗並出現錯誤。每個被拒絕的欄位都有一個替代方式來傳遞值：

在 v2.1.207 之前，這些欄位替換了 ${user_config.KEY} 值；更新依賴此功能的 plugin。

非敏感值儲存在您的使用者 settings.json 中的 pluginConfigs 金鑰下，作為 pluginConfigs[<plugin-id>].options。

在 macOS 上，Claude Code 將敏感值儲存在 macOS Keychain 中，當 Keychain 拒絕寫入時回退到 ~/.claude/.credentials.json。在沒有支援的 keychain 的平台上，它將它們儲存在 ~/.claude/.credentials.json 中。Keychain 儲存與 OAuth 令牌共享，總限制約為 2 KB，因此請保持敏感值較小。

Claude Code 只從三個設定來源讀取所有 pluginConfigs 值：

• 使用者設定：~/.claude/settings.json，啟用時提示寫入的檔案
• --settings：CLI 旗標或 SDK 內嵌設定
• 受管設定：組織控制的原則

當多個來源設定相同金鑰時，受管設定優先，然後是 --settings，然後是使用者設定。您可以從此清單中移除的唯一來源是使用者設定：傳遞 --setting-sources 而不包含 user，Claude Code 會跳過它們。受管設定和 --settings 保持您傳遞的任何內容。SDK 的 settingSources 選項設定相同的清單。

專案的 .claude/settings.json 或 .claude/settings.local.json 中的項目會被忽略。兩個檔案都位於工作區中，因此複製的儲存庫可以在那裡提供值，這些值會流入 plugin hook 命令、MCP 伺服器設定、LSP 命令和監視器命令。在 v2.1.207 之前，這些項目被讀取。限制特定於 pluginConfigs：enabledPlugins 仍然遵守專案和本機設定。

頻道

channels 欄位讓 plugin 宣告一個或多個訊息頻道，將內容注入對話中。每個頻道繫結到 plugin 提供的 MCP 伺服器。

{
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        },
        "owner_id": {
          "type": "string",
          "title": "Owner ID",
          "description": "Your Telegram user ID"
        }
      }
    }
  ]
}

server 欄位是必要的，必須符合 plugin 的 mcpServers 中的金鑰。選用的每個頻道 userConfig 使用與頂層欄位相同的架構，讓 plugin 在啟用時提示 bot 令牌或擁有者 ID。

路徑行為規則

自訂路徑是取代還是擴展 plugin 的預設目錄取決於欄位：

• 取代預設：commands、agents、workflows、outputStyles、experimental.themes、experimental.monitors。例如，當資訊清單指定 commands 時，預設 commands/ 目錄不會被掃描。若要保留預設並新增更多，請明確列出："commands": ["./commands/", "./extras/"]
• 新增至預設：skills。預設 skills/ 目錄始終被掃描，skills 中列出的目錄與其一起載入。例外：對於其 source 解析為市集根目錄的市集項目，宣告特定子目錄會取代預設 skills/ 掃描
• 自己的合併規則：hooks、MCP 伺服器 和 LSP 伺服器。請參閱每個部分以了解多個來源如何結合

當 plugin 同時具有預設資料夾和相符的資訊清單金鑰時，Claude Code 會在 claude plugin list 和 /plugin 詳細檢視中警告被忽略的資料夾。plugin 仍會使用資訊清單路徑載入。當資訊清單金鑰指向預設資料夾時，Claude Code 不會警告，例如 "commands": ["./commands/deploy.md"]，因為該路徑明確命名資料夾。

對於所有路徑欄位：

• 所有路徑必須相對於 plugin 根目錄並以 ./ 開頭，除了 skills 欄位也接受 "."
  • "." 和 "./" 都表示 plugin 根目錄本身
  • 在 v2.1.221 之前，"." 無法通過資訊清單驗證，plugin 無法載入，因此使用 "./" 以支援較早版本
• 來自自訂路徑的元件使用相同的命名和命名空間規則
• 多個路徑可以指定為陣列
• skill 路徑可以指向直接包含 SKILL.md 的目錄，例如 "skills": ["."] 用於 plugin 根目錄
  • Claude Code 從 SKILL.md 中的前置事項 name 欄位取得 skill 的呼叫名稱，因此無論安裝目錄名稱如何，名稱保持穩定
  • 如果前置事項中未設定 name，Claude Code 會回退到目錄基底名稱

具有根目錄中 SKILL.md、沒有 skills/ 子目錄且沒有 skills 資訊清單欄位的 plugin 會自動載入為單一 skill plugin。您不需要為此配置在 plugin.json 中設定 "skills": ["./"]。

路徑範例：

{
  "commands": [
    "./specialized/deploy.md",
    "./utilities/batch-process.md"
  ],
  "agents": [
    "./custom-agents/reviewer.md",
    "./custom-agents/tester.md"
  ]
}

環境變數

Claude Code 提供三個變數用於參考路徑：

所有三個都匯出為環境變數到 hook 程序以及 MCP 和 LSP 伺服器子程序。哪些欄位內嵌替換它們取決於 plugin 元件：

在 hook 命令中，使用執行形式搭配 args，以便每個路徑作為一個引數傳遞，無需引號。在 shell 形式 hook 和監視器命令中，用雙引號包裝變數，如 "${CLAUDE_PROJECT_DIR}/scripts/server.sh"。此 shell 形式 hook 執行與 plugin 捆綁的指令碼：

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

${CLAUDE_PLUGIN_ROOT} 在 plugin 更新時變更。前一個版本的目錄在更新後的寬限期內保留在磁碟上，但將其視為暫時的，不要在那裡寫入狀態。請參閱 plugin 快取以了解清理語義。

當 plugin 在工作階段中期更新時，hook 命令、監視器、MCP 伺服器和 LSP 伺服器繼續使用前一個版本的路徑。執行 /reload-plugins 以將 hook、MCP 伺服器和 LSP 伺服器切換到新路徑；監視器需要工作階段重新啟動。在沒有互動式終端的工作階段中，重新載入會將 plugin MCP 伺服器保留在舊路徑上，直到下一個工作階段。

對於具有 command 來源的 plugin，Claude Code 可以重新載入 plugin 本身。

MCP 伺服器也可以呼叫 roots/list 要求以在執行時讀取工作階段的工作目錄。請參閱 roots/list 傳回的內容以及 Claude Code 何時通知伺服器變更。

持續資料目錄

${CLAUDE_PLUGIN_DATA} 目錄解析為 ~/.claude/plugins/data/{id}/，其中 {id} 是 plugin 識別碼，其中 a-z、A-Z、0-9、_ 和 - 以外的字元被替換為 -。對於安裝為 formatter@my-marketplace 的 plugin，目錄是 ~/.claude/plugins/data/formatter-my-marketplace/。

常見用途是一次安裝語言相依性並在工作階段和 plugin 更新中重複使用它們。將其用於 Python 相依性、使用 Yarn 或 pnpm 鎖定的相依性，以及其生命週期指令碼必須執行的套件。對於市集安裝的 plugin，您可能根本不需要它：Claude Code 在快取 plugin 時會自動安裝符合條件的 Node.js 套件相依性。

因為資料目錄的壽命超過任何單一 plugin 版本，單獨檢查目錄存在無法偵測當更新變更 plugin 的相依性資訊清單時。建議的模式是比較捆綁的資訊清單與資料目錄中的副本，並在它們不同時重新安裝。

此 SessionStart hook 在首次執行時安裝 node_modules，並在 plugin 更新包含變更的 package.json 時再次安裝：

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
          }
        ]
      }
    ]
  }
}

diff 在儲存的副本遺失或與捆綁的副本不同時以非零值退出，涵蓋首次執行和相依性變更更新。如果 npm install 失敗，尾部 rm 會移除複製的資訊清單，以便下一個工作階段重試。

捆綁在 ${CLAUDE_PLUGIN_ROOT} 中的指令碼可以針對持續的 node_modules 執行：

{
  "mcpServers": {
    "routines": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": {
        "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
      }
    }
  }
}

當您從最後一個安裝 plugin 的範圍卸載 plugin 時，資料目錄會自動刪除。/plugin 介面顯示目錄大小並在刪除前提示。CLI 預設刪除；傳遞 --keep-data 以保留它。

Plugin 快取和檔案解析

Plugin 可以透過以下兩種方式指定：

• 透過 claude --plugin-dir 或 claude --plugin-url，在工作階段期間使用。
• 透過市集安裝，供未來的工作階段使用。

基於安全性和驗證目的，Claude Code 會將_市集_ plugin 複製到使用者的本機 plugin 快取（~/.claude/plugins/cache）中，而不是就地使用，除了連結模式中的 command 來源，Claude Code 會透過快取項目中的連結就地使用。

對於複製的 plugin，每個已安裝的版本都是快取中的單獨目錄，按市集和 plugin 分組，並以已解析的版本命名，具有自己的 plugin 檔案副本和 Node.js 套件相依性。從發行標籤解析的相依性會取得帶有 commit-SHA 後綴的目錄名稱。

當您更新或解除安裝 plugin 時，Claude Code 會將先前的版本目錄標記為孤立，並在大約 14 天後的背景掃描中將其移除。寬限期讓已載入舊版本的並行 Claude Code 工作階段繼續執行而不會出現錯誤。Claude Code 只在至少安裝了一個 plugin 時執行掃描；在您解除安裝最後一個 plugin 後，孤立目錄會保留在磁碟上，直到您再次安裝 plugin。

Claude Code 只在 plugin 或市集資料夾不再包含任何目錄或符號連結時，才會將它從快取中移除。如果您將開發簽出符號連結到快取中作為 plugin 的版本項目，Claude Code 永遠不會將連結標記為孤立，也永遠不會移除它或包含它的資料夾。Claude Code 也永遠不會在連結的簽出中寫入其版本追蹤檔案。

Claude 的 Glob 和 Grep 工具在搜尋期間會跳過孤立的版本目錄，因此檔案結果不包括過時的 plugin 程式碼。

Node.js 套件相依性

當 Claude Code 將 plugin 複製到快取時，它也會在那裡安裝 plugin 的 Node.js 套件相依性，以便 plugin 的 hooks 和 MCP 伺服器可以載入它們。本節涵蓋 plugin 在其自己的 package.json 中宣告的 npm 和 Bun 套件。對於依賴其他 plugin 的 plugin，請參閱 plugin 相依性版本。

Claude Code 在每次建立複製版本目錄時都會在其中執行安裝：當您安裝 plugin 時、當 Claude Code 將 plugin 更新為新版本時，以及在工作階段開始時（當已啟用的 plugin 尚未快取時），例如在新機器上。只有當 plugin 的根目錄同時包含 package.json 和支援的鎖定檔案時，安裝才會執行：

如果 plugin 包含多個這些鎖定檔案，Claude Code 會使用第一個符合項，按順序檢查：bun.lock、bun.lockb、npm-shrinkwrap.json、package-lock.json。Claude Code 會跳過 yarn.lock 和 pnpm-lock.yaml，因為 Yarn 和 pnpm 支援可以繞過 --ignore-scripts 的解析時間設定 hooks。

提供 npm 鎖定檔案以獲得最廣泛的覆蓋。Claude Code 從使用者的 PATH 執行符合的鎖定檔案的套件管理員，如果遺失，不會回退到其他鎖定檔案。對於透過 npm 來源分發的 plugin，請使用 npm-shrinkwrap.json；npm 會從已發佈的套件中排除 package-lock.json。

Claude Code 限制此相依性安裝，使得 plugin 或其套件中的任何程式碼在安裝期間都不會執行，並限制其執行時間：

• 凍結解析： Bun 和 npm 安裝鎖定檔案精確指定的內容，當 package.json 和鎖定檔案不一致時，會失敗而不是重新解析版本。
• 無生命週期指令碼： --ignore-scripts 防止 preinstall、install 和 postinstall 指令碼執行，因此在這些指令碼中建置原生模組的相依性會下載但在此安裝期間不會編譯。
• 60 秒逾時： Claude Code 會停止執行時間超過此時間的安裝，並將其視為失敗。

提取 npm 來源 plugin 本身會在此相依性安裝執行之前，以啟用的生命週期指令碼執行 npm install。

失敗或跳過的安裝永遠不會阻止 plugin。當安裝失敗或 Claude Code 跳過 yarn 或 pnpm 鎖定檔案時，它會在偵錯輸出中將原因記錄為警告。具有 package.json 且沒有鎖定檔案的 plugin 會被跳過，不會有日誌項目。逾時的安裝可能會在快取副本中留下部分 node_modules 樹。

您無法關閉自動安裝；沒有設定或環境變數可以停用它。在受限網路中，請參閱網路存取需求以了解要允許的主機。

對於自動安裝無法提供的相依性，例如需要其生命週期指令碼來建置的套件、Python 相依性或使用 Yarn 或 pnpm 鎖定的 plugin，請從 hook 將其安裝到持久資料目錄。

路徑遍歷限制

Claude Code 不允許 plugin 參考其自己目錄外的檔案。它會拒絕解析到 plugin 根目錄外的元件路徑，無論路徑是在 plugin.json 中宣告還是在市集項目中宣告。這涵蓋指向 plugin 外部的路徑（如寫入的），例如 ../shared-utils，以及導向 plugin 外部的符號連結，除了市集內的連結。

在 macOS 和 Linux 上，Claude Code 也會拒絕包含反斜線的元件路徑，即使路徑保留在 plugin 內。因此，使用反斜線路徑宣告的元件只在 Windows 上載入。使用正斜線編寫元件路徑，例如 ./commands/deploy.md。

當 Claude Code 拒絕路徑時，它會報告 path escapes plugin directory 錯誤，並在沒有該元件的情況下載入 plugin。

Claude Code 在安裝 plugin 時也不會將 plugin 目錄外的檔案複製到快取中，因此當複製的 plugin 內的指令碼讀取 plugin 根目錄上方的路徑時，它也找不到這些檔案。

使用符號連結在市集內共享檔案

如果您的 plugin 需要與同一市集的其他部分共享檔案，您可以在 plugin 目錄內建立符號連結。當 plugin 複製到快取時符號連結的處理方式取決於其目標的解析位置：

• 在 plugin 自己的目錄內： 符號連結在快取中保留為相對符號連結，因此在執行時它會繼續解析到複製的目標。
• 在同一市集內的其他位置： 符號連結被取消參考。目標的內容被複製到快取中以取代它。這讓中繼 plugin 的 skills/ 目錄可以連結到市集中其他 plugin 定義的技能。
• 在市集外： 符號連結因安全性而被跳過。這防止 plugin 將任意主機檔案（例如系統路徑）拉入快取。

對於使用 --plugin-dir 安裝的 plugin、來自本機路徑的 plugin，或來自複製模式中的 command 來源的 plugin，只有解析到 plugin 自己目錄內的符號連結會被保留。所有其他連結都會被跳過。

以下命令會建立從市集 plugin 內部到由同級 plugin 定義的共享技能的連結。在 Windows 上，從提升的命令提示字元使用 mklink /D 或啟用開發人員模式：

ln -s ../../shared-plugin/skills/foo ./skills/foo

Plugin 目錄結構

標準 plugin 配置

一個完整的 plugin 遵循此結構：

enterprise-plugin/
├── .claude-plugin/           # 中繼資料目錄（選用）
│   └── plugin.json             # plugin 資訊清單
├── skills/                   # Skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── commands/                 # Skills 作為平面 .md 檔案
│   ├── status.md
│   └── logs.md
├── agents/                   # Subagent 定義
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── workflows/                # Workflow 指令碼
│   └── release-audit.js
├── output-styles/            # 輸出樣式定義
│   └── terse.md
├── themes/                   # 色彩主題定義
│   └── dracula.json
├── monitors/                 # 背景監視器設定
│   └── monitors.json
├── hooks/                    # Hook 設定
│   ├── hooks.json           # 主要 hook 設定
│   └── security-hooks.json  # 其他 hooks
├── bin/                      # Plugin 可執行檔新增至 PATH
│   └── my-tool               # 在 Bash tool 中可作為裸命令叫用
├── settings.json            # Plugin 的預設設定
├── .mcp.json                # MCP 伺服器定義
├── .lsp.json                # LSP 伺服器設定
├── scripts/                 # Hook 和公用程式指令碼
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # 授權檔案
└── CHANGELOG.md             # 版本歷史

Plugin 根目錄的 CLAUDE.md 檔案不會作為專案內容載入。Plugins 透過 skills、agents 和 hooks 而非 CLAUDE.md 來貢獻內容。若要提供載入至 Claude 內容的指示，請將其放在 skill 中。

檔案位置參考

CLI 命令參考

Claude Code 提供 CLI 命令用於非互動式外掛程式管理，適用於指令碼和自動化。

plugin init

在 ~/.claude/skills/<name>/ 處建立新外掛程式的框架。在下一個 Claude Code 工作階段中，它會自動載入為 <name>@skills-dir，並在 /plugin 和 claude plugin list 中出現，無需安裝步驟。

請參閱技能目錄外掛程式以了解範圍和信任要求。

claude plugin init <name> [options]

該命令接受這些引數：

• <name>：外掛程式名稱。成為技能命名空間和 ~/.claude/skills/ 下的目錄名稱，因此不能包含空格或路徑分隔符。

該命令接受這些選項：

claude plugin new 是此命令的別名。

每個 --with 值都會為該元件新增一個入門檔案，準備好編輯：

建立框架的外掛程式使用 @skills-dir 來源，而不是市集。管理員可以使用 strictKnownMarketplaces 或在受管設定中新增 {"source": "skills-dir"} 至 blockedMarketplaces 來封鎖此來源。當被封鎖時，plugin init 會在寫入前失敗。

這些範例顯示常見的叫用方式：

# 建立最小外掛程式的框架
claude plugin init my-helper

# 使用技能和掛鉤資料夾建立框架
claude plugin init my-helper --with skills hooks

# 覆寫現有框架
claude plugin init my-helper --force

plugin install

從可用市集安裝外掛程式。

claude plugin install <plugin> [options]

該命令接受這些引數：

• <plugin>：外掛程式名稱或 plugin-name@marketplace-name 以指定特定市集

該命令接受這些選項：

範圍決定已安裝外掛程式新增至哪個設定檔。例如，--scope project 會寫入 .claude/settings.json 中的 enabledPlugins，使外掛程式可供複製專案存放庫的所有人使用。

使用 --json 時，stdout 的最後一行是一個 JSON 物件。只解析該行，因為 Claude Code 會在其前面列印市集宣告的任何命令。三個欄位始終存在：

• command：執行的子命令，例如 install
• outcome：ok 或 failed
• message：結果的人類可讀說明

其他欄位，例如 pluginId、scope 和 failureCode，僅在適用時出現。plugin uninstall、plugin update、plugin enable 和 plugin disable 上的 --json 選項會列印具有該子命令自己欄位的相同物件。使用錯誤（例如無效的 --scope）不會列印結果行，並以 stderr 上的原因退出 1。

這些範例顯示常見的叫用方式：

# 安裝至使用者範圍（預設）
claude plugin install formatter@my-marketplace

# 安裝至專案範圍（與團隊共享）
claude plugin install formatter@my-marketplace --scope project

# 安裝至本機範圍（不與團隊共享）
claude plugin install formatter@my-marketplace --scope local

plugin uninstall

移除已安裝的外掛程式。

claude plugin uninstall <plugin> [options]

該命令接受這些引數：

• <plugin>：外掛程式名稱或 plugin-name@marketplace-name

該命令接受這些選項：

claude plugin remove 和 claude plugin rm 是此命令的別名。

根據預設，從最後剩餘的範圍解除安裝也會刪除外掛程式的 ${CLAUDE_PLUGIN_DATA} 目錄。使用 --keep-data 保留它，例如在測試新版本後重新安裝時。

plugin prune

移除不再由任何已安裝外掛程式需要的自動安裝外掛程式相依性。Claude Code 為滿足另一個外掛程式的 dependencies 欄位而拉入的相依性會被移除；您直接安裝的外掛程式永遠不會被觸及。

claude plugin prune [options]

該命令接受這些選項：

claude plugin autoremove 是此命令的別名。

該命令列出孤立的相依性，並在移除前要求確認。若要在一個步驟中移除外掛程式並清理其相依性，請執行 claude plugin uninstall <plugin> --prune。

plugin enable

啟用已停用的外掛程式。當目標從市集安裝並宣告相依性時，Claude Code 會在相同範圍內以遞移方式啟用它們。該命令在啟用或停用具有相依性的外掛程式列出的條件下失敗。

claude plugin enable <plugin> [options]

該命令接受這些引數：

• <plugin>：外掛程式名稱或 plugin-name@marketplace-name

該命令接受這些選項：

plugin disable

停用外掛程式而不解除安裝它。當目標從市集安裝時，如果另一個已啟用的外掛程式依賴它，該命令會失敗。錯誤訊息包含一個鏈式命令，可先停用每個依賴它的外掛程式。

claude plugin disable [plugin] [options]

該命令接受這些引數：

• [plugin]：外掛程式名稱或 plugin-name@marketplace-name。使用 --all 時為選用。

該命令接受這些選項：

plugin update

將外掛程式更新至最新版本。

claude plugin update <plugin> [options]

該命令接受這些引數：

• <plugin>：外掛程式名稱或 plugin-name@marketplace-name

該命令接受這些選項：

plugin list

列出已安裝的外掛程式及其版本、來源市集和啟用狀態。

claude plugin list [options]

該命令接受這些選項：

在互動式工作階段中，/plugin list 會列印類似的列表內容，但它只涵蓋市集安裝的外掛程式：

• 從技能目錄載入的外掛程式會在 /plugin 介面和 claude plugin list 中出現，但不會在內嵌 /plugin list 輸出中出現。
• 在 Claude Code v2.1.239 或更新版本上，從 claude.ai 同步的外掛程式會在您在同步工作階段下載它們的環境中執行 claude plugin list 時出現。它們不會在內嵌 /plugin list 輸出中出現。
• 使用 --plugin-dir 或 --plugin-url 為工作階段載入的外掛程式會在 /plugin 介面中出現，並且在相同旗標位於子命令前時才會在 claude plugin list 中出現，如 claude --plugin-dir <dir> plugin list。只有旗標名稱會指出它們的位置，因此裸 claude plugin list 無法找到它們，不同於同步外掛程式和技能目錄外掛程式，Claude Code 會掃描其固定目錄。

互動式形式接受 --enabled 或 --disabled 以僅顯示該狀態中的外掛程式，並接受 ls 作為 list 的簡寫。

plugin details

顯示外掛程式的元件清單和預計權杖成本。輸出列出外掛程式貢獻的所有元件，分組為技能、代理、掛鉤、MCP 伺服器和 LSP 伺服器，以及它為每個工作階段新增多少權杖的估計。技能群組包括 skills/ 和 commands/ 項目。

claude plugin details <name>

該命令接受這些引數：

• <name>：外掛程式名稱或 plugin-name@marketplace-name

該命令接受這些選項：

輸出為每個元件顯示兩個成本數字：

• Always-on： 外掛程式的列表文字（例如技能說明、代理說明和命令名稱）無論任何元件是否觸發，都會新增至每個工作階段的權杖。
• On-invoke： 元件觸發時的成本。按元件顯示，而不是外掛程式總計，因為典型工作階段只會叫用元件的子集。

此範例顯示具有兩個技能的外掛程式的輸出外觀：

dependency-guard 1.2.0
  Dependency analysis for Claude Code sessions
  Source: dependency-guard@example-marketplace

Component inventory
  Skills (2)  scan-dependencies, review-changes
  Agents (0)
  Hooks (1)  SessionStart  (harness-only — no model context cost)
  MCP servers (0)
  LSP servers (0)

Projected token cost
  Always-on:   ~180 tok   added to every session

Per-component (rounded)
  component            always-on  on-invoke
  scan-dependencies        ~100      ~2400
  review-changes            ~80      ~1800

  On-invoke cost is paid each time a skill or agent fires.
  Token counts are estimates and may differ from actual usage.

always-on 總計是透過您的作用中模型的 count_tokens API 計算的。按元件的數字按比例從該總計縮放。如果 API 無法到達，該命令會回退至基於字元的估計。

plugin validate

在發佈前檢查外掛程式或市集是否有語法和結構描述錯誤。

當驗證通過時命令退出 0，失敗時退出 1，驗證執行本身失敗時退出 2，例如當您傳遞的路徑無法讀取時。

claude plugin validate <path> [options]

該命令接受這些引數：

• <path>：外掛程式目錄或市集目錄的路徑。請參閱驗證沒有資訊清單的外掛程式或目錄以了解外掛程式執行涵蓋的檔案。

該命令接受這些選項：

使用 --json 時，Claude Code 會將報告寫入 stdout 作為一個 JSON 物件，具有這些頂層欄位：

• success：退出代碼給出的相同判決
• strict：執行是否將警告視為錯誤
• target：Claude Code 驗證的已解析路徑
• manifest：資訊清單本身的結果，或 null 用於沒有資訊清單的執行
• contents：按檔案結果，每個命名其 file 並攜帶 errors、warnings 和 notes 陣列

退出 2 時，該命令不會向 stdout 寫入任何內容；錯誤訊息會進入 stderr。

在互動式工作階段中，/plugin validate <path> 會內嵌執行相同的檢查。

plugin eval

執行外掛程式的評估案例並報告評分結果。需要 Claude Code v2.1.269 或更新版本。每個案例都是一個提示加評分者；Claude Code 在隔離的工作階段中執行它多次，只載入目標外掛程式，預設情況下也不載入外掛程式，以便報告顯示差異。請參閱使用評估測試外掛程式以了解案例格式、評分者、結果和 CI 使用。

claude plugin eval [target] [options]

選用的 target 是外掛程式目錄、單個 prompt.md 或 case.yaml 檔案、已安裝的外掛程式作為 name 或 name@marketplace，或 name@skills-dir，預設為目前目錄。將其放在 --tag、--allow-tools 和 --json 之前。

此表列出大多數執行使用的選項。執行 claude plugin eval --help 以取得完整集合，包括 --case、--tag、--output-dir、--report、--allow-real-servers、--keep-temp 和 --verbose。

當每個案例都符合閾值時，命令退出 0，在失敗案例、載入錯誤或不受信任的外掛程式目錄時退出 1，在部分執行時退出 2，中斷時退出 130，終止時退出 143。請參閱在 CI 中執行評估。

plugin eval init

為目前目錄中的外掛程式建立評估套件。需要 Claude Code v2.1.269 或更新版本。在終端中，這會啟動一個編寫訪談，讀取外掛程式、提議案例和評分者、試驗它們，並寫入檔案。使用 --bare 或沒有終端時，它會改為寫入一個空白的單案例範本。從互動式 Claude Code 工作階段內執行時，它會列印該工作階段要遵循的訪談說明，而不是寫入範本。請參閱建立您的第一個評估套件。

claude plugin eval init [name] [options]

選用的 name 是案例名稱：訪談不需要一個，而 --bare 和無終端範本路徑需要一個。它接受這些選項：

plugin tag

為外掛程式建立發行 git 標籤。根據預設，該命令會標籤目前目錄中的外掛程式；傳遞路徑以標籤其他位置的外掛程式。請參閱標籤外掛程式發行。

claude plugin tag [path] [options]

該命令接受這些引數：

• [path]：外掛程式目錄的路徑。預設為目前目錄。

該命令接受這些選項：

除錯和開發工具

除錯命令

使用 claude --debug 查看外掛程式載入詳細資訊：

這會顯示：

• 正在載入哪些外掛程式
• 外掛程式清單中的任何錯誤
• Skill、agent 和 hook 註冊
• MCP 伺服器初始化

常見問題

範例錯誤訊息

清單驗證錯誤：

• Invalid JSON syntax: Unexpected token } in JSON at position 142：檢查是否缺少逗號、多餘逗號或未加引號的字串
• Plugin <name> has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Invalid input: expected string, received undefined：缺少必需欄位
• Plugin <name> has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...：JSON 語法錯誤。在 v2.1.246 之前，Claude Code 也會針對以位元組順序標記 (BOM) 儲存為 UTF-8 的 plugin.json 產生此錯誤，即使 JSON 在其他方面有效。

外掛程式載入錯誤：

• Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.：命令路徑存在但不包含有效的命令檔案
• Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.：marketplace.json 中的 source 路徑指向不存在的目錄
• Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.：移除重複的元件定義或移除 marketplace 項目中的 strict: false

Hook 除錯

Hook 指令碼未執行：

1. 檢查指令碼是否可執行：chmod +x ./scripts/your-script.sh
2. 驗證 shebang 行：第一行應為 #!/bin/bash 或 #!/usr/bin/env bash
3. 檢查路徑是否使用 ${CLAUDE_PLUGIN_ROOT}："command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/your-script.sh"
4. 手動測試指令碼：./scripts/your-script.sh

Hook 未在預期事件上觸發：

1. 驗證事件名稱正確（區分大小寫）：PostToolUse，而不是 postToolUse
2. 檢查匹配器模式是否與您的工具相符："matcher": "Write|Edit" 用於檔案操作
3. 確認 hook 類型有效：command、http、mcp_tool、prompt 或 agent

MCP 伺服器除錯

伺服器未啟動：

1. 檢查命令是否存在且可執行
2. 驗證所有路徑都使用 ${CLAUDE_PLUGIN_ROOT} 變數
3. 檢查 MCP 伺服器日誌：claude --debug 顯示初始化錯誤
4. 在 Claude Code 外手動測試伺服器

伺服器工具未出現：

1. 確保伺服器在 .mcp.json 或 plugin.json 中正確設定
2. 驗證伺服器正確實作 MCP 協定
3. 檢查除錯輸出中的連線逾時

目錄結構錯誤

症狀：外掛程式載入但元件（skills、agents、hooks）遺失。

正確結構：元件必須位於外掛程式根目錄，而不是在 .claude-plugin/ 內。只有 plugin.json 屬於 .claude-plugin/。

除錯檢查清單：

1. 執行 claude --debug 並查找「loading plugin」訊息
2. 檢查每個元件目錄是否列在除錯輸出中
3. 驗證檔案權限允許讀取外掛程式檔案

發佈和版本管理參考

版本管理

Claude Code 使用外掛程式的版本作為快取金鑰，以判斷是否有可用的更新。當您執行 /plugin update 或自動更新觸發時，Claude Code 會計算目前版本，如果與已安裝的版本相符，則跳過更新。

對於除了 command 以外的每種來源類型，Claude Code 會從以下第一個已設定的項目解析版本：

1. 外掛程式 plugin.json 中的 version 欄位
2. 外掛程式在 marketplace.json 中的市集項目中的 version 欄位
3. 外掛程式來源的 git 提交 SHA，適用於 git 託管市集中的 github、url、git-subdir 和相對路徑來源
4. SHA-256 摘要，適用於 archive 來源：市集項目中的 sha256 釘選，或當您未設定釘選時下載檔案的摘要。Claude Code 將其縮短為前 12 個字元
5. unknown，適用於 npm 來源或不在 git 儲存庫內的本機目錄

對於 command 來源，Claude Code 始終從命令產生的內容衍生版本：單獨的 12 字元內容雜湊，或在設定了一個時附加到 plugin.json 版本作為 <version>-<hash>。Claude Code 會忽略命令來源的市集項目 version 欄位。因此，命令的雜湊輸出變更會產生新版本，即使編寫的版本字串保持不變。在連結模式中，雜湊涵蓋列印目錄的實際路徑及其頂層項目，而不是檔案內容。

對於這些來源類型，這為您提供了三種方式來版本化外掛程式：

如果您使用明確版本，請遵循語義版本控制（MAJOR.MINOR.PATCH）：針對重大變更更新 MAJOR，針對新功能更新 MINOR，針對錯誤修正更新 PATCH。在 CHANGELOG.md 中記錄變更。

另請參閱

• Plugins - 教學和實際使用
• Plugin marketplaces - 建立和管理 marketplaces
• Skills - Skill 開發詳細資訊
• Subagents - Agent 設定和功能
• Hooks - 事件處理和自動化
• MCP - 外部工具整合
• Settings - Plugins 的設定選項