Claude Code 手冊

Appearance

Claude How To

Claude Code 外掛程式 (Plugins) ​

本資料夾包含完整的外掛程式範例，將多個 Claude Code 功能打包成完整且可安裝的套件。

概覽 (Overview) ​

Claude Code 外掛程式 (Plugins) 是自訂功能（斜線指令 (Slash Commands)、子代理 (Subagents)、MCP 伺服器 (MCP Servers) 與掛鉤 (Hooks)）的打包集合，只需單一指令即可完成安裝。它們代表最高層級的擴充機制——將多種功能組合為凝聚、可分享的套件。

外掛程式架構 (Plugin Architecture) ​

mermaid
graph TB
    A["外掛程式 (Plugin)"]
    B["斜線指令 (Slash Commands)"]
    C["子代理 (Subagents)"]
    D["MCP 伺服器 (MCP Servers)"]
    E["掛鉤 (Hooks)"]
    F["設定 (Configuration)"]

    A -->|打包| B
    A -->|打包| C
    A -->|打包| D
    A -->|打包| E
    A -->|打包| F

外掛程式載入流程 (Plugin Loading Process) ​

mermaid
sequenceDiagram
    participant User as 使用者
    participant Claude as Claude Code
    participant Plugin as 外掛程式市集 (Plugin Marketplace)
    participant Install as 安裝 (Installation)
    participant SlashCmds as 斜線指令 (Slash Commands)
    participant Subagents as 子代理 (Subagents)
    participant MCPServers as MCP 伺服器 (MCP Servers)
    participant Hooks as 掛鉤 (Hooks)
    participant Tools as 已設定工具 (Configured Tools)

    User->>Claude: /plugin install pr-review
    Claude->>Plugin: 下載外掛程式清單 (Manifest)
    Plugin-->>Claude: 回傳外掛程式定義
    Claude->>Install: 解壓縮元件
    Install->>SlashCmds: 設定
    Install->>Subagents: 設定
    Install->>MCPServers: 設定
    Install->>Hooks: 設定
    SlashCmds-->>Tools: 準備就緒
    Subagents-->>Tools: 準備就緒
    MCPServers-->>Tools: 準備就緒
    Hooks-->>Tools: 準備就緒
    Tools-->>Claude: 外掛程式已安裝 ✅

無需市集 (No marketplace required) (v2.1.157+)：置於 .claude/skills 目錄中的外掛程式現在無需市集即可自動載入。可使用 claude plugin init <name> 腳本化建立新外掛程式，該指令會在 ~/.claude/skills/<name>/（使用者全域 (user-global)）建立它，並在下一個會話中自動載入為 <name>@skills-dir。

外掛程式類型與分發 (Plugin Types & Distribution) ​

類型 (Type)範圍 (Scope)分享 (Shared)權限/機構 (Authority)範例 (Examples)
官方 (Official)全域 (Global)所有使用者AnthropicPR 審查 (PR Review), 安全性指導 (Security Guidance)
社群 (Community)公開 (Public)所有使用者社群開發運營 (DevOps), 資料科學 (Data Science)
組織 (Organization)內部 (Internal)團隊成員公司內部標準、工具
個人 (Personal)個人 (Individual)單一使用者開發者自訂工作流程

外掛程式定義結構 (Plugin Definition Structure) ​

外掛程式清單 (Manifest) 在 .claude-plugin/plugin.json 中使用 JSON 格式：

json
{
  "name": "my-first-plugin",
  "description": "A greeting plugin",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  },
  "homepage": "https://example.com",
  "repository": "https://github.com/user/repo",
  "license": "MIT"
}

除了這些識別欄位之外，清單還可以指向存放在預設資料夾之外元件的 Claude Code，並包含探索與相依性中繼資料 (discovery and dependency metadata)：

欄位 (Field)類型 (Type)說明 (Description)
workflowsstring | array自訂 工作流程 (workflow) 腳本檔案或目錄（取代預設的 workflows/）
outputStylesstring | array自訂輸出樣式檔案或目錄（取代預設的 output-styles/）
lspServersstring | array | object用於程式碼智慧的 LSP 伺服器 (LSP Servers) — 跳轉至定義 (go to definition)、尋找參考 (find references)、診斷 (diagnostics)。通常為 "./.lsp.json"。參見 LSP 伺服器設定
channelsarray用於訊息注入的通道宣告 (Channel declarations)（Telegram、Slack、Discord 風格）
dependenciesarray此外掛程式所需的其他外掛程式，可選擇性帶有語意化版本 (semver) 限制
keywordsarray在瀏覽與搜尋市集時使用的探索標籤 (Discovery tags)
metadataobject自由形式的物件，用於自訂資料（如權益 (entitlement) 或目錄欄位）
experimental.themesstring | array色彩主題檔案或目錄（取代預設的 themes/）
experimental.monitorsstring | array當外掛程式啟用時自動啟動的 背景監控器 (Background Monitor) 設定

外掛程式結構範例 (Plugin Structure Example) ​

my-plugin/
├── .claude-plugin/
│   └── plugin.json       # 清單 (Manifest) (名稱、描述、版本、作者)
├── commands/             # 作為 Markdown 檔案的技能 (Skills)
│   ├── task-1.md
│   ├── task-2.md
│   └── workflows/
├── agents/               # 自訂代理定義
│   ├── specialist-1.md
│   ├── specialist-2.md
│   └── configs/
├── skills/               # 帶有 SKILL.md 檔案的代理技能 (Agent Skills)
│   ├── skill-1.md
│   └── skill-2.md
├── hooks/                # hooks.json 中的事件處理程序 (Event handlers)
│   └── hooks.json
├── .mcp.json             # MCP 伺服器設定
├── .lsp.json             # 用於程式碼智慧的 LSP 伺服器設定
├── bin/                  # 啟用外掛程式時新增至 Bash 工具 PATH 的可執行檔
├── settings.json         # 啟用外掛程式時套用的預設設定（目前僅支援 `agent` 鍵）
├── themes/               # 選用：隨附自訂 Claude Code 主題 (v2.1.118+)
├── templates/
│   └── issue-template.md
├── scripts/
│   ├── helper-1.sh
│   └── helper-2.py
├── docs/
│   ├── README.md
│   └── USAGE.md
└── tests/
    └── plugin.test.js

附註：commands/ 是舊版遺留 (legacy)。官方指導原則是 "針對新外掛程式請使用 skills/"。現有的 commands/ 目錄仍可繼續運作 — 本模組中的三個範例外掛程式均隨附一個 — 但新外掛程式應將其功能放在 skills/ 中作為 SKILL.md 目錄，而非單平的 Markdown 指令檔案。

LSP 伺服器設定 (LSP Server Configuration) ​

外掛程式可以包含語言伺服器協定 (Language Server Protocol, LSP) 支援，以提供即時程式碼智慧 (real-time code intelligence)。在工作時，LSP 伺服器可提供診斷 (diagnostics)、程式碼導覽 (code navigation) 與符號資訊 (symbol information)。

設定位置：

  • 外掛程式根目錄中的 .lsp.json 檔案
  • plugin.json 中的 lspServers 鍵 — 官方清單欄位名稱。它接受字串、陣列或物件：字串或陣列指向 LSP 設定檔或目錄（例如 "./.lsp.json"），而物件則以行內 (inline) 方式宣告伺服器。

欄位參考 (Field Reference) ​

欄位 (Field)必填 (Required)說明 (Description)
command是LSP 伺服器二進位檔（必須在 PATH 中）
extensionToLanguage是將副檔名對映至語言 ID
args否伺服器的命令列引數 (Command-line arguments)
transport否通訊方式：stdio（預設）或 socket
env否伺服器程序展現的環境變數 (Environment variables)
initializationOptions否在 LSP 初始化期間傳送的選項
settings否傳遞給伺服器的工作區設定 (Workspace configuration)
workspaceFolder否覆寫工作區資料夾路徑
startupTimeout否等待伺服器啟動的最大時間 (ms)
shutdownTimeout否優雅關閉 (graceful shutdown) 的最大時間 (ms)
restartOnCrash否若伺服器崩潰則自動重啟
maxRestarts否放棄前最大的重啟嘗試次數

設定範例 (Example Configurations) ​

Go (gopls):

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

Python (pyright):

json
{
  "python": {
    "command": "pyright-langserver",
    "args": ["--stdio"],
    "extensionToLanguage": {
      ".py": "python",
      ".pyi": "python"
    }
  }
}

TypeScript:

json
{
  "typescript": {
    "command": "typescript-language-server",
    "args": ["--stdio"],
    "extensionToLanguage": {
      ".ts": "typescript",
      ".tsx": "typescriptreact",
      ".js": "javascript",
      ".jsx": "javascriptreact"
    }
  }
}

可用的 LSP 外掛程式 (Available LSP Plugins) ​

官方市集包含預先設定好的 LSP 外掛程式：

外掛程式 (Plugin)語言 (Language)伺服器二進位檔 (Server Binary)安裝指令 (Install Command)
pyright-lspPythonpyright-langserverpip install pyright
typescript-lspTypeScript/JavaScripttypescript-language-servernpm install -g typescript-language-server typescript
rust-lspRustrust-analyzer透過 rustup component add rust-analyzer 安裝

LSP 能力 (LSP Capabilities) ​

設定完成後，LSP 伺服器可提供：

  • 即時診斷 (Instant diagnostics) — 編輯後立即顯示錯誤與警告
  • 程式碼導覽 (Code navigation) — 跳轉至定義 (go to definition)、尋找參考 (find references)、尋找實作 (implementations)
  • 懸停資訊 (Hover information) — 懸停時顯示型態簽名 (type signatures) 與說明文件
  • 符號清單 (Symbol listing) — 瀏覽目前檔案或工作區中的符號

PATH 上的 bin/ 目錄 (bin/ Directory on PATH) ​

當外掛程式啟用時，其 bin/ 目錄會加載至會話的 PATH 前端。在該處隨附的任何可執行檔都可以直接從 Bash 工具中依名稱呼叫 — 無需指定完整路徑。

bash
# 在外掛程式配置中：
my-plugin/
├── plugin.json
└── bin/
    └── my-tool          # 可執行檔 (chmod +x)

# 在已啟用該外掛程式的 Claude Code 會話內部：
$ my-tool --help

將此功能用於 CLI 輔助工具，以便相同外掛程式內部的掛鉤 (hooks)、技能 (skills) 或指令 (commands) 能進行外殼呼叫 (shell out)。請將檔案在外掛程式儲存庫中標記為可執行 (chmod +x) — git 會保留此位元權限。

外掛程式選項 (Plugin Options) (v2.1.83+) ​

外掛程式可以透過 userConfig 在清單中宣告使用者可設定的選項。標記為 sensitive: true 的數值會儲存在系統金鑰圈 (system keychain) 中，而非純文字設定檔：

json
{
  "name": "my-plugin",
  "version": "1.0.0",
  "userConfig": {
    "apiKey": {
      "description": "API key for the service",
      "sensitive": true
    },
    "region": {
      "description": "Deployment region",
      "default": "us-east-1"
    }
  }
}

持久性外掛程式資料 (${CLAUDE_PLUGIN_DATA}) (v2.1.78+) ​

外掛程式可透過 ${CLAUDE_PLUGIN_DATA} 環境變數存取持久性狀態目錄 (persistent state directory)。此目錄對每個外掛程式是唯一的，並且跨會話持久存在，使其適用於快取 (caches)、資料庫 (databases) 和其他持久性狀態：

json
{
  "hooks": {
    "PostToolUse": [
      {
        "command": "node ${CLAUDE_PLUGIN_DATA}/track-usage.js"
      }
    ]
  }
}

當安裝外掛程式時會自動建立該目錄。儲存在此處的檔案將持續保留，直到解除安裝該外掛程式。

背景監控器 (Background Monitors) (v2.1.105) ​

外掛程式可以註冊背景監控器，這些監控器會在會話啟動或呼叫外掛程式的技能時自動武裝 (auto-arm)。在你的外掛程式清單中新增頂層 monitors 鍵：

json
{
  "name": "my-plugin",
  "version": "1.0.0",
  "monitors": [
    {
      "command": "tail -f /var/log/app.log",
      "trigger": "session_start"
    }
  ]
}

trigger 欄位接受：

  • "session_start" — 當會話開始時自動武裝監控器
  • "skill_invoke" — 當外掛程式的技能被呼叫時武裝監控器

監控器在底層使用相同的監控工具 (Monitor tool)，將 stdout 行作為事件串流傳送，供 Claude 進行回應。

透過設定檔的行內外掛程式 (source: 'settings') (v2.1.80+) ​

外掛程式可以使用 source: 'settings' 欄位作為市集項目在設定檔中進行行內定義 (inline)。這允許直接嵌入外掛程式定義，而不需要單獨的儲存庫或市集：

json
{
  "pluginMarketplaces": [
    {
      "name": "inline-tools",
      "source": "settings",
      "plugins": [
        {
          "name": "quick-lint",
          "source": "./local-plugins/quick-lint"
        }
      ]
    }
  ]
}

外掛程式設定 (Plugin Settings) ​

外掛程式可以隨附 settings.json 檔案以提供預設設定。目前支援 agent 鍵，用於設定外掛程式的主執行緒代理 (main thread agent)：

json
{
  "agent": "agents/specialist-1.md"
}

當外掛程式包含 settings.json 時，其預設值會在安裝時套用。使用者可以在自己的專案或使用者設定中覆寫這些設定。

獨立模式與外掛程式模式之比較 (Standalone vs Plugin Approach) ​

方式 (Approach)指令名稱 (Command Names)設定 (Configuration)最適合 (Best For)
獨立模式 (Standalone)/hello在 CLAUDE.md 中手動設定個人、專案特定
外掛程式模式 (Plugins)/plugin-name:hello透過 plugin.json 自動化分享、分發、團隊使用

對於快速的個人工作流程，請使用獨立斜線指令。當你想打包多個功能、與團隊共享或發布以供分發時，請使用外掛程式。

帶空格的呼叫 (Spaced invocation) (v2.1.136+)：外掛程式斜線指令也可以搭配空格使用 — /myplugin review 會解析為標準的 /myplugin:review。兩種形式皆可；冒號形式為標準形式且在腳本中被推薦使用。

skills/ 探索 (v2.1.136+)：plugin.json 中的 skills 項目不再隱藏外掛程式預設的 skills/ 目錄。在兩個地方宣告的技能會合併，因此你可以在 plugin.json 中列出一些重點，而不會失去其餘部分。

根目錄 SKILL.md 外掛程式 (v2.1.142+)：擁有頂層 SKILL.md 且沒有 skills/ 子目錄的外掛程式本身會呈現為單一技能 — 外掛程式即是技能。這是一種額外的模式，而非取代 skills/ 目錄或 plugin.json 的 skills 項目；在目錄配置無法帶來附加價值的微型單一技能外掛程式中使用它。

實用範例 (Practical Examples) ​

範例 1：PR 審查外掛程式 (PR Review Plugin) ​

檔案： .claude-plugin/plugin.json

json
{
  "name": "pr-review",
  "version": "1.0.0",
  "description": "Complete PR review workflow with security, testing, and docs",
  "author": {
    "name": "Anthropic"
  },
  "repository": "https://github.com/your-org/pr-review",
  "license": "MIT"
}

檔案： commands/review-pr.md

markdown
---
name: Review PR
description: Start comprehensive PR review with security and testing checks
---

# PR Review

This command initiates a complete pull request review including:

1. Security analysis
2. Test coverage verification
3. Documentation updates
4. Code quality checks
5. Performance impact assessment

檔案： agents/security-reviewer.md

yaml
---
name: security-reviewer
description: Security-focused code review
tools: Read, Grep, Bash
---

# Security Reviewer

Specializes in finding security vulnerabilities:
- Authentication/authorization issues
- Data exposure
- Injection attacks
- Secure configuration

安裝 (Installation)：

bash
/plugin install pr-review

# 結果 (Result)：
# ✅ 3 slash commands installed
# ✅ 3 subagents configured
# ✅ 2 MCP servers connected
# ✅ 4 hooks registered
# ✅ Ready to use!

範例 2：DevOps 外掛程式 (DevOps Plugin) ​

元件 (Components)：

devops-automation/
├── commands/
│   ├── deploy.md
│   ├── rollback.md
│   ├── status.md
│   └── incident.md
├── agents/
│   ├── deployment-specialist.md
│   ├── incident-commander.md
│   └── alert-analyzer.md
├── mcp/
│   ├── github-config.json
│   ├── kubernetes-config.json
│   └── prometheus-config.json
├── hooks/
│   ├── pre-deploy.js
│   ├── post-deploy.js
│   └── on-error.js
└── scripts/
    ├── deploy.sh
    ├── rollback.sh
    └── health-check.sh

範例 3：說明文件外掛程式 (Documentation Plugin) ​

打包元件 (Bundled Components)：

documentation/
├── commands/
│   ├── generate-api-docs.md
│   ├── generate-readme.md
│   ├── sync-docs.md
│   └── validate-docs.md
├── agents/
│   ├── api-documenter.md
│   ├── code-commentator.md
│   └── example-generator.md
├── mcp/
│   ├── github-docs-config.json
│   └── slack-announce-config.json
└── templates/
    ├── api-endpoint.md
    ├── function-docs.md
    └── adr-template.md

外掛程式市集 (Plugin Marketplace) ​

官方 Anthropic 管理的外掛程式目錄為 anthropics/claude-plugins-official，會在首次互動式啟動時自動註冊。企業管理員還可以建立私有外掛程式市集以進行內部分發。

還有一個 社群市集 (community marketplace) anthropics/claude-plugins-community，託管已通過 Anthropic 自動化驗證與安全性篩選的第三方外掛程式 — 每個外掛程式都固定在目錄中的特定 commit SHA。與官方市集不同，你需要手動新增它：

bash
/plugin marketplace add anthropics/claude-plugins-community

# 然後使用 claude-community 市集名稱從中進行安裝
/plugin install <plugin-name>@claude-community
mermaid
graph TB
    A["外掛程式市集 (Plugin Marketplace)"]
    B["官方 (Official)<br/>anthropics/claude-plugins-official"]
    C["社群市集 (Community Marketplace)"]
    D["企業私有登錄檔<br/>(Enterprise Private Registry)"]

    A --> B
    A --> C
    A --> D

    B -->|分類| B1["開發 (Development)"]
    B -->|分類| B2["開發運營 (DevOps)"]
    B -->|分類| B3["說明文件 (Documentation)"]

    C -->|搜尋| C1["DevOps 自動化"]
    C -->|搜尋| C2["行動裝置開發"]
    C -->|搜尋| C3["資料科學"]

    D -->|內部| D1["公司標準"]
    D -->|內部| D2["舊版系統"]
    D -->|內部| D3["合規性"]

    style A fill:#e1f5fe,stroke:#333,color:#333
    style B fill:#e8f5e9,stroke:#333,color:#333
    style C fill:#f3e5f5,stroke:#333,color:#333
    style D fill:#fff3e0,stroke:#333,color:#333

市集設定 (Marketplace Configuration) ​

企業與進階使用者可以透過設定控制市集行為：

設定 (Setting)說明 (Description)
extraKnownMarketplaces新增預設值以外的額外市集來源
strictKnownMarketplaces控制允許使用者新增哪些市集（僅限管理模式 managed-only）
blockedMarketplaces由管理員管理的市集封鎖清單（自 v2.1.119 起支援 hostPattern / pathPattern 正則表示式欄位）
deniedPlugins由管理員管理的封鎖清單，以防止安裝特定的外掛程式

更友善的別名 (v2.1.232)：additionalMarketplaces 被接受作為 extraKnownMarketplaces 的別名，而 allowedMarketplaces 作為 strictKnownMarketplaces 的別名。 源自變更日誌 — v2.1.232 變更日誌宣佈了它們，但官方設定參考尚未列出這兩個名稱。繼續使用標準鍵是安全的。

擁有者萬用字元 (Owner wildcards) (v2.1.223+)："owner/*" 項目允許或封鎖一個 GitHub 擁有者下的每個市集儲存庫。僅在 strictKnownMarketplaces 與 blockedMarketplaces 中接受。 在其他出現 github 來源的地方 — 包括 extraKnownMarketplaces 與 /plugin marketplace add — repo 值必須指定單一儲存庫。

強制執行 (Enforcement) (v2.1.117+)：blockedMarketplaces 與 strictKnownMarketplaces 會在外掛程式生命週期的每個事件（安裝、更新、重新整理與自動更新）中強制執行，而不僅僅是在首次新增時。strictKnownMarketplaces 為僅限管理模式 (managed-only)。

帶有主機/路徑正則表示式的 blockedMarketplaces 範例 (v2.1.119)：

json
{
  "blockedMarketplaces": [
    {
      "hostPattern": "^evil\\.example\\.com$",
      "pathPattern": "^/marketplaces/.*"
    }
  ]
}

市集 headersHelper (v2.1.238) ​

url 市集 — 或單個目錄項目 — 可以指定一個 headersHelper 指令，該指令會生成用於擷取目錄和任何同源檔案庫 (same-origin archives) 的 HTTP 標頭。這就是位於權杖核發服務背後的私有市集進行身分驗證的方式，而無需在設定中包含靜態密鑰。

目錄項目的輔助工具僅在安裝或更新時執行，且僅在其指令展示給你看之後才執行：claude plugin install 與 claude plugin update 會在執行前提示 [y/N]。在自動化流程中傳遞 -y 可以在沒有提示的情況下接受。

額外市集功能 (Additional Marketplace Features) ​

  • 市集搜尋列 (Marketplace search bar) (v2.1.172)：在 /plugin 中瀏覽市集的外掛程式時，搜尋列可讓你依名稱或關鍵字篩選市集的外掛程式 — 對於捲動完整清單較慢的大型市集非常實用。
  • 預設 git 超時：針對大型外掛程式儲存庫，將預設值從 30 秒增加到 120 秒
  • 自訂 npm 登錄檔：外掛程式可以指定自訂 npm 登錄檔 URL 以進行相依性解析
  • 版本固定 (Version pinning)：將外掛程式固定至特定版本以獲得可重複的環境
  • 瀏覽窗格中的預期脈絡成本 (Projected context cost) (v2.1.143)：/plugin 市集瀏覽器會顯示每個外掛程式預期的每輪脈絡權杖成本 (context-token cost) — 始終載入的技能、掛鉤與 MCP 伺服器描述符的總和。在安裝前使用它來評估外掛程式採用規模。相同的預測可在安裝後透過 claude plugin details <name> 取得。

帶有成本欄位的瀏覽列範例：

text
NAME              VERSION   AUTHOR     CTX/TURN   DESCRIPTION
code-reviewer     1.2.0     anthropic  +1,420     Multi-agent PR review
devops-toolkit    0.4.1     acme       +3,180     SRE playbooks, on-call helpers
docs-helper       0.9.0     community  +610       Doc-style guide enforcement

市集定義結構 schema (Marketplace Definition Schema) ​

外掛程式市集在 .claude-plugin/marketplace.json 中定義：

json
{
  "name": "my-team-plugins",
  "owner": "my-org",
  "plugins": [
    {
      "name": "code-standards",
      "source": "./plugins/code-standards",
      "description": "Enforce team coding standards",
      "version": "1.2.0",
      "author": "platform-team"
    },
    {
      "name": "deploy-helper",
      "source": {
        "source": "github",
        "repo": "my-org/deploy-helper",
        "ref": "v2.0.0"
      },
      "description": "Deployment automation workflows"
    }
  ]
}
欄位 (Field)必填 (Required)說明 (Description)
name是烤肉串命名法 (kebab-case) 的市集名稱
owner是維護市集的組織或使用者
plugins是外掛程式項目的陣列
plugins[].name是外掛程式名稱 (kebab-case)
plugins[].source是外掛程式來源（路徑字串或來源物件）
plugins[].description否簡短的外掛程式描述
plugins[].version否語意化版本字串 (Semantic version string)
plugins[].author否外掛程式作者名稱
plugins[].renames否將舊的外掛程式 name 對映至其目前的名稱（若已移除則為 null），以便使用者自動遷移 (v2.1.193)
plugins[].displayName否在 UI 中顯示的人類可讀名稱；不用於查找 (v2.1.143)
plugins[].defaultEnabled否若為 false，則外掛程式安裝後預設為停用，直到使用者選擇啟用 (v2.1.154)

外掛程式來源類型 (Plugin Source Types) ​

外掛程式可以來自多個位置：

來源 (Source)語法 (Syntax)範例 (Example)
相對路徑 (Relative path)字串路徑"./plugins/my-plugin"
GitHub{ "source": "github", "repo": "owner/repo" }{ "source": "github", "repo": "acme/lint-plugin", "ref": "v1.0" }
Git URL{ "source": "url", "url": "..." }{ "source": "url", "url": "https://git.internal/plugin.git" }
Git 子目錄 (Git subdirectory){ "source": "git-subdir", "url": "...", "path": "..." }{ "source": "git-subdir", "url": "https://github.com/org/monorepo.git", "path": "packages/plugin" }
npm{ "source": "npm", "package": "..." }{ "source": "npm", "package": "@acme/claude-plugin", "version": "^2.0" }
pip{ "source": "pip", "package": "..." }{ "source": "pip", "package": "claude-data-plugin", "version": ">=1.0" }
封存檔 (Archive) (v2.1.224+){ "source": "archive", "url": "..." }{ "source": "archive", "url": "https://cdn.example.com/lint-plugin-1.2.0.zip", "sha256": "…" }
指令 (Command) (v2.1.229+){ "source": "command", "command": "..." }{ "source": "command", "command": "acme-plugin-resolver --print-dir" }

GitHub 與 git 來源支援選用的 ref（分支/標籤）與 sha（commit 雜湊值）欄位以固定版本。

純來源名稱與 metadata.pluginRoot (v2.1.239)：市集的 metadata.pluginRoot 現在生效 — 目錄中的純外掛程式來源名稱會解析為該根目錄下的目錄，而無需在每個項目上拼寫完整的相對路徑。

從 claude.ai 同步的技能 (v2.1.239)：從 claude.ai 同步下來的外掛程式會顯示為 name@synced。在 claude plugin enable <name>@synced 與 claude plugin disable <name>@synced 中以該方式進行存取。同步的外掛程式永遠不會覆寫同名的已安裝外掛程式 — 兩者共存，透過 @synced 後綴進行區分。

archive 來源 (v2.1.224+) ​

透過 HTTPS 從 zip 檔安裝外掛程式 — 不需要 git clone，不需要 npm install。

json
{
  "source": "archive",
  "url": "https://cdn.example.com/lint-plugin-1.2.0.zip",
  "sha256": "3b1f0c2e9a7d4f5b8c6e1a2d3f4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b"
}
欄位 (Field)必填 (Required)附註 (Notes)
url是僅限 HTTPS。 http://、回環 (loopback)、本機連結 (link-local) 與雲端中繼資料主機皆會被拒絕 — 且會在每次重定向跳轉 (redirect hop) 時重新檢查，因此重定向無法將你偷渡到被封鎖的主機
sha256否64 個十六進位字元。不相符時安裝會失敗並顯示 Plugin archive integrity check failed

封存檔限制最大為 256 MiB。針對非你自己建置的任何內容，請固定 sha256 — 沒有它，控制 URL 的任何人就能控制在你的會話中執行的程式碼。

command 來源 (v2.1.229+) ​

讓本地安裝的工具決定外掛程式的位置。當內部套件管理員已經知道如何擷取與佈局你的外掛程式時非常實用。

json
{
  "source": "command",
  "command": "acme-plugin-resolver --print-dir",
  "timeout": 60,
  "mode": "copy"
}

協定非常嚴格：指令必須在 stdout 上精確輸出單一行並以 exit code 0 結束。 該行是包含完整外掛程式之目錄的絕對路徑。

欄位 (Field)必填 (Required)預設值 (Default)附註 (Notes)
command是—要執行的指令
timeout否60（秒）最大 600
mode否"copy""copy" 建立目錄的快照；"link" 對其建立符號連結 (symlink)，因此修改會即時生效

指令會在每個會話中重新解析，且結果會在不需要重啟的情況下套用。組織可以使用 disableCommandPluginSources 在全組織範圍內完全封鎖此來源類型。

保留的市集名稱現在包含 first-party-plugins 與 healthcare (v2.1.205) — 這些保留給官方使用，無法由自訂市集宣告。

分發方法 (Distribution Methods) ​

GitHub (推薦):

bash
# 使用者新增你的市集
/plugin marketplace add owner/repo-name

其他 git 服務（需要完整 URL）:

bash
/plugin marketplace add https://gitlab.com/org/marketplace-repo.git

純 gitlab.com 儲存庫 URL（包含巢狀子群組）複製方式與 github.com URL 相同 (v2.1.232)。通訊協定 (scheme) 是強制的：自 v2.1.196 起，純 gitlab.example.com/team/plugins 會被拒絕，視為無效的 owner/repo 簡寫，因此請使用完整的 https://gitlab.com/company/plugins.git 格式。v2.1.232 還新增了 GitLab 權杖系列密鑰遮蔽 (token-family secret redaction)，並給予 glab CLI 與 gh 相同的沙盒 (sandbox) 及憑證路徑保護。

私有儲存庫 (Private repositories)：透過 git 憑證輔助工具 (credential helpers) 或環境權杖支援。使用者必須擁有該儲存庫的讀取權限。

官方市集提交 (Official marketplace submission)：透過 claude.ai/settings/plugins/submit 或 platform.claude.com/plugins/submit 將外掛程式提交至 Anthropic 策劃的市集以進行更廣泛的分發。

管理市集 (Managing Marketplaces) ​

bash
# 市集 CLI 指令
claude plugin marketplace add <source>       # 新增市集 (GitHub, URL, 本地)
claude plugin marketplace update [name]      # 重新整理目錄索引
claude plugin marketplace remove <name>      # 移除市集
claude plugin marketplace list               # 列出已設定的市集

重要：marketplace update 僅會重新整理外掛程式目錄（可供安裝的內容）。它不會更新已安裝的外掛程式。請使用 plugin update <name> 來更新特定的已安裝外掛程式。

嚴格模式 (Strict Mode) ​

控制市集定義如何與本地 plugin.json 檔案互動：

設定 (Setting)行為 (Behavior)
strict: true（預設）本地 plugin.json 具有權威性；市集項目為補充內容
strict: false市集項目即為完整的外掛程式定義

使用 strictKnownMarketplaces 的組織限制：

數值 (Value)效果 (Effect)
未設定無限制 — 使用者可以新增任何市集
空陣列 []鎖定 — 不允許任何市集
模式陣列允許清單 — 僅相符的市集可被新增
json
{
  "strictKnownMarketplaces": [
    "my-org/*",
    "github.com/trusted-vendor/*"
  ]
}

警告：在帶有 strictKnownMarketplaces 的嚴格模式下，使用者只能從被列入允許清單的市集中安裝外掛程式。這對於需要受控外掛程式分發的企業環境非常有用。

外掛程式安裝與生命週期 (Plugin Installation & Lifecycle) ​

mermaid
graph LR
    A["探索 (Discover)"] -->|瀏覽| B["市集 (Marketplace)"]
    B -->|選擇| C["外掛程式頁面"]
    C -->|檢視| D["元件 (Components)"]
    D -->|安裝| E["/plugin install"]
    E -->|解壓縮| F["設定 (Configure)"]
    F -->|啟用| G["使用 (Use)"]
    G -->|檢查| H["更新 (Update)"]
    H -->|可用| G
    G -->|完成| I["停用 (Disable)"]
    I -->|稍後| J["啟用 (Enable)"]
    J -->|返回| G

外掛程式功能比較 (Plugin Features Comparison) ​

功能 (Feature)斜線指令 (Slash Command)技能 (Skill)子代理 (Subagent)外掛程式 (Plugin)
安裝 (Installation)手動複製手動複製手動設定單一指令
設定時間 (Setup Time)5 分鐘10 分鐘15 分鐘2 分鐘
打包 (Bundling)單一檔案單一檔案單一檔案多個
版本控管 (Versioning)手動手動手動自動
團隊共享 (Team Sharing)複製檔案複製檔案複製檔案安裝 ID
更新 (Updates)手動手動手動自動可用
相依性 (Dependencies)無無無可包含
市集 (Marketplace)否否否是
分發 (Distribution)儲存庫儲存庫儲存庫市集

外掛程式 CLI 指令 (Plugin CLI Commands) ​

所有外掛程式操作均可作為 CLI 指令使用：

bash
claude plugin install <name>@<marketplace>   # 從市集安裝
claude plugin uninstall <name>               # 移除外掛程式
claude plugin update <name>                  # 將已安裝的外掛程式更新至最新版本
claude plugin list                           # 列出已安裝的外掛程式
claude plugin enable <name>                  # 啟用已停用的外掛程式
claude plugin disable <name>                 # 停用外掛程式
claude plugin validate <path>                # 驗證位於 <path> 的外掛程式結構
claude plugin tag [path]                     # 建立 {name}--v{version} 發布 git 標籤 (v2.1.118+)
claude plugin prune                          # 移除孤立的自動安裝外掛程式相依性 (v2.1.121+)
claude plugin uninstall <name> --prune       # 解除安裝並串接清理孤立相依性 (v2.1.121+)
claude plugin details <name>                 # 顯示清冊 + 預期的每輪權杖成本 (v2.1.139+)
claude plugin init <name>                    # 腳本化建立新外掛程式 (別名: claude plugin new)

別名：claude plugin new 用於 init，remove / rm 用於 uninstall，ls 用於 list，以及 autoremove 用於 prune。

值得了解的旗標：

指令 (Command)旗標 (Flag)目的 (Purpose)
plugin init--with <components...>腳本化建立特定的元件資料夾：skills, agents, hooks, mcp, lsp, output-style, channel
plugin init-f, --force覆寫現有的 .claude-plugin/ 目錄
plugin install--config <key=value>在安裝時設定 userConfig 選項
plugin install-y, --yes無需確認提示即可接受指令
plugin list--available同時列出市集中可用的外掛程式（需要 --json）
plugin tag--push建立標籤後將其推送到遠端
plugin tag--dry-run印出將被標記的內容而不建立標籤
plugin validate--strict將警告視為錯誤
plugin validate--json發出可由機器讀取的驗證報告 (v2.1.259+)

範例：claude plugin tag ./my-plugin 接受外掛程式的路徑（而非版本字串）。它會建立衍生自 plugin.json 的 {name}--v{version} git 標籤，驗證 plugin.json 與任何包含它的市集項目是否一致，這是發布外掛程式以供分發的推薦方式。

claude plugin prune 在安裝或解除安裝引入了自己相依性的市集外掛程式後非常有有用 — 它會移除父外掛程式已被移除的任何自動安裝之外掛程式。plugin uninstall --prune 可以在單一步驟中執行相同的串接清理。

相依性強制執行 (v2.1.143)：如果另一個啟用的外掛程式仍相依於目標，則 claude plugin disable <name> 會拒絕停用（相依性圖表會損壞）。claude plugin enable <name> 在單次確認提示後會強制啟用遞移相依性 (transitive dependencies)，而不需要針對每個相依性單獨進行啟用。使用 claude plugin prune 清理相依者隨後已被移除的相依性。

claude plugin details <name> (v2.1.139+) ​

claude plugin details <name> 印出外掛程式的完整元件清冊 — 技能 (skills)、掛鉤 (hooks)、MCP 伺服器、LSP 伺服器、背景監控器、斜線指令 — 以及預期的每輪（與每次呼叫）權杖成本 (projected token cost)。在採用外掛程式之前，使用它來評估外掛程式規模，特別是在脈絡受限的模型上。

輸出範例（簡略）：

text
plugin: code-reviewer (1.2.0)
skills:        3      hooks: 2      mcp: 1      lsp: 0      monitors: 0
commands:      /review, /security-review
projected ctx: +1,420 tokens per turn  ·  +9,800 tokens per /review invocation

LSP 伺服器已在 v2.1.142 中新增至詳細資訊窗格。亦可參見 外掛程式市集 中涵蓋的市集瀏覽窗格預期脈絡成本 (v2.1.143)。

安裝方法 (Installation Methods) ​

從市集安裝 (From Marketplace) ​

bash
/plugin install plugin-name
# 或從 CLI：
claude plugin install plugin-name@marketplace-name

它會立即生效嗎？ 自 v2.1.221 起，通常是的 — 請閱讀安裝摘要的最後一行：

安裝摘要顯示它的意思
Plugin is now active.Claude Code 已將外掛程式作為安裝的一部分進行啟用。無須進一步操作。
Run /reload-plugins to activate.外掛程式已安裝但尚未生效 — 要麼啟用它會使提示快取 (prompt cache) 失效，要麼啟用嘗試失敗了。

在 v2.1.221 之前，在目前的會話中，除非你執行 /reload-plugins 或重啟，否則不會有任何安裝生效，因此較舊的指南將該步驟描述為無條件的。

啟用 / 停用（帶有自動偵測範圍）(Enable / Disable with auto-detected scope) ​

bash
/plugin enable plugin-name
/plugin disable plugin-name

/plugin 介面會浮現未使用的外掛程式，以便你可以進行清理 (v2.1.187+)。當外掛程式的 plugin.json 中的 name 與其市集項目名稱不同時，啟用/停用亦可正常工作 (v2.1.195+)。

列出已安裝的外掛程式 (v2.1.163) (Listing installed plugins) ​

確認目前的會話中有哪些外掛程式處於啟用狀態：

bash
/plugin list             # 所有已安裝的外掛程式
/plugin list --enabled   # 僅限啟用的外掛程式
/plugin list --disabled  # 僅限停用的外掛程式

本地外掛程式（用於開發）(Local Plugin for development) ​

bash
# 用於本地測試的 CLI 旗標（可針對多個外掛程式重複使用）
claude --plugin-dir ./path/to/plugin
claude --plugin-dir ./plugin-a --plugin-dir ./plugin-b

# --plugin-dir 亦接受 .zip 封存檔路徑 (v2.1.128+)
claude --plugin-dir ./my-plugin.zip

# 為目前的會話從 URL 擷取外掛程式 .zip 封存檔 (v2.1.129+, 可重複)
claude --plugin-url https://example.com/releases/my-plugin-0.3.0.zip

從 Git 儲存庫安裝 (From Git Repository) ​

bash
/plugin install github:username/repo

自動更新 (Auto-Update) ​

Claude Code 在啟動時可以自動更新市集及其已安裝的外掛程式。

市集類型 (Marketplace Type)自動更新預設值 (Auto-Update Default)如何切換 (How to Toggle)
官方 (claude-plugins-official)✅ 啟用/plugin → 市集 → 選擇
第三方 / 本地❌ 停用相同的 UI 路徑

當自動更新執行時，Claude Code 會：

  1. 重新整理市集目錄
  2. 將已安裝的外掛程式更新至最新版本
  3. 回報每個外掛程式的結果：當 Claude Code 將外掛程式作為更新的一部分進行啟用時顯示 Plugin is now active.，未啟用時顯示 Run /reload-plugins to activate.

環境變數 (Environment Variables) ​

變數 (Variable)效果 (Effect)
DISABLE_AUTOUPDATER=1停用所有自動更新（Claude Code + 外掛程式）
DISABLE_AUTOUPDATER=1 + FORCE_AUTOUPDATE_PLUGINS=1保留外掛程式更新，停用 Claude Code 更新
CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1(v2.1.141+) 強制 claude plugin install 透過 HTTPS 而非 SSH 複製 GitHub 外掛程式來源，即使 SSH 遠端可用亦然。在沒有 SSH 金鑰的 CI 執行器或容器中使用。
bash
# 停用所有自動更新
export DISABLE_AUTOUPDATER=1

# 僅保留外掛程式自動更新
export DISABLE_AUTOUPDATER=1
export FORCE_AUTOUPDATE_PLUGINS=1

# 沒有 SSH 金鑰的 CI 執行器 — 強制外掛程式安裝使用 HTTPS
export CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1
claude plugin install code-reviewer@anthropic

遠端會話外掛程式載入 (v2.1.179)：遠端會話中的外掛程式載入效能已在 v2.1.179 中獲得改善，因此當你連線至遠端會話時，外掛程式能更快可用。

何時建立外掛程式 (When to Create a Plugin) ​

mermaid
graph TD
    A["我應該建立外掛程式嗎？"]
    A -->|需要多個元件| B{"多個指令<br/>或子代理<br/>或 MCP？"}
    B -->|是| C["✅ 建立外掛程式"]
    B -->|否| D["使用個別功能"]
    A -->|團隊工作流程| E{"與團隊<br/>分享？"}
    E -->|是| C
    E -->|否| F["保持為本地設定"]
    A -->|複雜設定| G{"需要自動<br/>設定？"}
    G -->|是| C
    G -->|否| D

外掛程式使用案例 (Plugin Use Cases) ​

使用案例 (Use Case)建議 (Recommendation)原因 (Why)
團隊新進人員導覽 (Team Onboarding)✅ 使用外掛程式即時設定、所有配置
框架設定 (Framework Setup)✅ 使用外掛程式打包特定框架指令
企業標準 (Enterprise Standards)✅ 使用外掛程式中央分發、版本控制
快速任務自動化 (Quick Task Automation)❌ 使用指令複雜度過高
單一領域專業知識 (Single Domain Expertise)❌ 使用技能太過重型，請改用技能
專業化分析 (Specialized Analysis)❌ 使用子代理手動建立或使用技能
即時資料存取 (Live Data Access)❌ 使用 MCP獨立存在，請勿打包

測試外掛程式 (Testing a Plugin) ​

在發布之前，使用 --plugin-dir CLI 旗標在本地測試你的外掛程式（可針對多個外掛程式重複使用）：

bash
claude --plugin-dir ./my-plugin
claude --plugin-dir ./my-plugin --plugin-dir ./another-plugin

# 除了目錄外，--plugin-dir 還接受 .zip 封存檔 (v2.1.128+)
claude --plugin-dir ./my-plugin.zip

# --plugin-url 為此會話從 URL 擷取外掛程式 .zip (v2.1.129+, 可重複)
claude --plugin-url https://example.com/releases/my-plugin-0.3.0.zip

這會載入你的外掛程式並啟動 Claude Code，允許你：

  • 驗證所有斜線指令皆可用
  • 測試子代理與代理功能是否正確
  • 確認 MCP 伺服器連接正常
  • 驗證掛鉤執行情況
  • 檢查 LSP 伺服器設定
  • 檢查是否有任何設定錯誤

熱重新載入 (Hot-Reload) ​

外掛程式在開發期間支援熱重新載入 (hot-reload)。當你修改外掛程式檔案時，Claude Code 可以自動偵測變更。你也可以使用以下指令強制重新載入：

bash
/reload-plugins

這會在不重啟會話的情況下重新讀取所有外掛程式清單、指令、代理、技能、掛鉤以及 MCP/LSP 設定。

外掛程式的管理設定 (Managed Settings for Plugins) ​

管理員可以使用管理設定 (managed settings) 在全組織範圍內控制外掛程式行為：

設定 (Setting)說明 (Description)
enabledPlugins預設啟用的外掛程式允許清單
deniedPlugins無法安裝的外掛程式封鎖清單
extraKnownMarketplaces新增預設值以外的額外市集來源
strictKnownMarketplaces限制允許使用者新增哪些市集（僅限管理模式 managed-only；自 v2.1.117 起在外掛程式生命週期的每個事件中強制執行）
blockedMarketplaces市集封鎖清單；自 v2.1.117 起在外掛程式生命週期的每個事件中強制執行；自 v2.1.119 起支援 hostPattern / pathPattern 正則表示式欄位
allowedChannelPlugins控制每個發布通道允許哪些外掛程式
disableCommandPluginSources在全組織範圍內封鎖 command 外掛程式來源類型 (v2.1.229+)

更友善的別名 (v2.1.232)：additionalMarketplaces 被接受作為 extraKnownMarketplaces 的別名，而 allowedMarketplaces 作為 strictKnownMarketplaces 的別名。 源自變更日誌 — v2.1.232 變更日誌宣佈了它們，但官方設定參考尚未列出這兩個名稱。繼續使用標準鍵是安全的。

擁有者萬用字元 (Owner wildcards) (v2.1.223+)："owner/*" 項目允許或封鎖一個 GitHub 擁有者下的每個市集儲存庫。僅在 strictKnownMarketplaces 與 blockedMarketplaces 中接受。 在其他出現 github 來源的地方 — 包括 extraKnownMarketplaces 與 /plugin marketplace add — repo 值必須指定單一儲存庫。

這些設定可以透過管理設定檔在組織層級套用，且優先權高於使用者層級的設定。

外掛程式安全性 (Plugin Security) ​

外掛程式子代理會在受限的沙盒 (sandbox) 中執行。外掛程式子代理定義中不允許使用以下 frontmatter 鍵：

  • hooks -- 子代理無法註冊事件處理程序
  • mcpServers -- 子代理無法設定 MCP 伺服器
  • permissionMode -- 子代理無法覆寫權限模型

這可確保外掛程式無法提升權限或在其宣告的範圍之外修改主機環境。

發布外掛程式 (Publishing a Plugin) ​

發布步驟：

  1. 建立包含所有元件的外掛程式結構
  2. 撰寫 .claude-plugin/plugin.json 清單
  3. 撰寫帶有說明文件的 README.md
  4. 使用 claude --plugin-dir ./my-plugin 在本地測試
  5. 使用 claude plugin tag ./my-plugin 標記發布版本 (v2.1.118+) — 接受外掛程式路徑並建立衍生自 plugin.json 的 {name}--v{version} git 標籤
  6. 提交至外掛程式市集
  7. 通過審查與核准
  8. 發布於市集上
  9. 使用者即可透過單一指令進行安裝

提交範例：

markdown
# PR Review Plugin

## Description
Complete PR review workflow with security, testing, and documentation checks.

## What's Included
- 3 slash commands for different review types
- 3 specialized subagents
- GitHub and CodeQL MCP integration
- Automated security scanning hooks

## Installation
```bash
/plugin install pr-review

Features ​

✅ Security analysis ✅ Test coverage checking ✅ Documentation verification ✅ Code quality assessment ✅ Performance impact analysis

Usage ​

bash
/review-pr
/check-security
/check-tests

Requirements ​

  • Claude Code 2.1+
  • GitHub access
  • CodeQL (optional)

## 外掛程式與手動設定之比較 (Plugin vs Manual Configuration)

**手動設定 (2 小時以上)：**
- 逐一安裝斜線指令
- 個別建立子代理
- 分別設定 MCP
- 手動設定掛鉤
- 為所有內容撰寫說明文件
- 與團隊分享（希望他們正確設定）

**使用外掛程式 (2 分鐘)：**
```bash
/plugin install pr-review
# ✅ 所有內容均已安裝與設定完成
# ✅ 立即準備就緒即可使用
# ✅ 團隊可以重現精確的設定

最佳實踐 (Best Practices) ​

建議作法 ✅ (Do's) ​

  • 使用清晰且具描述性的外掛程式名稱
  • 包含完整的 README
  • 適當管理你的外掛程式版本（語意化版本 semver）
  • 一起測試所有元件
  • 清晰地記錄需求說明文件
  • 提供使用範例
  • 包含錯誤處理機制
  • 適當標記標籤以利探索
  • 維持回溯相容性 (backward compatibility)
  • 保持外掛程式專注且具凝聚力
  • 包含全面的測試
  • 記錄所有相依性

不建議作法 ❌ (Don'ts) ​

  • 不要打包無關的功能
  • 不要硬編碼 (hardcode) 憑證
  • 不要跳過測試
  • 不要忘記說明文件
  • 不要建立冗餘的外掛程式
  • 不要忽視版本控制
  • 不要過度複雜化元件的相依性
  • 不要忘記優雅地處理錯誤

安裝說明 (Installation Instructions) ​

從市集安裝 (Installing from Marketplace) ​

  1. 瀏覽可用的外掛程式：

    bash
    /plugin list

  2. 檢視外掛程式詳細資訊：

    bash
    claude plugin details plugin-name

  3. 安裝外掛程式：

    bash
    /plugin install plugin-name

從本地路徑安裝 (Installing from Local Path) ​

bash
/plugin install ./path/to/plugin-directory

從 GitHub 安裝 (Installing from GitHub) ​

bash
/plugin install github:username/repo

列出已安裝的外掛程式 (Listing Installed Plugins) ​

bash
/plugin list             # 所有已安裝的外掛程式
/plugin list --enabled   # 僅限啟用的外掛程式
/plugin list --disabled  # 僅限停用的外掛程式

更新外掛程式 (Updating a Plugin) ​

使用 CLI 形式 — 這是在 plugin update 下記載的形式，也是有可用更新時 Claude Code 本身會指引你的形式：

bash
claude plugin update plugin-name

停用/啟用外掛程式 (Disabling/Enabling a Plugin) ​

bash
# 暫時停用
/plugin disable plugin-name

# 重新啟用
/plugin enable plugin-name

解除安裝外掛程式 (Uninstalling a Plugin) ​

bash
/plugin uninstall plugin-name

以下 Claude Code 功能可與外掛程式協同工作：

完整範例工作流程 (Complete Example Workflow) ​

PR 審查外掛程式完整工作流程 (PR Review Plugin Full Workflow) ​

1. 使用者: /review-pr

2. 外掛程式執行:
   ├── pre-review.js 掛鉤驗證 git 儲存庫
   ├── GitHub MCP 擷取 PR 資料
   ├── security-reviewer 子代理分析安全性
   ├── test-checker 子代理驗證覆蓋率
   └── performance-analyzer 子代理檢查效能

3. 結果綜合與呈現:
   ✅ 安全性：無重大問題
   ⚠️  測試：覆蓋率 65%（建議 80%+）
   ✅ 效能：無顯著影響
   📝 已提供 12 項建議

疑難排解 (Troubleshooting) ​

外掛程式無法安裝 (Plugin Won't Install) ​

  • 檢查 Claude Code 版本相容性：/version
  • 使用 JSON 驗證器確認 plugin.json 語法
  • 檢查網路連線（針對遠端外掛程式）
  • 檢查權限：ls -la plugin/

元件未載入 (Components Not Loading) ​

  • 驗證 plugin.json 中的路徑是否與實際目錄結構相符
  • 檢查檔案權限：chmod +x scripts/
  • 審查元件檔案語法
  • 檢查元件清冊：claude plugin details plugin-name

MCP 連線失敗 (MCP Connection Failed) ​

  • 驗證環境變數是否設定正確
  • 檢查 MCP 伺服器安裝情況與健康狀態
  • 使用 /mcp test 獨立測試 MCP 連線
  • 審查 mcp/ 目錄中的 MCP 設定

安裝後指令不可用 (Commands Not Available After Install) ​

  • 確保外掛程式已成功安裝：/plugin list
  • 檢查外掛程式是否已啟用：/plugin list --enabled
  • 檢查它是否已經生效 — 參見 安裝方法 中的安裝摘要指引：Plugin is now active. 不需要任何操作，Run /reload-plugins to activate. 代表需要執行該指令（不需要重啟）
  • 檢查與現有指令是否有名稱衝突

掛鉤執行問題 (Hook Execution Issues) ​

  • 驗證掛鉤檔案是否擁有正確權限
  • 檢查掛鉤語法與事件名稱
  • 審查掛鉤記錄檔 (logs) 以獲取錯誤詳細資訊
  • 如果可行，手動測試掛鉤

額外資源 (Additional Resources) ​

最後更新 (Last Updated)：2026 年 9 月 6 日 Claude Code 版本 (Claude Code Version)：2.1.263 資料來源 (Sources)：

Released under the MIT License.

Copyright © 2026 Claude Code HowTo Guide