Go Premium Account

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

This page contains 0 additions and 1645 deletions.

2026

Thu 10 23:00 Sat 12 03:02 Sun 13 21:00 Fri 18 23:58 Tue 22 23:59 Fri 25 23:58

This document has no rendered page for this history range.

plugins-reference.md +0 −1645 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# Plugins 參考~~

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

~~9<Tip>~~

10 想要安裝 plugins？請參閱 [探索和安裝 plugins](/docs/zh-TW/discover-plugins)。如需建立 plugins，請參閱 [Plugins](/docs/zh-TW/plugins)。如需發佈 plugins，請參閱 [Plugin 市場](/docs/zh-TW/plugin-marketplaces)。

~~11</Tip>~~

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

~~15<h2 id="plugin-components-reference">~~

~~16 Plugin 元件參考~~

~~17</h2>~~

~~19<h3 id="skills">~~

~~20 Skills~~

~~21</h3>~~

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

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

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

~~29**Skill 結構**：~~

~~31```text theme={null}~~

~~32skills/~~

~~33├── pdf-processor/~~

~~34│ ├── SKILL.md~~

~~35│ ├── reference.md (optional)~~

~~36│ └── scripts/ (optional)~~

~~37└── code-reviewer/~~

~~38 └── SKILL.md~~

~~39```~~

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

43如果 plugin 沒有 `skills/` 目錄且沒有 `skills` manifest 欄位，plugin 根目錄中的 `SKILL.md` 會被載入為單一 skill。設定 frontmatter `name` 欄位以控制 skill 的叫用名稱。沒有設定的話，Claude Code 會回退到安裝目錄名稱。對於 [複製到快取中](#plugin-caching-and-file-resolution) 的 plugin，該名稱是一個在每次更新時都會改變的版本字串。對於提供多個 skills 的 plugins，請使用上面所示的 `skills/` 目錄配置。

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

~~47如需完整詳細資訊，請參閱 [Skills](/docs/zh-TW/skills)。~~

~~49<h3 id="agents">~~

~~50 Agents~~

~~51</h3>~~

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

~~55**位置**：plugin 根目錄中的 `agents/` 目錄~~

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

~~59**Agent 結構**：~~

~~61```markdown theme={null}~~

~~62name: agent-name~~

~~63description: What this agent specializes in and when Claude should invoke it~~

~~64model: sonnet~~

~~65effort: medium~~

~~66maxTurns: 20~~

~~67disallowedTools: Write, Edit~~

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

~~70```~~

~~72<h4 id="plugin-agent-frontmatter">~~

~~73 Plugin agent frontmatter~~

~~74</h4>~~

76Plugin agent 檔案使用與 [subagent 檔案相同的 frontmatter 欄位](/docs/zh-TW/sub-agents#supported-frontmatter-fields)，除了當 agent 來自 plugin 時，Claude Code 只支援其中一些：

78* **支援**：`name`、`description`、`model`、`effort`、`maxTurns`、`tools`、`disallowedTools`、`skills`、`memory`、`background`、`omitClaudeMd`、`isolation`、`color` 和 `experimental`。唯一有效的 `isolation` 值是 `"worktree"`。

79* **基於安全考量不支援**：`hooks`、`mcpServers` 和 `permissionMode`。Claude Code 在從 plugin 載入 agent 時會忽略這些。若要使用它們，請將 agent 檔案複製到 `.claude/agents/` 或 `~/.claude/agents/`。

~~80* **不支援**：`initialPrompt`。~~

82您可以將 plugin agent 檔案放在 `agents/` 的子資料夾中。Claude Code [會遞迴載入它們](/docs/zh-TW/sub-agents#choose-the-subagent-scope)，並將 plugin 名稱、每個子資料夾名稱和檔案名稱用冒號連接以形成 agent 的範圍名稱。例如，名為 `my-plugin` 的 plugin 中的 `agents/review/security.md` 會載入為 `my-plugin:review:security`。兩個設定會改變該名稱：

~~84* Frontmatter `name`：它只替換檔案名稱，所以 `agents/review/security.md` 中的 `name: audit` 會載入為 `my-plugin:review:audit`~~

85* Manifest [`agents`](#component-path-fields) 欄位：您在其中列出的檔案會載入而不含子資料夾名稱，所以 `"agents": "./custom/review/security.md"` 會載入為 `my-plugin:security`

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

~~89* 沒有 `name`：Claude Code 會根據檔案名稱為 agent 命名，所以名為 `my-plugin` 的 plugin 中的 `agents/reviewer.md` 會載入為 `my-plugin:reviewer`~~

~~90* 無法解析的 Frontmatter：Claude Code 會根據檔案名稱為 agent 命名，使用 `Agent from my-plugin plugin` 作為其描述，並忽略檔案中的每個欄位~~

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

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

~~96* 具有 manifest 的 plugin：`claude plugin validate ./my-plugin`~~

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

~~99Agents 會在 [@-mention 類型提前](/docs/zh-TW/sub-agents#invoke-subagents-explicitly) 中以其範圍名稱（例如 `my-plugin:code-reviewer`）出現，一旦 plugin 被啟用。~~

~~100~~

101如需完整詳細資訊，請參閱 [Subagents](/docs/zh-TW/sub-agents)。

~~102~~

103<h3 id="hooks">

104 Hooks

105</h3>

~~106~~

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

~~108~~

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

~~110~~

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

~~112~~

113`hooks/hooks.json` 可以攜帶頂層 `$schema` 金鑰，該金鑰命名 JSON Schema URL 以供編輯器自動完成和驗證。Claude Code 在載入時會忽略該金鑰。

~~114~~

115**Hook 設定**：

~~116~~

117```json theme={null}

118{

119 "hooks": {

120 "PostToolUse": [

121 {

122 "matcher": "Write|Edit",

123 "hooks": [

124 {

125 "type": "command",

126 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/format-code.sh"

127 }

128 ]

129 }

130 ]

131 }

132}

133```

~~134~~

135Plugin hooks 回應與 [使用者定義的 hooks](/docs/zh-TW/hooks) 相同的生命週期事件：

~~136~~

137| 事件 | 何時觸發 |

138| :-------------------- | :-------------------------------------------------------------------------------------------------------------------- |

139| `SessionStart` | 當工作階段開始或繼續時 |

140| `Setup` | 當您使用 `--init-only` 啟動 Claude Code，或在 `-p` 模式中使用 `--init` 或 `--maintenance` 時。用於 CI 或指令碼中的一次性準備 |

141| `UserPromptSubmit` | 當您提交提示詞時，在 Claude 處理之前 |

142| `UserPromptExpansion` | 當使用者輸入的命令擴展為提示詞時，在到達 Claude 之前。可以阻止擴展 |

143| `PreToolUse` | 在工具呼叫執行之前。可以阻止它 |

144| `PermissionRequest` | 當工具呼叫需要權限決定時 |

145| `PermissionDenied` | 當自動模式拒絕工具呼叫時，包括沒有分類器判決的拒絕。使用 JSON `hookSpecificOutput.retry: true` 告訴模型它可能重試被拒絕的工具呼叫。Claude Code 在分類器未產生判決時忽略 `retry` |

146| `PostToolUse` | 在工具呼叫成功後 |

147| `PostToolUseFailure` | 在工具呼叫失敗後 |

148| `PostToolBatch` | 在完整的平行工具呼叫批次解決後，在下一個模型呼叫之前 |

149| `Notification` | 當 Claude Code 傳送通知時 |

150| `MessageDisplay` | 在助手訊息文字顯示時 |

151| `SubagentStart` | 當子代理被生成時 |

152| `SubagentStop` | 當子代理完成時 |

153| `TaskCreated` | 當透過 `TaskCreate` 建立任務時 |

154| `TaskCompleted` | 當任務被標記為已完成時 |

155| `Stop` | 當 Claude 完成回應時 |

156| `StopFailure` | 當回合因 API 錯誤而結束時 |

157| `TeammateIdle` | 當[代理團隊](/docs/zh-TW/agent-teams)隊友即將閒置時 |

158| `InstructionsLoaded` | 當 CLAUDE.md 或 `.claude/rules/*.md` 檔案被載入到上下文時。在工作階段開始時以及在工作階段期間延遲載入檔案時觸發 |

159| `ConfigChange` | 當設定檔在工作階段期間變更時 |

160| `CwdChanged` | 當工作目錄變更時，例如當 Claude 執行 `cd` 命令時。適用於使用 direnv 等工具進行反應式環境管理 |

161| `DirectoryAdded` | 當工作目錄在工作階段中期透過 `/add-dir` 或 SDK `register_repo_root` 控制請求新增時 |

162| `FileChanged` | 當監視的檔案在磁碟上變更時。`matcher` 欄位指定要監視的檔案名稱 |

163| `WorktreeCreate` | 當透過 `--worktree`、`isolation: "worktree"` 建立 worktree 時，或用於背景工作階段時。取代預設的 git 行為 |

164| `WorktreeRemove` | 當在工作階段結束時、子代理完成時或您刪除背景工作階段時移除 worktree 時 |

165| `PreCompact` | 在上下文壓縮之前 |

166| `PostCompact` | 在上下文壓縮完成後 |

167| `PreModelSwitch` | 在 Claude Code 應用您或用戶端要求的模型切換之前。可以阻止切換 |

168| `PostModelSwitch` | 在工作階段的模型變更後，包括 Claude Code 自行進行的變更，例如當您繼續工作階段時恢復模型 |

169| `Elicitation` | 當 MCP 伺服器在工具呼叫期間要求使用者輸入時 |

170| `ElicitationResult` | 在使用者回應 MCP 引出後，在回應傳送回伺服器之前 |

171| `SessionEnd` | 當工作階段終止時 |

~~172~~

173**Hook 類型**：

~~174~~

175* `command`：執行 shell 命令或指令碼

176* `http`：將事件 JSON 作為 POST 請求傳送到 URL

177* `mcp_tool`：在已設定的 [MCP server](/docs/zh-TW/mcp) 上呼叫工具

178* `prompt`：使用 LLM 評估提示（使用 `$ARGUMENTS` 預留位置作為內容）

179* `agent`：執行具有工具的代理程式驗證器以進行複雜驗證任務

~~180~~

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

~~182~~

183<h3 id="mcp-servers">

184 MCP servers

185</h3>

~~186~~

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

~~188~~

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

~~190~~

191**格式**：標準 MCP 伺服器設定

~~192~~

193**MCP 伺服器設定**：

~~194~~

195```json theme={null}

196{

197 "mcpServers": {

198 "plugin-database": {

199 "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",

200 "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],

201 "env": {

202 "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"

203 }

204 },

205 "plugin-api-client": {

206 "command": "npx",

207 "args": ["@company/mcp-server", "--plugin-mode"]

208 }

209 }

210}

211```

~~212~~

213**整合行為**：

~~214~~

215* Plugin MCP 伺服器在 plugin 啟用時自動啟動

216* 伺服器在 Claude 的工具組中顯示為標準 MCP 工具

217* Plugin 伺服器可以獨立於使用者 MCP 伺服器進行設定

218* 如果您在工作階段中執行 [`/reload-plugins`](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting)，Claude Code 會保持其設定未變更的伺服器的即時連接

~~219~~

220<h3 id="lsp-servers">

221 LSP servers

222</h3>

~~223~~

224<Tip>

225 尋找使用 LSP plugins？從官方 marketplace 安裝它們：在 `/plugin` Discover 標籤中搜尋「lsp」。本節記錄如何為官方 marketplace 未涵蓋的語言建立 LSP plugins。

226</Tip>

~~227~~

228Plugins 可以提供 [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) 伺服器，以在處理您的程式碼庫時為 Claude 提供 [即時程式碼智慧](/docs/zh-TW/discover-plugins#code-intelligence)。

~~229~~

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

~~231~~

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

~~233~~

234**`.lsp.json` 檔案格式**：

~~235~~

236```json theme={null}

237{

238 "go": {

239 "command": "gopls",

240 "args": ["serve"],

241 "extensionToLanguage": {

242 ".go": "go"

243 }

244 }

245}

246```

~~247~~

248**在 `plugin.json` 中內聯**：

~~249~~

250```json theme={null}

251{

252 "name": "my-plugin",

253 "lspServers": {

254 "go": {

255 "command": "gopls",

256 "args": ["serve"],

257 "extensionToLanguage": {

258 ".go": "go"

259 }

260 }

261 }

262}

263```

~~264~~

265**必需欄位：**

~~266~~

267| 欄位 | 描述 |

268| :-------------------- | :------------------------ |

269| `command` | 要執行的 LSP 二進位檔（必須在 PATH 中） |

270| `extensionToLanguage` | 將檔案副檔名對應到語言識別碼 |

~~271~~

272**選用欄位：**

~~273~~

274| 欄位 | 描述 |

275| :---------------------- | :------------------------------------------------------------------------------------------ |

276| `args` | LSP 伺服器的命令列引數 |

277| `transport` | 通訊傳輸：`stdio`（預設）或 `socket`。Claude Code 接受 `socket` 但在 stdio 上執行每個伺服器，因此 stdout 協定規則適用於所有伺服器 |

278| `env` | 啟動伺服器時要設定的環境變數 |

279| `initializationOptions` | 在初始化期間傳遞給伺服器的選項 |

280| `settings` | 透過 `workspace/didChangeConfiguration` 傳遞的設定 |

281| `workspaceFolder` | 伺服器的工作區資料夾路徑 |

282| `startupTimeout` | 等待伺服器啟動的最長時間（毫秒） |

283| `shutdownTimeout` | 等待正常關閉的最長時間（毫秒）。當逾時時間過去時，Claude Code 會終止伺服器程序。未設定時，不適用逾時 |

284| `restartOnCrash` | 伺服器當機後是否重新啟動。預設為 `true`。設定為 `false` 以保持當機的伺服器停止而不是重新啟動 |

285| `maxRestarts` | 放棄前的最大重新啟動嘗試次數 |

286| `diagnostics` | 編輯後是否將診斷推送到 Claude 的內容中（預設 `true`）。設定為 `false` 以保持程式碼導覽但抑制自動診斷注入 |

~~287~~

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

~~289~~

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

~~291~~

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

~~293~~

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

~~295~~

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

~~297~~

298<Warning>

299 **您必須單獨安裝語言伺服器二進位檔。** LSP plugins 設定 Claude Code 如何連接到語言伺服器，但它們不包括伺服器本身。如果您在 `/plugin` Errors 標籤中看到 `Executable not found in $PATH`，請為您的語言安裝所需的二進位檔。

300</Warning>

~~301~~

302**可用的 LSP plugins：**

~~303~~

304| Plugin | 語言伺服器 | 安裝命令 |

305| :------------------ | :------------------------- | :------------------------------------------------------------------------------- |

306| `pyright-lsp` | Pyright (Python) | `pip install pyright` 或 `npm install -g pyright` |

307| `typescript-lsp` | TypeScript Language Server | `npm install -g typescript-language-server typescript` |

308| `rust-analyzer-lsp` | rust-analyzer | [請參閱 rust-analyzer 安裝](https://rust-analyzer.github.io/manual.html#installation) |

~~309~~

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

~~311~~

312<h3 id="monitors">

313 Monitors

314</h3>

~~315~~

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

~~317~~

318Plugin monitors 使用與 [Monitor tool](/docs/zh-TW/tools-reference#monitor-tool) 相同的機制，並共享其可用性限制。它們僅在互動式 CLI 工作階段中執行，以與 [hooks](#hooks) 相同的信任層級在未沙箱化的環境中執行，並在 Monitor tool 不可用的主機上被跳過。

~~319~~

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

~~321~~

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

~~323~~

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

~~325~~

326```json theme={null}

327[

328 {

329 "name": "deploy-status",

330 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",

331 "description": "Deployment status changes"

332 },

333 {

334 "name": "error-log",

335 "command": "tail -F ./logs/error.log",

336 "description": "Application error log",

337 "when": "on-skill-invoke:debug"

338 }

339]

340```

~~341~~

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

~~343~~

344**必需欄位：**

~~345~~

346| 欄位 | 描述 |

347| :------------ | :------------------------------------------------ |

348| `name` | 在 plugin 中唯一的識別碼。防止 plugin 重新載入或再次叫用 skill 時的重複程序 |

349| `command` | 在工作階段工作目錄中作為持久背景程序執行的 shell 命令 |

350| `description` | 正在監視的內容的簡短摘要。顯示在工作面板和通知摘要中 |

~~351~~

352**選用欄位：**

~~353~~

354| 欄位 | 描述 |

355| :----- | :----------------------------------------------------------------------------------------------------------------- |

356| `when` | 控制監視器何時啟動。`"always"` 在工作階段啟動和 plugin 重新載入時啟動它，是預設值。`"on-skill-invoke:<skill-name>"` 在此 plugin 中的命名 skill 首次被分派時啟動它 |

~~357~~

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

~~359~~

360Monitor `command` 無法參考 [`${user_config.*}`](#user-configuration) 值。命令透過 shell 執行，因此 Claude Code 會以 [error](/docs/zh-TW/errors#plugin-command-references-user-config) 拒絕監視器，而不是替換值。Monitor 程序不會接收 `CLAUDE_PLUGIN_OPTION_<KEY>` 環境變數，因此讓監視器指令碼從它擁有的設定檔讀取值。

~~361~~

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

~~363~~

364<h3 id="themes">

365 Themes

366</h3>

~~367~~

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

~~369~~

370```json theme={null}

371{

372 "name": "Dracula",

373 "base": "dark",

374 "overrides": {

375 "claude": "#bd93f9",

376 "error": "#ff5555",

377 "success": "#50fa7b"

378 }

379}

380```

~~381~~

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

~~383~~

384***

~~385~~

386<h2 id="plugin-installation-scopes">

387 Plugin 安裝範圍

388</h2>

~~389~~

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

~~391~~

392| 範圍 | 設定檔 | 使用案例 |

393| :-------- | :------------------------------------------ | :------------------------------------------------ |

394| `user` | `~/.claude/settings.json` | 個人 plugin，可在所有專案中使用（預設） |

395| `project` | `.claude/settings.json` | 透過版本控制共享的團隊 plugin |

396| `local` | `.claude/settings.local.json` | 專案特定的 plugin，當 Claude Code 將設定儲存到其中時會被 gitignored |

397| `managed` | [Managed settings](/docs/zh-TW/managed-settings) | 受管理的 plugin（唯讀，僅更新） |

~~398~~

399Plugin 使用與其他 Claude Code 設定相同的範圍系統。如需安裝說明和範圍旗標，請參閱 [Install plugins](/docs/zh-TW/discover-plugins#install-plugins)。如需範圍的完整說明，請參閱 [Configuration scopes](/docs/zh-TW/settings#where-settings-live)。

~~400~~

401***

~~402~~

403<h2 id="skills-directory-plugins">

404 Skills-directory plugins

405</h2>

~~406~~

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

~~408~~

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

~~410~~

411| 你擁有的 | 它是什麼 |

412| :-------------------------------------------- | :------------------------------------------------------- |

413| `<skills-dir>/foo/SKILL.md` 且沒有清單 | 一個名為 `foo` 的純 [skill](/docs/zh-TW/skills) |

414| `<skills-dir>/foo/.claude-plugin/plugin.json` | 一個 plugin `foo@skills-dir`，可以捆綁自己的 skills、agents、hooks 等 |

415| `<plugin>/skills/bar/SKILL.md` | 一個 skill `bar` 打包在 plugin 內 |

~~416~~

417<h3 id="choose-where-the-plugin-loads-from">

418 選擇 plugin 從何處載入

419</h3>

~~420~~

421| Skills 目錄 | 範圍 | 載入 |

422| :---------------------- | :- | :---------------------------------------------------------------------------------- |

423| `~/.claude/skills/` | 個人 | 在每個專案中，因為該位置只屬於你 |

424| `<cwd>/.claude/skills/` | 專案 | 只有在你接受該資料夾的工作區 [信任對話](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder) 後才會載入 |

~~425~~

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

~~427~~

428* 它宣告的 MCP 伺服器會經過與專案 `.mcp.json` 相同的 [每個伺服器批准](/docs/zh-TW/mcp)

429* LSP 伺服器只有在你信任工作區後才會啟動

430* [背景監視器](#monitors) 不會載入

~~431~~

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

~~433~~

434<Warning>

435 專案範圍的 `@skills-dir` plugins 只從工作階段的 [主要工作目錄](/docs/zh-TW/permissions#working-directories) 的 `.claude/skills/` 載入。它們不會像純 skills 和命令那樣 [向上走到儲存庫根目錄](/docs/zh-TW/skills#discovery-from-parent-and-nested-directories)，所以從子目錄啟動會錯過位於儲存庫根目錄的 plugin。從儲存庫根目錄啟動，或在 v2.1.246 或更新版本上 [使用 `/cd` 將工作階段移到那裡](/docs/zh-TW/permissions#move-the-session-to-another-directory)。

436</Warning>

~~437~~

438<h3 id="edit-reload-and-disable-a-skills-directory-plugin">

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

440</h3>

~~441~~

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

~~443~~

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

~~445~~

446```bash theme={null}

447claude plugin disable my-tool@skills-dir

448```

~~449~~

450***

~~451~~

452<h2 id="synced-plugins">

453 從 claude.ai 同步的外掛程式

454</h2>

~~455~~

456Claude Code 會載入為您的 claude.ai 帳戶啟用的外掛程式，包括您的組織為其成員開啟的外掛程式，以及您從 marketplace 安裝的外掛程式。它會將每個外掛程式下載到 `~/.claude/plugins/synced/` 中，並將其載入為 `<name>@synced`，沒有 marketplace 也沒有安裝記錄。同步的外掛程式執行時具有與您安裝的 marketplace 外掛程式相同的信任等級：其 skills、agents、hooks、MCP 伺服器和 LSP 伺服器都會載入。

~~457~~

458Claude Code 同步這些外掛程式的位置取決於工作階段：

~~459~~

460* 在 [Cowork](https://claude.com/product/cowork) 和[雲端工作階段](/docs/zh-TW/cloud-environments#what-carries-over-from-your-setup)中，Claude Code 會在工作階段啟動時將它們下載到工作階段自身的環境中。在 v2.1.239 之前，Claude Code 將這些外掛程式載入為 `<name>@inline`，這是 `--plugin-dir` 外掛程式使用的身分。

461* 在您使用 claude.ai 帳戶登入的終端機工作階段中，Claude Code 每次啟動時會檢查您的帳戶一次，然後在背景中下載新的和更新的外掛程式，並移除您或您的組織關閉的外掛程式。終端機工作階段中的同步需要 Claude Code v2.1.273 或更新版本。

~~462~~

463啟動檢查在背景中執行，因此可以在您的工作階段啟動後完成。當它在互動式工作階段中新增、更新或移除同步的外掛程式時，Claude Code 會顯示 `Plugins changed. Run /reload-plugins to activate.` 執行 [`/reload-plugins`](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting) 以在該工作階段中載入變更，或留待下次啟動 Claude Code 時再進行。如果您在工作階段執行時在 claude.ai 上啟用外掛程式，Claude Code 會在下次啟動時下載它。

~~464~~

465終端機工作階段中的外掛程式同步在與[從 claude.ai 同步的 skills](/docs/zh-TW/skills#where-synced-skills-load)相同的登入條件下執行。它還需要授予 Claude Code 存取您帳戶外掛程式的登入。

~~466~~

467來自較早版本 Claude Code 的登入會在 Claude Code 在背景中更新該登入時（通常在幾小時內）或在您再次執行 `/login` 時立即取得外掛程式存取權限。外掛程式同步會在您之後下次啟動 Claude Code 時開始。

~~468~~

469`claude plugin list` 會在 `Synced from claude.ai` 標題下顯示同步的外掛程式，而 `/plugin` **Installed** 標籤會列出它們，並以 `synced` 作為其來源。使用 `claude plugin list` 列印的 `<name>@synced` ID 來管理同步的外掛程式：

~~470~~

471* **關閉其中一個**：執行 `claude plugin disable <name>@synced`，或從 `/plugin` **Installed** 標籤中停用它。Claude Code 會將選擇儲存為您使用者層級 [`enabledPlugins`](/docs/zh-TW/settings-reference#enabledplugins) 中的 `"<name>@synced": false`。若要重新開啟外掛程式，請執行 `claude plugin enable <name>@synced`。

472* **在任何地方都排除其中一個**：[為您的 claude.ai 帳戶關閉外掛程式](/docs/zh-TW/desktop#extend-claude-code)。若要在每個環境中將其排除在一個專案之外，請在該專案已提交的 `.claude/settings.json` 中的 `enabledPlugins` 下設定 `"<name>@synced": false`。

473* **在 claude.ai 上管理外掛程式本身**：`claude plugin install`、`update` 和 `uninstall` 不適用於同步的外掛程式。Claude Code 會在下次同步時下載外掛程式的更新。若要移除一個，請為您的 claude.ai 帳戶關閉外掛程式，Claude Code 會在下次同步時將其移除。

474* **停止在機器上同步**：在您的使用者設定中將 [`syncClaudeAiPlugins`](/docs/zh-TW/settings-reference#syncclaudeaiplugins) 設定為 `false`。Claude Code 會停止下載，下次啟動時會將已同步的外掛程式移動到 `~/.claude/plugins/.trash/`，並不再載入它們。您的組織可以在[受管設定](/docs/zh-TW/managed-settings)中設定相同的金鑰，或在 claude.ai 上關閉 Skills，這也會停止外掛程式同步。

~~475~~

476您無法關閉您的組織在 claude.ai 上標記為必需的外掛程式。Claude Code 會載入它，即使您之前停用了它，而 `claude plugin disable` 會拒絕並顯示 `Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it.` 在 `claude plugin list` 中，這些外掛程式會標記為 `required by your org`。

~~477~~

478當來自任何其他來源的已啟用外掛程式與同步外掛程式的名稱相符時，Claude Code 會載入該外掛程式並報告同步副本未被載入。其他來源包括 marketplace 安裝、[skills 目錄外掛程式](#skills-directory-plugins)、`--plugin-dir` 外掛程式和內建於 Claude Code 的外掛程式。若要改用 claude.ai 副本，請停用您自己的副本。在 v2.1.239 之前，Claude Code 會載入同步副本而不是同名的 marketplace 安裝。

~~479~~

480***

~~481~~

482<h2 id="plugin-manifest-schema">

483 Plugin manifest schema

484</h2>

~~485~~

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

~~487~~

488manifest 是選用的。如果省略，Claude Code 會在[預設位置](#file-locations-reference)自動探索元件，並從目錄名稱衍生 plugin 名稱。當你需要提供中繼資料或自訂元件路徑時，請使用 manifest。

~~489~~

490<h3 id="complete-schema">

491 Complete schema

492</h3>

~~493~~

494```json theme={null}

495{

496 "name": "plugin-name",

497 "displayName": "Plugin Name",

498 "version": "1.2.0",

499 "description": "Brief plugin description",

500 "author": {

501 "name": "Author Name",

502 "email": "author@example.com",

503 "url": "https://github.com/author"

504 },

505 "homepage": "https://docs.example.com/plugin",

506 "repository": "https://github.com/author/plugin",

507 "license": "MIT",

508 "keywords": ["keyword1", "keyword2"],

509 "metadata": { "catalogId": "cat-123", "tier": "pro" },

510 "skills": "./custom/skills/",

511 "commands": ["./custom/commands/special.md"],

512 "agents": ["./custom/agents/reviewer.md"],

513 "hooks": "./config/hooks.json",

514 "mcpServers": "./mcp-config.json",

515 "outputStyles": "./styles/",

516 "lspServers": "./.lsp.json",

517 "experimental": {

518 "themes": "./themes/",

519 "monitors": "./monitors.json",

520 "evals": "quality/evals"

521 },

522 "dependencies": [

523 "helper-lib",

524 { "name": "secrets-vault", "version": "~2.1.0" }

525 ]

526}

527```

~~528~~

529<h3 id="required-fields">

530 必需欄位

531</h3>

~~532~~

533如果你包含 manifest，`name` 是唯一必需的欄位。

~~534~~

535| 欄位 | 類型 | 說明 | 範例 |

536| :----- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------- |

537| `name` | string | 唯一識別碼，採用 kebab-case，不含空格、控制字元或雙向格式化字元。當[marketplace 項目](/docs/zh-TW/plugin-marketplaces#plugin-entries)以不同名稱列出 plugin 時，marketplace 項目名稱是 `enabledPlugins` 鍵和 `/plugin` 使用的名稱 | `"deployment-tools"` |

~~538~~

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

~~540~~

541<h3 id="unrecognized-fields">

542 無法識別的欄位

543</h3>

~~544~~

545Claude Code 會忽略它無法識別的頂層欄位。你可以在 `plugin.json` 中保留來自另一個生態系統的中繼資料，plugin 仍然會載入。這使得維護一個 manifest 作為 VS Code 或 Cursor extension manifest、npm `package.json` 或 MCPB/DXT bundle manifest 變得實用。

~~546~~

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

~~548~~

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

~~550~~

551* **大多數欄位**：plugin 無法載入。例如，`keywords` 值是字串而不是陣列是載入錯誤，`claude plugin validate` 會將其報告為錯誤。

552* **`experimental` 和 `metadata`**：Claude Code 會忽略非物件值，`claude plugin validate` 會報告警告。

~~553~~

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

~~555~~

556```bash theme={null}

557claude plugin validate ./my-plugin --strict

558```

~~559~~

560<h3 id="metadata-fields">

561 中繼資料欄位

562</h3>

~~563~~

564| 欄位 | 類型 | 說明 | 範例 |

565| :--------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- |

567| `displayName` | string | 在 `/plugin` 選擇器和其他 UI 表面中顯示的人類可讀名稱。對於 marketplace 安裝的 plugin，[marketplace 項目](/docs/zh-TW/plugin-marketplaces#optional-plugin-fields)上的 `displayName` 優先於此值。當兩個位置都未設定顯示名稱時，使用者會看到 `name`。與 `name` 不同，可以包含空格和任何大小寫。不用於命名空間或查詢。 | `"Deployment Tools"` |

568| `version` | string | 選用。語義版本。設定此項會將 plugin 固定到該版本字串，因此使用者只有在你提升版本時才會收到更新，除了[`command` source](/docs/zh-TW/plugin-marketplaces#command-sources)或[就地載入](#plugin-caching-and-file-resolution)的 plugin；請參閱[版本管理](#version-management)。如果也在 marketplace 項目中設定，`plugin.json` 優先。如果省略，版本來自[版本管理](#version-management)中的下一個來源。 | `"2.1.0"` |

570| `author` | object | 作者資訊 | `{"name": "Dev Team", "email": "dev@company.com"}` |

575| `metadata` | object | 自由格式物件，用於你自己的資料，例如權利或目錄欄位。Claude Code 不會讀取它，因此值永遠不會影響 plugin 行為。Claude Code 會忽略非物件值，`claude plugin validate` 會將其報告為警告。在 v2.1.222 之前，Claude Code 將該鍵視為[無法識別的欄位](#unrecognized-fields)。 | `{"catalogId": "cat-123"}` |

~~577~~

578<h3 id="default-enablement">

579 預設啟用

580</h3>

~~581~~

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

~~583~~

584`defaultEnabled` 是當沒有其他因素決定 plugin 狀態時的後備。使用者的設定和依賴項要求優先於它：

~~585~~

586* **使用者的設定**：任何設定範圍中 `enabledPlugins` 中的 plugin 項目。一旦寫入，它會在 plugin 更新和重新安裝中持續存在，因此在後續版本中變更 `defaultEnabled` 不會翻轉現有使用者。

587* **依賴項要求**：當 plugin 由另一個活躍的 plugin 要求時，Claude Code 在安裝或啟用時為其寫入 `true`。這給了它一個明確的設定，因此它自己的預設不再適用。請參閱[啟用或停用具有依賴項的 plugin](/docs/zh-TW/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies)。

~~588~~

589相同的欄位可以出現在 plugin 的 marketplace 項目中，其優先於 `plugin.json` 中的值。請參閱[選用 plugin 欄位](/docs/zh-TW/plugin-marketplaces#optional-plugin-fields)。

~~590~~

591<h3 id="component-path-fields">

592 元件路徑欄位

593</h3>

~~594~~

595| 欄位 | 類型 | 說明 | 範例 |

596| :---------------------- | :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |

610| `dependencies` | array | 此 plugin 需要的其他 plugin，可選擇使用 semver 版本限制。請參閱[限制 plugin 依賴項版本](/docs/zh-TW/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |

~~611~~

612<h3 id="experimental-components">

613 實驗性元件

614</h3>

~~615~~

616`experimental` 鍵下的元件 `themes` 和 `monitors` 具有在版本之間可能變更的 manifest schema，同時它們穩定。你宣告它們的位置是一個單獨的遷移：頂層仍然有效，`claude plugin validate` 發出警告，未來版本將需要 `experimental.*`。

~~617~~

618<h3 id="user-configuration">

619 使用者設定

620</h3>

~~621~~

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

~~623~~

624```json theme={null}

625{

626 "userConfig": {

627 "api_endpoint": {

628 "type": "string",

629 "title": "API endpoint",

630 "description": "Your team's API endpoint"

631 },

632 "api_token": {

633 "type": "string",

634 "title": "API token",

635 "description": "API authentication token",

636 "sensitive": true

637 }

638 }

639}

640```

~~641~~

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

~~643~~

644| 欄位 | 必需 | 說明 |

645| :------------ | :- | :--------------------------------------------------------------------------------------------------------------------------- |

646| `type` | 是 | `string`、`number`、`boolean`、`directory` 或 `file` 之一 |

647| `title` | 是 | 在設定對話方塊中顯示的標籤 |

648| `description` | 是 | 在欄位下方顯示的說明文字 |

649| `sensitive` | 否 | 如果為 `true`，會遮罩輸入並將值儲存在安全儲存中而不是 `settings.json` |

650| `required` | 否 | 如果為 `true`，當欄位為空時驗證失敗 |

651| `default` | 否 | 當使用者未提供任何內容時使用的值 |

652| `options` | 否 | 對於 `string` 類型，欄位接受的值，在 `/config` 中顯示為它們上的選擇器。請參閱[將欄位限制為固定選項](#limit-a-field-to-fixed-options)。需要 Claude Code v2.1.271 或更新版本 |

653| `multiple` | 否 | 對於 `string` 類型，允許字串陣列 |

654| `min` / `max` | 否 | `number` 類型的邊界 |

~~655~~

656除了 `sensitive` 欄位和 `multiple` 列表，每個啟用 plugin 的每個欄位也會在 `/config` 面板中顯示為一列。這些列需要 Claude Code v2.1.269 或更新版本。

~~657~~

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

~~659~~

660在 shell 中執行的欄位拒絕 `${user_config.*}`：將設定值替換到 shell 命令中會讓 shell 執行該值包含的任何內容，因此元件會失敗並出現[錯誤](/docs/zh-TW/errors#plugin-command-references-user-config)。每個被拒絕的欄位都有一個替代方式來傳遞值：

~~661~~

662| 被拒絕的欄位 | 如何傳遞值 |

663| :------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------- |

664| Shell 形式 hook 命令 | 使用[執行形式](/docs/zh-TW/hooks#exec-form-and-shell-form)搭配 `args`，或從 hook 的環境讀取 `CLAUDE_PLUGIN_OPTION_<KEY>` |

665| [Monitor](#monitors) 命令 | 從指令碼中的設定檔讀取值 |

666| MCP [`headersHelper`](/docs/zh-TW/mcp#use-dynamic-headers-for-custom-authentication) | 從指令碼中的設定檔讀取值 |

~~667~~

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

~~669~~

670非敏感值儲存在你的使用者 `settings.json` 中的 [`pluginConfigs`](/docs/zh-TW/settings-reference#pluginconfigs) 鍵下，作為 `pluginConfigs[<plugin-id>].options`。

~~671~~

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

~~673~~

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

~~675~~

676* **使用者設定**：`~/.claude/settings.json`，啟用時提示寫入的檔案

677* **`--settings`**：CLI 旗標或 SDK 內嵌設定

678* **受管設定**：[組織控制的原則](/docs/zh-TW/permissions#managed-settings)

~~679~~

680當多個來源設定相同的鍵時，受管設定優先，然後是 `--settings`，然後是使用者設定。你可以從此列表中移除的唯一來源是使用者設定：傳遞 [`--setting-sources`](/docs/zh-TW/cli-reference#cli-flags) 而不包含 `user`，Claude Code 會跳過它們。受管設定和 `--settings` 保持你傳遞的任何內容。SDK 的 [`settingSources`](/docs/zh-TW/agent-sdk/claude-code-features#what-settingsources-does-not-control) 選項設定相同的列表。

~~681~~

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

~~683~~

684<h4 id="limit-a-field-to-fixed-options">

685 將欄位限制為固定選項

686</h4>

~~687~~

688在 `userConfig` 欄位上設定 `options` 以讓使用者從固定列表中選擇其值。

~~689~~

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

~~691~~

692```json theme={null}

693{

694 "userConfig": {

695 "tone": {

696 "type": "string",

697 "title": "Tone",

698 "description": "Voice for generated replies",

699 "options": ["neutral", "warm", "formal"],

700 "default": "neutral"

701 }

702 }

703}

704```

~~705~~

706如果你在任何欄位上宣告 `options`，Claude Code v2.1.271 之前版本的使用者無法載入 plugin。

~~707~~

708當你在欄位上設定 `options` 時，遵循這些規則：

~~709~~

710* 將 `type` 設定為 `string`

711* 不要將 `multiple` 或 `sensitive` 設定為 `true`

712* 將 `default` 設定為其中一個選項

713* 如果你不設定 `default`，將 `required` 設定為 `true`

714* 列出至少一個選項，每個 1 到 64 個字元長

715* 不要以空格開始或結束選項

716* 不要在選項中使用控制字元、不可見字元、改變文字方向的字元或除了常規空格以外的空格

717* 不要列出相同的選項兩次，即使是不同的字母大小寫

~~718~~

719如果你違反任何這些規則，plugin 無法載入。執行 `claude plugin validate` 以查看哪個欄位違反了哪個規則。

~~720~~

721<h3 id="channels">

722 頻道

723</h3>

~~724~~

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

~~726~~

727```json theme={null}

728{

729 "channels": [

730 {

731 "server": "telegram",

732 "userConfig": {

733 "bot_token": {

734 "type": "string",

735 "title": "Bot token",

736 "description": "Telegram bot token",

737 "sensitive": true

738 },

739 "owner_id": {

740 "type": "string",

741 "title": "Owner ID",

742 "description": "Your Telegram user ID"

743 }

744 }

745 }

746 ]

747}

748```

~~749~~

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

~~751~~

752<h3 id="path-behavior-rules">

753 路徑行為規則

754</h3>

~~755~~

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

~~757~~

758* **取代預設**：`commands`、`agents`、`workflows`、`outputStyles`、`experimental.themes`、`experimental.monitors`。例如，當 manifest 指定 `commands` 時，預設 `commands/` 目錄不會被掃描。要保留預設並新增更多，明確列出它：`"commands": ["./commands/", "./extras/"]`

759* **新增到預設**：`skills`。預設 `skills/` 目錄始終被掃描，`skills` 中列出的目錄與它一起載入。例外：對於[其 `source` 解析為 marketplace 根目錄的 marketplace 項目](/docs/zh-TW/plugin-marketplaces#advanced-plugin-entries)，宣告特定子目錄會取代預設 `skills/` 掃描

760* **自己的合併規則**：[hooks](#hooks)、[MCP 伺服器](#mcp-servers) 和 [LSP 伺服器](#lsp-servers)。請參閱每個部分以了解多個來源如何組合

~~761~~

762當 plugin 同時具有預設資料夾和匹配的 manifest 鍵時，Claude Code 會在 `claude plugin list` 和 `/plugin` 詳細檢視中警告被忽略的資料夾。plugin 仍然使用 manifest 路徑載入。當 manifest 鍵指向預設資料夾時，Claude Code 不會發出警告，例如 `"commands": ["./commands/deploy.md"]`，因為該路徑明確命名了資料夾。

~~763~~

764對於所有路徑欄位：

~~765~~

766* 所有路徑必須相對於 plugin 根目錄並以 `./` 開頭，除了 `skills` 欄位也接受 `"."`

767 * `"."` 和 `"./"` 都表示 plugin 根目錄本身

768 * 在 v2.1.221 之前，`"."` 無法通過 manifest 驗證，plugin 無法載入，因此使用 `"./"` 以支援較早版本

769* 來自自訂路徑的元件使用相同的命名和命名空間規則，除了 agent 檔案。請參閱 [Agents](#agents) 以了解 agent 名稱如何運作

770* 多個路徑可以指定為陣列

771* skill 路徑可以指向直接包含 `SKILL.md` 的目錄，例如 `"skills": ["."]` 用於 plugin 根目錄

772 * Claude Code 從 `SKILL.md` 中的 frontmatter `name` 欄位取得 skill 的呼叫名稱，因此無論安裝目錄名稱如何，名稱保持穩定

773 * 如果 frontmatter 中未設定 `name`，Claude Code 會回退到目錄基名

~~774~~

775具有根目錄中的 `SKILL.md`、沒有 `skills/` 子目錄且沒有 `skills` manifest 欄位的 plugin 會自動載入為單一 skill plugin。對於此佈局，你不需要在 `plugin.json` 中設定 `"skills": ["./"]`。

~~776~~

777**路徑範例**：

~~778~~

779```json theme={null}

780{

781 "commands": [

782 "./specialized/deploy.md",

783 "./utilities/batch-process.md"

784 ],

785 "agents": [

786 "./custom-agents/reviewer.md",

787 "./custom-agents/tester.md"

788 ]

789}

790```

~~791~~

792<h3 id="environment-variables">

793 環境變數

794</h3>

~~795~~

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

~~797~~

798| 變數 | 解析為 | 用途 |

799| :---------------------- | :--------------------------------------------------------- | :------------------------------------------------ |

800| `${CLAUDE_PLUGIN_ROOT}` | plugin 安裝目錄的絕對路徑 | 與 plugin 捆綁的指令碼、二進位檔案和設定檔 |

801| `${CLAUDE_PLUGIN_DATA}` | [持久目錄](#persistent-data-directory)，在首次參考時建立，在 plugin 更新中存活 | 已安裝的依賴項，例如 `node_modules` 或 Python 虛擬環境、生成的程式碼和快取 |

802| `${CLAUDE_PROJECT_DIR}` | 專案根目錄 | 專案本地指令碼和設定檔 |

~~803~~

804所有三個都匯出為環境變數到 hook 程序和 MCP 及 LSP 伺服器子程序。它們不存在於 Claude 通過 Bash 工具執行的命令環境中，無論是在主工作階段還是在子 agent 中。在 plugin 內容中，寫入佔位符，Claude Code 在載入內容時內嵌替換路徑。哪些欄位內嵌替換它們取決於 plugin 元件：

~~805~~

806| Plugin 元件 | 佔位符解析的欄位 |

807| :------------------------ | :--------------------------------------- |

808| Skill 和 agent 內容 | 佔位符出現的任何地方 |

809| Hook 和監視器命令 | 佔位符出現的任何地方 |

810| MCP `stdio` 伺服器 | `command`、`args`、`env` |

811| MCP `http`、`sse`、`ws` 伺服器 | `url`、`headers`、`headersHelper` |

812| LSP 伺服器 | `command`、`args`、`env`、`workspaceFolder` |

~~813~~

814在 hook 命令中，使用[執行形式](/docs/zh-TW/hooks#exec-form-and-shell-form)搭配 `args`，以便每個路徑作為一個引數傳遞，不需要引號。在 shell 形式 hook 和監視器命令中，用雙引號包裝變數，如 `"${CLAUDE_PROJECT_DIR}/scripts/server.sh"`。此 shell 形式 hook 執行與 plugin 捆綁的指令碼：

~~815~~

816```json theme={null}

817{

818 "hooks": {

819 "PostToolUse": [

820 {

821 "hooks": [

822 {

823 "type": "command",

824 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/process.sh"

825 }

826 ]

827 }

828 ]

829 }

830}

831```

~~832~~

833對於複製的 plugin，`${CLAUDE_PLUGIN_ROOT}` 在 plugin 更新時變更。前一個版本的目錄在更新後的寬限期內保留在磁碟上，但將其視為暫時的，不要在那裡寫入狀態。對於從本地目錄 marketplace 就地載入的 plugin，變數指向穩定的來源目錄。請參閱 [plugin 快取](#plugin-caching-and-file-resolution)以了解哪些 plugin 被複製以及清理語義。

~~834~~

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

~~836~~

837對於具有 `command` source 的 plugin，Claude Code [可以重新載入 plugin 本身](/docs/zh-TW/plugin-marketplaces#when-claude-code-re-runs-the-command)。

~~838~~

839MCP 伺服器也可以呼叫 `roots/list` 請求以在執行時讀取工作階段的工作目錄。請參閱[`roots/list` 返回的內容以及 Claude Code 何時通知伺服器變更](/docs/zh-TW/mcp#option-3-add-a-local-stdio-server)。

~~840~~

841<h4 id="persistent-data-directory">

842 持久資料目錄

843</h4>

~~844~~

845`${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/`。

~~846~~

847常見用途是一次安裝語言依賴項並在工作階段和 plugin 更新中重複使用它們。將其用於 Python 依賴項、使用 Yarn 或 pnpm 鎖定的依賴項以及其生命週期指令碼必須執行的套件。對於 marketplace 安裝的 plugin，你可能根本不需要它：Claude Code 在快取 plugin 時自動安裝符合條件的 [Node.js 套件依賴項](#node-js-package-dependencies)。

~~848~~

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

~~850~~

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

~~852~~

853```json theme={null}

854{

855 "hooks": {

856 "SessionStart": [

857 {

858 "hooks": [

859 {

860 "type": "command",

861 "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\""

862 }

863 ]

864 }

865 ]

866 }

867}

868```

~~869~~

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

~~871~~

872然後在 `${CLAUDE_PLUGIN_ROOT}` 中捆綁的指令碼可以針對持久的 `node_modules` 執行：

~~873~~

874```json theme={null}

875{

876 "mcpServers": {

877 "routines": {

878 "command": "node",

879 "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],

880 "env": {

881 "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"

882 }

883 }

884 }

885}

886```

~~887~~

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

~~889~~

890***

~~891~~

892<h2 id="plugin-caching-and-file-resolution">

893 Plugin 快取和檔案解析

894</h2>

~~895~~

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

~~897~~

898* 透過 `claude --plugin-dir` 或 `claude --plugin-url`，在工作階段期間使用。

899* 透過市集安裝，供未來的工作階段使用。

900* 透過您的 claude.ai 帳戶，[同步](#synced-plugins)到 `~/.claude/plugins/synced/`。

~~901~~

902基於安全性和驗證目的，Claude Code 會將\_市集\_ plugin 複製到使用者的本機 **plugin 快取**（`~/.claude/plugins/cache`），除非 plugin 就地載入。[連結模式中的 `command` 來源](/docs/zh-TW/plugin-marketplaces#copy-mode-and-link-mode)會透過快取項目中的連結就地載入。[市集中的相對路徑來源](/docs/zh-TW/plugin-marketplaces#relative-paths)從本機目錄新增的市集會就地從市集資料夾載入。

~~903~~

904對於從本機目錄市集就地載入的 plugin，您對來源目錄的編輯會在下一個工作階段開始或 `/reload-plugins` 時生效。您不需要版本更新。Plugin 的 hook 程序和 MCP 和 LSP 伺服器會收到指向來源目錄的 `CLAUDE_PLUGIN_ROOT`。Claude Code 不會將 plugin 的 [Node.js 套件相依性](#node-js-package-dependencies)安裝到來源目錄中。請自行安裝它們，或從 hook 安裝到[持久資料目錄](#persistent-data-directory)。

~~905~~

906對於複製的 plugin，每個已安裝的版本都是快取中的單獨目錄，按市集和 plugin 分組，並以已解析的版本命名，具有自己的 plugin 檔案副本和 [Node.js 套件相依性](#node-js-package-dependencies)。從[發行標籤](/docs/zh-TW/plugin-dependencies#tag-plugin-releases-for-version-resolution)解析的相依性會取得帶有 commit-SHA 後綴的目錄名稱。

~~907~~

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

~~909~~

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

~~911~~

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

~~913~~

914<h3 id="node-js-package-dependencies">

915 Node.js 套件相依性

916</h3>

~~917~~

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

~~919~~

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

~~921~~

922| 鎖定檔案 | 命令 |

923| :------------------------------------------ | :----------------------------------------------- |

924| `bun.lock` 或 `bun.lockb` | `bun install --frozen-lockfile --ignore-scripts` |

925| `npm-shrinkwrap.json` 或 `package-lock.json` | `npm ci --ignore-scripts` |

~~926~~

927如果 plugin 包含多個這些鎖定檔案，Claude Code 會使用第一個符合項，按順序檢查：`bun.lock`、`bun.lockb`、`npm-shrinkwrap.json`、`package-lock.json`。

~~928~~

929Claude Code 在兩種情況下會跳過安裝，各有其自己的修正方式：

~~930~~

931* 如果您的 plugin 只附帶 `yarn.lock` 或 `pnpm-lock.yaml`，請將其替換為 npm 鎖定檔案。

932* 如果 `bunfig.toml` 位於 bun 鎖定檔案旁邊，請移除 `bunfig.toml`，或將 bun 鎖定檔案替換為 npm 鎖定檔案。

~~933~~

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

~~935~~

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

~~937~~

938* **凍結解析：** Bun 和 npm 安裝鎖定檔案精確指定的內容，當 `package.json` 和鎖定檔案不一致時，會失敗而不是重新解析版本。

939* **無生命週期指令碼：** `--ignore-scripts` 防止 `preinstall`、`install` 和 `postinstall` 指令碼執行，因此在這些指令碼中建置原生模組的相依性會下載但在此安裝期間不會編譯。

940* **60 秒逾時：** Claude Code 會停止執行時間超過此時間的安裝，並將其視為失敗。

~~941~~

942Claude Code 在此相依性安裝之前會提取 npm 來源 plugin，並且套件本身的任何安裝指令碼都不會在提取期間執行。請參閱 [npm 套件](/docs/zh-TW/plugin-marketplaces#npm-packages)。

~~943~~

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

~~945~~

946您無法關閉自動安裝；沒有設定或環境變數可以停用它。在受限網路中，請參閱[網路存取需求](/docs/zh-TW/network-config#network-access-requirements)以了解要允許的主機。

~~947~~

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

~~949~~

950<h3 id="path-traversal-limitations">

951 路徑遍歷限制

952</h3>

~~953~~

954Claude Code 不允許 plugin 參考其自己目錄外的檔案。它會拒絕解析到 plugin 根目錄外的元件路徑，無論路徑是在 `plugin.json` 中宣告還是在[市集項目](/docs/zh-TW/plugin-marketplaces#plugin-entries)中宣告。這涵蓋指向 plugin 外部的路徑（如寫入的），例如 `../shared-utils`，以及導向 plugin 外部的符號連結，除了[市集內的連結](#share-files-within-a-marketplace-with-symlinks)。

~~955~~

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

~~957~~

958當 Claude Code 拒絕路徑時，它會報告 [`path escapes plugin directory`](/docs/zh-TW/errors#path-escapes-plugin-directory) 錯誤，並在沒有該元件的情況下載入 plugin。

~~959~~

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

~~961~~

962<h3 id="share-files-within-a-marketplace-with-symlinks">

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

964</h3>

~~965~~

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

~~967~~

968* **在 plugin 自己的目錄內：** 符號連結在快取中保留為相對符號連結，因此在執行時它會繼續解析到複製的目標。

969* **在同一市集內的其他位置：** 符號連結被取消參考。目標的內容被複製到快取中以取代它。這讓中繼 plugin 的 `skills/` 目錄可以連結到市集中其他 plugin 定義的技能。

970* **在市集外：** 符號連結因安全性而被跳過。這防止 plugin 將任意主機檔案（例如系統路徑）拉入快取。

~~971~~

972對於使用 `--plugin-dir` 安裝的 plugin、來自本機路徑的 plugin，或來自複製模式中的 [`command` 來源](/docs/zh-TW/plugin-marketplaces#copy-mode-and-link-mode)的 plugin，只有解析到 plugin 自己目錄內的符號連結會被保留。所有其他連結都會被跳過。

~~973~~

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

~~975~~

976```bash theme={null}

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

978```

~~979~~

980***

~~981~~

982<h2 id="plugin-directory-structure">

983 Plugin 目錄結構

984</h2>

~~985~~

986<h3 id="standard-plugin-layout">

987 標準 plugin 配置

988</h3>

~~989~~

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

~~991~~

992```text theme={null}

993enterprise-plugin/

994├── .claude-plugin/ # 中繼資料目錄（選用）

995│ └── plugin.json # plugin 資訊清單

996├── skills/ # Skills

997│ ├── code-reviewer/

998│ │ └── SKILL.md

999│ └── pdf-processor/

1000│ ├── SKILL.md

1001│ └── scripts/

1002├── commands/ # Skills 作為平面 .md 檔案

1003│ ├── status.md

1004│ └── logs.md

1005├── agents/ # Subagent 定義

1006│ ├── security-reviewer.md

1007│ ├── performance-tester.md

1008│ ├── compliance-checker.md

1009│ └── review/ # 此處的 Agents 載入為 enterprise-plugin:review:<name>

1010│ └── accessibility.md

1011├── workflows/ # Workflow 指令碼

1012│ └── release-audit.js

1013├── output-styles/ # 輸出樣式定義

1014│ └── terse.md

1015├── themes/ # 色彩主題定義

1016│ └── dracula.json

1017├── monitors/ # 背景監視器設定

1018│ └── monitors.json

1019├── hooks/ # Hook 設定

1020│ ├── hooks.json # 主要 hook 設定

1021│ └── security-hooks.json # 其他 hooks

1022├── bin/ # Plugin 可執行檔新增至 PATH

1023│ └── my-tool # 在 Bash tool 中可作為裸命令叫用

1024├── settings.json # Plugin 的預設設定

1025├── .mcp.json # MCP 伺服器定義

1026├── .lsp.json # LSP 伺服器設定

1027├── scripts/ # Hook 和公用程式指令碼

1028│ ├── security-scan.sh

1029│ ├── format-code.py

1030│ └── deploy.js

1031├── LICENSE # 授權檔案

1032└── CHANGELOG.md # 版本歷史

1033```

~~1034~~

1035<Warning>

1036 `.claude-plugin/` 目錄包含 `plugin.json` 檔案。所有其他目錄（commands/、agents/、skills/、workflows/、output-styles/、themes/、monitors/、hooks/）必須位於 plugin 根目錄，而不是在 `.claude-plugin/` 內。

1037</Warning>

~~1038~~

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

~~1040~~

1041<h3 id="file-locations-reference">

1042 檔案位置參考

1043</h3>

~~1044~~

1045| 元件 | 預設位置 | 用途 |

1046| :------------ | :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1047| **資訊清單** | `.claude-plugin/plugin.json` | Plugin 中繼資料和設定（選用） |

1048| **Skills** | `skills/` | 具有 `<name>/SKILL.md` 結構的 Skills |

1049| **Commands** | `commands/` | Skills 作為平面 Markdown 檔案。新 plugins 請使用 `skills/` |

1050| **Agents** | `agents/` | Subagent Markdown 檔案。子資料夾是 [agent 名稱](#agents) 的一部分 |

1051| **Workflows** | `workflows/` | [Workflow](/docs/zh-TW/workflows) 指令碼檔案 |

1052| **輸出樣式** | `output-styles/` | 輸出樣式定義 |

1053| **主題** | `themes/` | 色彩主題定義 |

1054| **Hooks** | `hooks/hooks.json` | Hook 設定 |

1055| **MCP 伺服器** | `.mcp.json` | MCP 伺服器定義 |

1056| **LSP 伺服器** | `.lsp.json` | 語言伺服器設定 |

1057| **監視器** | `monitors/monitors.json` | 背景監視器設定 |

1058| **可執行檔** | `bin/` | 新增至 Bash tool 的 `PATH` 的可執行檔，在 plugin 啟用時可作為裸命令叫用。您無法在透過 claude.ai 組織設定 [分發的 plugin 中包含此目錄](/docs/zh-TW/plugin-marketplaces#keep-executables-out-of-the-top-level-bin-directory) |

1059| **設定** | `settings.json` | Plugin 啟用時套用的預設設定。僅支援 [`agent`](/docs/zh-TW/sub-agents) 和 [`subagentStatusLine`](/docs/zh-TW/statusline#subagent-status-lines) 鍵 |

~~1060~~

1061***

~~1062~~

1063<h2 id="cli-commands-reference">

1064 CLI 命令參考

1065</h2>

~~1066~~

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

~~1068~~

1069<h3 id="plugin-init">

1070 plugin init

1071</h3>

~~1072~~

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

~~1074~~

1075請參閱[技能目錄外掛程式](#skills-directory-plugins)以了解範圍和信任要求。

~~1076~~

1077```bash theme={null}

1078claude plugin init <name> [options]

1079```

~~1080~~

1081該命令接受這些引數：

~~1082~~

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

~~1084~~

1085該命令接受這些選項：

~~1086~~

1087| 選項 | 說明 | 預設值 |

1088| :----------------------- | :------------------------------------------------------------------------------ | :---------------------- |

1089| `--description <text>` | 資訊清單說明 | |

1090| `--author <name>` | 作者名稱 | `git config user.name` |

1091| `--author-email <email>` | 作者電子郵件 | `git config user.email` |

1092| `--with <components...>` | 同時建立元件資料夾的框架。有效值：`skills`、`agents`、`hooks`、`mcp`、`lsp`、`output-style`、`channel` | |

1093| `-f, --force` | 覆寫目標處現有的 `.claude-plugin/` | |

1094| `-h, --help` | 顯示命令說明 | |

~~1095~~

1096`claude plugin new` 是此命令的別名。

~~1097~~

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

~~1099~~

1100| 元件 | 建立的內容 |

1101| :------------- | :------------------------------------------------------------------------------------------ |

1102| `skills` | 一個額外的命名空間 `<name>:example` 技能，與預設技能並列 |

1103| `agents` | 一個 `agents/` 子代理定義 |

1104| `hooks` | 一個 `hooks/hooks.json`，包含範例事件處理程式 |

1105| `mcp` | 一個 `.mcp.json`，包含 HTTP 和 stdio 伺服器範例 |

1106| `lsp` | 一個 `.lsp.json` 語言伺服器範例 |

1107| `output-style` | 一個 `output-styles/<name>.md`，在外掛程式啟用時自動套用 |

1108| `channel` | 一個基於 MCP 的[頻道](/docs/zh-TW/channels)：一個 stdio 伺服器 (`server.ts`)、其 `.mcp.json` 和一個 `package.json` |

~~1109~~

1110建立框架的外掛程式使用 `@skills-dir` 來源，而不是市集。管理員可以使用 `strictKnownMarketplaces` 或在[受管設定](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions)中新增 `{"source": "skills-dir"}` 至 `blockedMarketplaces` 來封鎖此來源。當被封鎖時，`plugin init` 會在寫入前失敗。

~~1111~~

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

~~1113~~

1114```bash theme={null}

1115# 建立最小外掛程式的框架

1116claude plugin init my-helper

~~1117~~

1118# 使用技能和掛鉤資料夾建立框架

1119claude plugin init my-helper --with skills hooks

~~1120~~

1121# 覆寫現有框架

1122claude plugin init my-helper --force

1123```

~~1124~~

1125<h3 id="plugin-install">

1126 plugin install

1127</h3>

~~1128~~

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

~~1130~~

1131```bash theme={null}

1132claude plugin install <plugin> [options]

1133```

~~1134~~

1135該命令接受這些引數：

~~1136~~

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

~~1138~~

1139該命令接受這些選項：

~~1140~~

1141| 選項 | 說明 | 預設值 |

1142| :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |

1143| `-s, --scope <scope>` | 安裝範圍：`user`、`project` 或 `local` | `user` |

1144| `--config <key=value>` | 設定外掛程式資訊清單中宣告的 [`userConfig`](#user-configuration) 選項。重複此旗標以設定多個選項 | |

1145| `-y, --yes` | 接受外掛程式市集宣告的命令，無需確認提示：產生具有 [`command` 來源](/docs/zh-TW/plugin-marketplaces#command-sources)的外掛程式的命令，或驗證封存下載的 [`headersHelper`](/docs/zh-TW/plugin-marketplaces#authenticate-archive-downloads)。接受 `headersHelper` 需要 Claude Code v2.1.238 或更新版本。Claude Code 仍會先列印命令。當 stdin 或 stdout 不是 TTY 時為必需，除非您傳遞 `--accept-command`。在 Claude Code 工作階段內無效，因此請從您自己的終端執行命令 | |

1146| `--accept-command <sha256>` | 接受市集宣告的命令，其 `sha256` 先前的 [`--json` 執行](#plugin-json-result)在 `shownCommand` 中報告，以取代 `-y`。接受計數適用於完全相同的命令、外掛程式和市集目錄。如果自命令顯示以來任何一個已變更，包括透過執行本身的市集重新整理，Claude Code 不會接受摘要並再次顯示命令。無法與 `-y` 結合。在 Claude Code 工作階段內無效，因此請從您自己的終端執行命令。需要 Claude Code v2.1.271 或更新版本 | |

1147| `--json` | 將結果列印為 stdout 最後一行的一個 JSON 物件，供指令碼使用。請參閱 [JSON 結果格式](#plugin-json-result)。需要 Claude Code v2.1.268 或更新版本 | |

1148| `-h, --help` | 顯示命令說明 | |

~~1149~~

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

~~1151~~

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

~~1153~~

1154* `command`：執行的子命令，例如 `install`

1155* `outcome`：`ok` 或 `failed`

1156* `message`：結果的人類可讀說明

~~1157~~

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

~~1159~~

1160當執行顯示市集宣告的命令且不執行它時，`failed` 結果也會攜帶一個 `shownCommand` 物件，其欄位包括顯示的命令、它所屬的外掛程式和命令的 `sha256`。若要接受完全相同的命令，請使用該 `sha256` 作為 `--accept-command` 重新執行。需要 Claude Code v2.1.271 或更新版本。

~~1161~~

1162如果 `shownCommand.acceptCommandMatched` 是 `false`，您傳遞的摘要與現在顯示的命令不符。在傳遞其 `sha256` 之前，向某人顯示該命令。

~~1163~~

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

~~1165~~

1166```bash theme={null}

1167# 安裝至使用者範圍（預設）

1168claude plugin install formatter@my-marketplace

~~1169~~

1170# 安裝至專案範圍（與團隊共享）

1171claude plugin install formatter@my-marketplace --scope project

~~1172~~

1173# 安裝至本機範圍（不與團隊共享）

1174claude plugin install formatter@my-marketplace --scope local

1175```

~~1176~~

1177<h3 id="plugin-uninstall">

1178 plugin uninstall

1179</h3>

~~1180~~

1181移除已安裝的外掛程式。

~~1182~~

1183```bash theme={null}

1184claude plugin uninstall <plugin> [options]

1185```

~~1186~~

1187該命令接受這些引數：

~~1188~~

1189* `<plugin>`：外掛程式名稱或 `plugin-name@marketplace-name`

~~1190~~

1191該命令接受這些選項：

~~1192~~

1193| 選項 | 說明 | 預設值 |

1194| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------- | :----- |

1195| `-s, --scope <scope>` | 從範圍解除安裝：`user`、`project` 或 `local` | `user` |

1196| `--keep-data` | 保留外掛程式的[持久資料目錄](#persistent-data-directory) | |

1197| `--prune` | 同時移除其他外掛程式不再需要的自動安裝相依性。請參閱 [plugin prune](#plugin-prune) | |

1198| `-y, --yes` | 跳過 `--prune` 確認提示。當 stdin 或 stdout 不是 TTY 時為必需 | |

1199| `--json` | 將結果列印為 stdout 最後一行的一個 JSON 物件，格式與 [`plugin install --json`](#plugin-json-result) 相同。無法與 `--prune` 結合。需要 Claude Code v2.1.268 或更新版本 | |

1200| `-h, --help` | 顯示命令說明 | |

~~1201~~

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

~~1203~~

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

~~1205~~

1206<Note>

1207 當來自不同市集的已安裝外掛程式共享名稱時，`plugin-name@marketplace-name` 形式只會解除安裝來自指定市集的外掛程式。在 v2.1.212 之前，合格形式可能會符合並解除安裝來自不同市集的同名外掛程式。

1208</Note>

~~1209~~

1210<h3 id="plugin-prune">

1211 plugin prune

1212</h3>

~~1213~~

1214移除不再由任何已安裝外掛程式需要的自動安裝外掛程式相依性。Claude Code 為滿足另一個外掛程式的 [`dependencies`](/docs/zh-TW/plugin-dependencies) 欄位而拉入的相依性會被移除；您直接安裝的外掛程式永遠不會被觸及。

~~1215~~

1216```bash theme={null}

1217claude plugin prune [options]

1218```

~~1219~~

1220該命令接受這些選項：

~~1221~~

1222| 選項 | 說明 | 預設值 |

1223| :-------------------- | :---------------------------------- | :----- |

1224| `-s, --scope <scope>` | 在範圍進行清理：`user`、`project` 或 `local` | `user` |

1225| `--dry-run` | 列出將被移除的內容，但不實際移除 | |

1226| `-y, --yes` | 跳過確認提示。當 stdin 或 stdout 不是 TTY 時為必需 | |

1227| `-h, --help` | 顯示命令說明 | |

~~1228~~

1229`claude plugin autoremove` 是此命令的別名。

~~1230~~

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

~~1232~~

1233<h3 id="plugin-enable">

1234 plugin enable

1235</h3>

~~1236~~

1237啟用已停用的外掛程式。當目標從市集安裝並宣告[相依性](/docs/zh-TW/plugin-dependencies)時，Claude Code 會在相同範圍內以遞移方式啟用它們。該命令在[啟用或停用具有相依性的外掛程式](/docs/zh-TW/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies)列出的條件下失敗。

~~1238~~

1239```bash theme={null}

1240claude plugin enable <plugin> [options]

1241```

~~1242~~

1243該命令接受這些引數：

~~1244~~

1245* `<plugin>`：外掛程式名稱、`plugin-name@marketplace-name` 或 `plugin-name@synced` 用於[從 claude.ai 同步的外掛程式](#synced-plugins)

~~1246~~

1247該命令接受這些選項：

~~1248~~

1249| 選項 | 說明 | 預設值 |

1250| :-------------------- | :---------------------------------------------------------------------------------------------------------------- | :--- |

1251| `-s, --scope <scope>` | 要啟用的範圍：`user`、`project` 或 `local`。省略時，Claude Code 會偵測安裝外掛程式的範圍 | 自動偵測 |

1252| `--json` | 將結果列印為 stdout 最後一行的一個 JSON 物件，格式與 [`plugin install --json`](#plugin-json-result) 相同。需要 Claude Code v2.1.268 或更新版本 | |

1253| `-h, --help` | 顯示命令說明 | |

~~1254~~

1255<h3 id="plugin-disable">

1256 plugin disable

1257</h3>

~~1258~~

1259停用外掛程式而不解除安裝它。

~~1260~~

1261當目標從市集安裝時，如果另一個已啟用的外掛程式[依賴](/docs/zh-TW/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies)它，該命令會失敗。錯誤訊息包含一個鏈式命令，可先停用每個依賴它的外掛程式。

~~1262~~

1263對於您的組織需要的[同步外掛程式](#synced-plugins)，該命令會失敗且不會儲存任何內容。

~~1264~~

1265```bash theme={null}

1266claude plugin disable [plugin] [options]

1267```

~~1268~~

1269該命令接受這些引數：

~~1270~~

1271* `[plugin]`：外掛程式名稱、`plugin-name@marketplace-name` 或 `plugin-name@synced` 用於[從 claude.ai 同步的外掛程式](#synced-plugins)。使用 `--all` 時為選用。

~~1272~~

1273該命令接受這些選項：

~~1274~~

1275| 選項 | 說明 | 預設值 |

1276| :-------------------- | :---------------------------------------------------------------------------------------------------------------- | :--- |

1277| `-a, --all` | 停用所有已啟用的外掛程式。無法與 `--scope` 結合 | |

1278| `-s, --scope <scope>` | 要停用的範圍：`user`、`project` 或 `local`。省略時，Claude Code 會偵測安裝外掛程式的範圍 | 自動偵測 |

1279| `--json` | 將結果列印為 stdout 最後一行的一個 JSON 物件，格式與 [`plugin install --json`](#plugin-json-result) 相同。需要 Claude Code v2.1.268 或更新版本 | |

1280| `-h, --help` | 顯示命令說明 | |

~~1281~~

1282<h3 id="plugin-update">

1283 plugin update

1284</h3>

~~1285~~

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

~~1287~~

1288```bash theme={null}

1289claude plugin update <plugin> [options]

1290```

~~1291~~

1292該命令接受這些引數：

~~1293~~

1294* `<plugin>`：外掛程式名稱或 `plugin-name@marketplace-name`

~~1295~~

1296該命令接受這些選項：

~~1297~~

1298| 選項 | 說明 | 預設值 |

1299| :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |

1300| `-s, --scope <scope>` | 要更新的範圍：`user`、`project`、`local` 或 `managed` | `user` |

1301| `-y, --yes` | 接受外掛程式市集宣告的命令，無需確認提示：產生具有 [`command` 來源](/docs/zh-TW/plugin-marketplaces#command-sources)的外掛程式的命令，或驗證封存下載的 [`headersHelper`](/docs/zh-TW/plugin-marketplaces#authenticate-archive-downloads)。接受 `headersHelper` 需要 Claude Code v2.1.238 或更新版本。Claude Code 仍會先列印命令。當 stdin 或 stdout 不是 TTY 時為必需，除非您傳遞 `--accept-command`。在 Claude Code 工作階段內無效，因此請從您自己的終端執行命令 | |

1302| `--accept-command <sha256>` | 接受市集宣告的命令，其 `sha256` 先前的 [`--json` 執行](#plugin-json-result)在 `shownCommand` 中報告，以取代 `-y`。接受計數適用於完全相同的命令、外掛程式和市集目錄。如果自命令顯示以來任何一個已變更，包括透過執行本身的市集重新整理，Claude Code 不會接受摘要並再次顯示命令。無法與 `-y` 結合。在 Claude Code 工作階段內無效，因此請從您自己的終端執行命令。需要 Claude Code v2.1.271 或更新版本 | |

1303| `--json` | 將結果列印為 stdout 最後一行的一個 JSON 物件，格式與 [`plugin install --json`](#plugin-json-result) 相同。需要 Claude Code v2.1.268 或更新版本 | |

1304| `-h, --help` | 顯示命令說明 | |

~~1305~~

1306<Note>

1307 Claude Code 根據您已安裝的外掛程式解析裸外掛程式名稱。當來自不同市集的已安裝外掛程式共享名稱時，Claude Code 會拒絕更新並列出要執行的合格 `plugin-name@marketplace-name` 命令。在 v2.1.246 之前，Claude Code 只接受合格形式，並將裸名稱拒絕為未找到。

1308</Note>

~~1309~~

1310***

~~1311~~

1312<h3 id="plugin-list">

1313 plugin list

1314</h3>

~~1315~~

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

~~1317~~

1318```bash theme={null}

1319claude plugin list [options]

1320```

~~1321~~

1322該命令接受這些選項：

~~1323~~

1324| 選項 | 說明 | 預設值 |

1325| :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-- |

1326| `--json` | 輸出為 JSON。具有載入問題或編寫警告的外掛程式列會攜帶 `errors` 或 `notes` 字串陣列。在 Claude Code v2.1.268 或更新版本上，平行的 `errorDetails` 和 `noteDetails` 陣列會提供每個項目的診斷 `type` 和它所指的名稱，例如外掛程式、市集、伺服器或檔案 | |

1327| `--available` | 包含市集中的可用外掛程式。需要 `--json` | |

1328| `-h, --help` | 顯示命令說明 | |

~~1329~~

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

~~1331~~

1332* 從技能目錄載入的外掛程式會在 `/plugin` 介面和 `claude plugin list` 中出現，但不會在內嵌 `/plugin list` 輸出中出現。

1333* [從 claude.ai 同步的外掛程式](#synced-plugins)會在 Claude Code v2.1.239 或更新版本上的 `claude plugin list` 中出現，並在 `/plugin` 介面中出現，但不會在內嵌 `/plugin list` 輸出中出現。

1334* 使用 `--plugin-dir` 或 `--plugin-url` 為工作階段載入的外掛程式會在 `/plugin` 介面中出現，並且在相同旗標位於子命令前時才會在 `claude plugin list` 中出現，如 `claude --plugin-dir <dir> plugin list`。只有旗標名稱會指出它們的位置，因此裸 `claude plugin list` 無法找到它們，不同於同步外掛程式和技能目錄外掛程式，Claude Code 會掃描其固定目錄。

~~1335~~

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

~~1337~~

1338<h3 id="plugin-details">

1339 plugin details

1340</h3>

~~1341~~

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

~~1343~~

1344```bash theme={null}

1345claude plugin details <name>

1346```

~~1347~~

1348該命令接受這些引數：

~~1349~~

1350* `<name>`：外掛程式名稱或 `plugin-name@marketplace-name`

~~1351~~

1352該命令接受這些選項：

~~1353~~

1354| 選項 | 說明 | 預設值 |

1355| :----------- | :----- | :-- |

1356| `-h, --help` | 顯示命令說明 | |

~~1357~~

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

~~1359~~

1360* **Always-on：** 外掛程式的列表文字（例如技能說明、代理說明和命令名稱）無論任何元件是否觸發，都會新增至每個工作階段的權杖。

1361* **On-invoke：** 元件觸發時的成本。按元件顯示，而不是外掛程式總計，因為典型工作階段只會叫用元件的子集。

~~1362~~

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

~~1364~~

1365```

1366dependency-guard 1.2.0

1367 Dependency analysis for Claude Code sessions

1368 Source: dependency-guard@example-marketplace

~~1369~~

1370Component inventory

1371 Skills (2) scan-dependencies, review-changes

1372 Agents (0)

1373 Hooks (1) SessionStart (harness-only — no model context cost)

1374 MCP servers (0)

1375 LSP servers (0)

~~1376~~

1377Projected token cost

1378 Always-on: ~180 tok added to every session

~~1379~~

1380Per-component (rounded)

1381 component always-on on-invoke

1382 scan-dependencies ~100 ~2400

1383 review-changes ~80 ~1800

~~1384~~

1385 On-invoke cost is paid each time a skill or agent fires.

1386 Token counts are estimates and may differ from actual usage.

1387```

~~1388~~

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

~~1390~~

1391<h3 id="plugin-validate">

1392 plugin validate

1393</h3>

~~1394~~

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

~~1396~~

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

~~1398~~

1399```bash theme={null}

1400claude plugin validate <path> [options]

1401```

~~1402~~

1403該命令接受這些引數：

~~1404~~

1405* `<path>`：外掛程式目錄或市集目錄的路徑。請參閱[驗證沒有資訊清單的外掛程式或目錄](/docs/zh-TW/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest)以了解外掛程式執行涵蓋的檔案。

~~1406~~

1407該命令接受這些選項：

~~1408~~

1409| 選項 | 說明 | 預設值 |

1410| :----------- | :---------------------------------------------------------------------- | :-- |

1411| `--strict` | 將警告視為錯誤，並在警告時退出 1。在 CI 中使用以捕捉執行時容許的問題，例如[無法識別的欄位](#unrecognized-fields) | |

1412| `--json` | 將驗證報告輸出為一個 JSON 物件，具有相同的退出代碼。需要 Claude Code v2.1.259 或更新版本 | |

1413| `-h, --help` | 顯示命令說明 | |

~~1414~~

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

~~1416~~

1417* `success`：退出代碼給出的相同判決

1418* `strict`：執行是否將警告視為錯誤

1419* `target`：Claude Code 驗證的已解析路徑

1420* `manifest`：資訊清單本身的結果，或 `null` 用於[沒有資訊清單的執行](/docs/zh-TW/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest)

1421* `contents`：按檔案結果，每個命名其 `file` 並攜帶 `errors`、`warnings` 和 `notes` 陣列

~~1422~~

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

~~1424~~

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

~~1426~~

1427<h3 id="plugin-eval">

1428 plugin eval

1429</h3>

~~1430~~

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

~~1432~~

1433```bash theme={null}

1434claude plugin eval [target] [options]

1435```

~~1436~~

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

~~1438~~

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

~~1440~~

1441| 選項 | 說明 | 預設值 |

1442| :------------------------- | :--------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------- |

1443| `--runs <n>` | 每個案例每個臂的執行次數 | 每個案例的 `runs`，否則 3 |

1444| `-j, --concurrency <n>` | 同時執行的代理工作階段，1 到 8。它們共享您的速率限制 | `1` |

1445| `--model <model>` | 受測代理的模型 | 每個案例的 `model`，否則 `ANTHROPIC_MODEL`（如果設定），否則 Claude Code 的預設值 |

1446| `--judge-model <model>` | `llm` 和 `baseline` 評分者的模型 | 一個小型快速模型 |

1447| `--ablation <mode>` | `none` 或 `with-without`。請參閱[與無外掛程式基線比較](/docs/zh-TW/plugin-evals#compare-against-a-no-plugin-baseline) | 當外掛程式解析時為 `with-without`，否則為 `none` |

1448| `--threshold <0..1>` | 如果任何案例評分低於此值，退出 1 | `1.0` |

1449| `--max-cost-usd <usd>` | 一旦支出達到此值，停止下一次執行，退出 2，並報告部分結果 | 無上限 |

1450| `--allow-tools <tools...>` | 授予超過唯讀集合的工具，例如 `Bash`、`Write`、`Edit` 或 `"mcp__plugin_<plugin>_<server>__*"`。請參閱[授予工具](/docs/zh-TW/plugin-evals#grant-tools) | |

1451| `--scaffold` | 執行每個案例的 [`scaffold_script`](/docs/zh-TW/plugin-evals#add-setup-or-history-with-case-yaml) | 關閉 |

1452| `--trust-plugin` | 跳過首次執行信任提示，用於 CI。請參閱[執行可以存取的內容](/docs/zh-TW/plugin-evals#security) | 關閉 |

1453| `--mocks <mode>` | `record` 或 `off`。請參閱[模擬 MCP 伺服器](/docs/zh-TW/plugin-evals#mock-mcp-servers) | `record` |

1454| `--eval-dir <dir>` | 保存案例的外掛程式下方的目錄 | 資訊清單的 `experimental.evals`，否則 `evals` |

1455| `--json [path]` | 將[結果文件](/docs/zh-TW/plugin-evals#json-result)列印至 stdout，或將其寫入 `.json` 路徑 | |

1456| `--no-publish` | 保持 HTML 報告本機 | |

1457| `-h, --help` | 顯示命令說明 | |

~~1458~~

1459當每個案例都符合閾值時，命令退出 0，在失敗案例、載入錯誤或不受信任的外掛程式目錄時退出 1，在部分執行時退出 2，中斷時退出 130，終止時退出 143。請參閱[在 CI 中執行評估](/docs/zh-TW/plugin-evals#run-evals-in-ci)。

~~1460~~

1461<h3 id="plugin-eval-init">

1462 plugin eval init

1463</h3>

~~1464~~

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

~~1466~~

1467```bash theme={null}

1468claude plugin eval init [name] [options]

1469```

~~1470~~

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

~~1472~~

1473| 選項 | 說明 | 預設值 |

1474| :------------------ | :---------------------------------------------------- | :------------------------------------ |

1475| `--bare` | 改為為 `<name>` 寫入空白 `prompt.md` 和 `graders/criteria.md` | |

1476| `-i, --interactive` | 需要訪談。沒有終端時失敗，而不是寫入範本 | |

1477| `--eval-dir <dir>` | 目前目錄下方寫入案例的目錄 | 資訊清單的 `experimental.evals`，否則 `evals` |

1478| `-h, --help` | 顯示命令說明 | |

~~1479~~

1480<h3 id="plugin-tag">

1481 plugin tag

1482</h3>

~~1483~~

1484為外掛程式建立發行 git 標籤。根據預設，該命令會標籤目前目錄中的外掛程式；傳遞路徑以標籤其他位置的外掛程式。請參閱[標籤外掛程式發行](/docs/zh-TW/plugin-dependencies#tag-plugin-releases-for-version-resolution)。

~~1485~~

1486```bash theme={null}

1487claude plugin tag [path] [options]

1488```

~~1489~~

1490該命令接受這些引數：

~~1491~~

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

~~1493~~

1494該命令接受這些選項：

~~1495~~

1496| 選項 | 說明 | 預設值 |

1497| :-------------------- | :----------------------- | :------- |

1498| `--push` | 建立標籤後將其推送至遠端 | |

1499| `--dry-run` | 列印將被標籤的內容，但不建立標籤 | |

1500| `-f, --force` | 即使工作樹髒污或標籤已存在，也建立標籤 | |

1501| `-m, --message <msg>` | 標籤註解訊息。使用 `%s` 作為版本的預留位置 | |

1502| `--remote <name>` | 使用 `--push` 推送至的遠端 | `origin` |

1503| `-h, --help` | 顯示命令說明 | |

~~1504~~

1505***

~~1506~~

1507<h2 id="debugging-and-development-tools">

1508 除錯和開發工具

1509</h2>

~~1510~~

1511<h3 id="debugging-commands">

1512 除錯命令

1513</h3>

~~1514~~

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

~~1516~~

1517這會顯示：

~~1518~~

1519* 正在載入哪些外掛程式

1520* 外掛程式清單中的任何錯誤

1521* Skill、agent 和 hook 註冊

1522* MCP 伺服器初始化

~~1523~~

1524<h3 id="common-issues">

1525 常見問題

1526</h3>

~~1527~~

1528| 問題 | 原因 | 解決方案 |

1529| :---------------------------------- | :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1530| 外掛程式未載入 | 無效的 `plugin.json` | 執行 `claude plugin validate ./my-plugin` 或 `/plugin validate ./my-plugin`，其中 `./my-plugin` 是您的外掛程式目錄，以檢查 `plugin.json`、`hooks/hooks.json` 以及外掛程式預設目錄中的 skills、agents 和 commands 的前置資訊是否有語法和結構描述錯誤。請參閱[驗證外掛程式或沒有清單的目錄](/docs/zh-TW/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest)以了解執行涵蓋的內容 |

1531| Skills 未出現 | 目錄結構錯誤 | 確保 `skills/` 或 `commands/` 位於外掛程式根目錄，而不是在 `.claude-plugin/` 內 |

1532| Hooks 未觸發 | 指令碼不可執行 | 執行 `chmod +x script.sh` |

1533| MCP 伺服器失敗 | 缺少 `${CLAUDE_PLUGIN_ROOT}` | 對所有外掛程式路徑使用變數 |

1534| 路徑錯誤 | 使用了絕對路徑 | 使路徑相對，以 `./` 開頭；請參閱[路徑行為規則](#path-behavior-rules)，其中涵蓋了 `skills` 欄位的 `"."` 例外 |

1535| LSP `Executable not found in $PATH` | 語言伺服器未安裝 | 安裝二進位檔案（例如，`npm install -g typescript-language-server typescript`） |

~~1536~~

1537<h3 id="example-error-messages">

1538 範例錯誤訊息

1539</h3>

~~1540~~

1541**清單驗證錯誤**：

~~1542~~

1543* `Invalid JSON syntax: Unexpected token } in JSON at position 142`：檢查是否缺少逗號、多餘逗號或未加引號的字串

1544* `Plugin <name> has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Invalid input: expected string, received undefined`：缺少必需欄位

1545* `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 在其他方面有效。

~~1546~~

1547**外掛程式載入錯誤**：

~~1548~~

1549* `Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.`：命令路徑存在但不包含有效的命令檔案

1550* `Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.`：marketplace.json 中的 `source` 路徑指向不存在的目錄

1551* `Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.`：移除重複的元件定義或移除 marketplace 項目中的 `strict: false`

~~1552~~

1553<h3 id="hook-troubleshooting">

1554 Hook 除錯

1555</h3>

~~1556~~

1557**Hook 指令碼未執行**：

~~1558~~

15591. 檢查指令碼是否可執行：`chmod +x ./scripts/your-script.sh`

15602. 驗證 shebang 行：第一行應為 `#!/bin/bash` 或 `#!/usr/bin/env bash`

15613. 檢查路徑是否使用 `${CLAUDE_PLUGIN_ROOT}`：`"command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/your-script.sh"`

15624. 手動測試指令碼：`./scripts/your-script.sh`

~~1563~~

1564**Hook 未在預期事件上觸發**：

~~1565~~

15661. 驗證事件名稱正確（區分大小寫）：`PostToolUse`，而不是 `postToolUse`

15672. 檢查匹配器模式是否與您的工具相符：`"matcher": "Write|Edit"` 用於檔案操作

15683. 確認 hook 類型有效：`command`、`http`、`mcp_tool`、`prompt` 或 `agent`

~~1569~~

1570<h3 id="mcp-server-troubleshooting">

1571 MCP 伺服器除錯

1572</h3>

~~1573~~

1574**伺服器未啟動**：

~~1575~~

15761. 檢查命令是否存在且可執行

15772. 驗證所有路徑都使用 `${CLAUDE_PLUGIN_ROOT}` 變數

15783. 檢查 MCP 伺服器日誌：`claude --debug` 顯示初始化錯誤

15794. 在 Claude Code 外手動測試伺服器

~~1580~~

1581**伺服器工具未出現**：

~~1582~~

15831. 確保伺服器在 `.mcp.json` 或 `plugin.json` 中正確設定

15842. 驗證伺服器正確實作 MCP 協定

15853. 檢查除錯輸出中的連線逾時

~~1586~~

1587<h3 id="directory-structure-mistakes">

1588 目錄結構錯誤

1589</h3>

~~1590~~

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

~~1592~~

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

~~1594~~

1595**除錯檢查清單**：

~~1596~~

15971. 執行 `claude --debug` 並查找「loading plugin」訊息

15982. 檢查每個元件目錄是否列在除錯輸出中

15993. 驗證檔案權限允許讀取外掛程式檔案

~~1600~~

1601***

~~1602~~

1603<h2 id="distribution-and-versioning-reference">

1604 發佈和版本管理參考

1605</h2>

~~1606~~

1607<h3 id="version-management">

1608 版本管理

1609</h3>

~~1610~~

1611Claude Code 使用外掛程式的版本作為快取金鑰，以判斷是否有可用的更新。當您執行 `/plugin update` 或自動更新觸發時，Claude Code 會計算目前版本，如果與已安裝的版本相符，則跳過更新。從[本機目錄市集](#plugin-caching-and-file-resolution)載入的外掛程式會在每次工作階段開始時載入其目前的來源檔案，無論其版本字串說什麼。

~~1612~~

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

~~1614~~

16151. 外掛程式 `plugin.json` 中的 `version` 欄位

16162. 外掛程式在 `marketplace.json` 中的市集項目中的 `version` 欄位

16173. 外掛程式來源的 git 提交 SHA，適用於 git 託管市集中的 `github`、`url`、`git-subdir` 和相對路徑來源

16184. SHA-256 摘要，適用於 [`archive` 來源](/docs/zh-TW/plugin-marketplaces#zip-archives)：市集項目中的 `sha256` 釘選，或當您未設定釘選時下載檔案的摘要。Claude Code 將其縮短為前 12 個字元

16195. `unknown`，適用於 `npm` 來源或不在 git 儲存庫內的本機目錄。Claude Code 不會從包含安裝路徑的儲存庫（例如 git 管理的 `~/.claude`）中取得版本

~~1620~~

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

~~1622~~

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

~~1624~~

1625| 方法 | 如何操作 | 更新行為 | 最適合 |

1626| :------------ | :-------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------- | :--------------------------- |

~~1630~~

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

~~1632~~

1633***

~~1634~~

1635<h2 id="see-also">

1636 另請參閱

1637</h2>

~~1638~~

1639* [Plugins](/docs/zh-TW/plugins) - 教學和實際使用

1640* [Plugin marketplaces](/docs/zh-TW/plugin-marketplaces) - 建立和管理 marketplaces

1641* [Skills](/docs/zh-TW/skills) - Skill 開發詳細資訊

1642* [Subagents](/docs/zh-TW/sub-agents) - Agent 設定和功能

1643* [Hooks](/docs/zh-TW/hooks) - 事件處理和自動化

1644* [MCP](/docs/zh-TW/mcp) - 外部工具整合

1645* [Settings](/docs/zh-TW/settings) - Plugins 的設定選項