12 · 怎麼給 AI 裝外掛

真正把 Claude Code 用進團隊，不是每個人都手動抄一遍配置，而是把好用的能力打包、分發、更新。Plugin 解決的就是這個問題：把散裝經驗變成可安裝的工具箱。——翔宇

1. 先從一個同事的問題開始

你已經把 Claude Code 配得很順手。

你有：

• 一個專案級 CLAUDE.md，寫著團隊規範。
• 兩個 Skills，用來做 code review 和 release note。
• 一個 MCP server，連線 GitHub。
• 三個 Hooks，負責格式化、敏感檔案保護和任務結束前檢查。
• 一套許可權規則，禁止讀 .env 和亂 push。

然後同事問：

你这套 Claude Code 怎么配的？我也想装。

你會發現麻煩來了。

單個檔案可以複製，單段配置可以貼過去。但整套能力散落在 .claude/、settings.json、.mcp.json、指令碼目錄、依賴說明裡。複製一次還行，給三個人複製就會出錯。你更新 Hook 邏輯後，還得通知大家手動更新。

官方 Create plugins 文件給的定位很清楚：Plugins 用來把 skills、agents、hooks、MCP servers 等擴充套件能力分享給專案和團隊。Standalone 配置適合個人和單專案；Plugin 適合跨專案、跨團隊、版本化分發。

2. Standalone 和 Plugin 的分界線

先不要急著做外掛。很多配置一開始就該散裝。

這跟寫程式碼一樣：不要一開始就發 npm 包。先在本專案裡跑通，穩定後再打包。

flowchart LR
    Idea["一個好用配置"]
    Local["本專案 standalone<br/>快速試錯"]
    Stable["跨專案複用<br/>結構穩定"]
    Plugin["打成 Plugin<br/>安裝 / 更新 / 分發"]
    Market["進入 Marketplace<br/>團隊或社群發現"]

    Idea --> Local --> Stable --> Plugin --> Market

    style Local fill:#dcfce7,stroke:#22c55e,stroke-width:2px
    style Plugin fill:#e0f2fe,stroke:#0284c7,stroke-width:2px
    style Market fill:#fef3c7,stroke:#f59e0b,stroke-width:2px

3. Plugin 不是“一個功能”，而是“一個容器”

舊理解裡，Plugin 常被說成只打包五類東西：commands、agents、skills、hooks、MCP。

當前官方口徑更寬。一個 Plugin 可以包含這些元件：

• Skills：放在 skills/，給 Claude 增加任務流程和領域能力。
• Commands：放在 commands/，是 flat Markdown 命令；新外掛優先用 skills/。
• Agents：放在 agents/，定義自定義 subagent。
• Hooks：放在 hooks/hooks.json，做自動化檢查和事件處理。
• MCP servers：放在 .mcp.json，連線外部工具和服務。
• LSP servers：放在 .lsp.json，提供程式碼跳轉、引用、診斷等精確程式碼感知。
• Monitors：放在 monitors/monitors.json，後臺監聽日誌、檔案或外部狀態。
• bin/：放可執行工具，給 Bash tool 增加命令。
• Output styles：放在 output-styles/，自定義 Claude 輸出風格。
• Themes：放在 themes/，自定義介面主題。
• Default settings：放在 settings.json，外掛啟用時應用預設設定。

你不需要每個外掛都塞滿。一個好外掛往往只圍繞一個工作流打包。

為什麼 Plugin 是"容器"不是"功能"：Skills / Hooks / MCP 各自獨立時是單點能力，但真實工作流裡它們經常聯動——比如"PR 審查" 這一件事 = Skill（流程）+ SubAgent definition（安全審查員角色）+ MCP server（GitHub 資料）+ Hook（提交前最後一道檢查）。如果只能單獨裝這幾樣，團隊成員要手動裝 4 處、4 個版本各自維護——很快失控。Plugin 把這幾樣作為一組打包 + 一起更新 + 一起解除安裝，解決"散裝能力的版本一致性" 問題。這跟 npm 包的設計哲學一樣——不是創造新能力，是給已有能力提供分發包裝。

比如“PR 審查外掛”可以包含：

• skills/review-pr/：審查流程。
• agents/security-reviewer.md：安全審查子代理。
• .mcp.json：GitHub MCP server。
• hooks/hooks.json：審查結束前檢查是否輸出風險清單。

4. 目錄結構：只有 manifest 進 .claude-plugin/

Plugin 最容易寫錯的是目錄。

官方 reference 反覆強調：.claude-plugin/ 目錄裡放 manifest；其他元件放在外掛根目錄，不要塞進 .claude-plugin/ 裡面。

一個標準結構大概這樣：

team-review-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── review-pr/
│       └── SKILL.md
├── agents/
│   └── security-reviewer.md
├── hooks/
│   └── hooks.json
├── bin/
│   └── review-helper
├── .mcp.json
├── .lsp.json
└── settings.json

錯誤寫法是這樣：

team-review-plugin/
└── .claude-plugin/
    ├── plugin.json
    ├── skills/
    ├── agents/
    └── hooks/

第二種會導致元件載入不到。

5. plugin.json：正式分發時別省

.claude-plugin/plugin.json 是外掛 manifest。官方 reference 裡有一個細節：manifest 可以省略；如果省略，Claude Code 會按預設位置自動發現元件，並從目錄名推導外掛名。

但教程裡不建議你省。

正式分發時，至少寫清：

{
  "name": "team-review-plugin",
  "description": "Team code review workflows for Claude Code",
  "version": "1.0.0",
  "author": {
    "name": "Your Team"
  }
}

欄位怎麼理解：

版本欄位要特別小心。

如果你寫了 version，使用者只有在你 bump 版本號後才會更新。如果你沒寫 version，並且透過 git 分發，Claude Code 會用 commit SHA 判斷版本，每次 commit 都會被視為新版本。

6. 名稱空間：外掛生態能長大的關鍵

假設你裝了兩個外掛：

• commit-commands
• release-commands

它們都提供一個 publish Skill。如果沒有名稱空間，/publish 會衝突。

Plugin 的處理方式是：用外掛名做字首。

/commit-commands:publish
/release-commands:publish

這就是為什麼 plugin.json 裡的 name 不只是展示名。它會進入命令識別符號、Skill 名稱和使用者呼叫習慣。

7. LSP 外掛：給 Claude 精確程式碼感知

LSP（Language Server Protocol）就是 VS Code 那套“跳轉定義、找引用、看型別錯誤”的底層協議。

Claude Code 的官方 marketplace 裡已經有常見語言的 LSP 外掛，比如 TypeScript、Python、Rust、Go、Java 等。安裝後，如果本機有對應 language server binary，Claude 就能在編輯後更快看到診斷、型別錯誤、缺失 import。

這不是讓 Claude “更聰明”，而是讓 Claude 少靠猜：

• 沒有 LSP 時，它要靠搜尋和上下文推斷函式定義；有 LSP 後，可以跳轉定義。
• 沒有 LSP 時，型別錯誤常常要等測試或編譯才暴露；有 LSP 後，編輯後就能收到診斷。
• 沒有 LSP 時，大專案裡容易漏引用；有 LSP 後，可以查 references。
• 沒有 LSP 時，對動態生成程式碼更吃力；有 LSP 後，能拿到語言伺服器的結構化資訊。

自己寫 LSP 外掛時，用 .lsp.json：

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

8. Marketplace：先加市場，再裝外掛

Plugin 是包，Marketplace 是目錄。

官方 Discover plugins 文件裡，marketplace 的流程是兩步：

1. 先新增 marketplace，讓 Claude Code 知道有哪些外掛可瀏覽。
2. 再從 marketplace 裡安裝某個具體 plugin。

官方 Anthropic marketplace claude-plugins-official 現在會自動可用。你可以在 Claude Code 裡執行：

/plugin

進入 Discover tab 瀏覽，也可以直接裝：

/plugin install github@claude-plugins-official

如果要加一個自定義 marketplace：

/plugin marketplace add anthropics/claude-code
/plugin marketplace add https://gitlab.com/company/plugins.git
/plugin marketplace add ./my-marketplace

安裝外掛：

/plugin install plugin-name@marketplace-name

安裝後當前會話裡要重新載入：

/reload-plugins

9. 安裝作用域：個人、專案、本地、管理員

同一個外掛裝在哪裡，影響完全不同：

• User：影響你所有專案，適合個人常用外掛。
• Project：影響這個儲存庫的所有協作者，適合團隊統一工具鏈。
• Local：隻影響你在這個儲存庫的本機配置，適合臨時實驗。
• Managed：由管理員下發，適合企業強制外掛。

命令列預設裝到 user scope：

/plugin install plugin-name@marketplace-name

專案級安裝會寫入 .claude/settings.json 的 enabledPlugins，所以 clone 這個儲存庫的人會看到同樣的外掛要求：

claude plugin install formatter@your-org --scope project

團隊 marketplace 也可以寫進 .claude/settings.json：

{
  "extraKnownMarketplaces": {
    "my-team-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

10. 安全：Plugin 是高信任元件

外掛不是普通文件。

官方安全提示很直接：Plugins 和 marketplaces 是 high-trust components，可以用你的使用者許可權在機器上執行任意程式碼。Anthropic 不會替你驗證第三方外掛裡的 MCP server、指令碼、檔案和外部軟體是否可信。

所以安裝前至少看四件事：

• 來源：marketplace 和 plugin repo 是誰維護的。
• 程式碼：hooks/、bin/、.mcp.json 有沒有危險命令或外部連線。
• 許可權：外掛是否要求過寬能力。
• 更新：是否自動更新，版本是否可追蹤。

尤其要看 bin/ 和 hooks。因為 bin/ 會被加到 Bash tool 的 PATH 裡，hooks 又會在事件點自動執行。它們很方便，也最需要信任。

新手最常見的兩類失控：

1. 看 marketplace 像 App Store 裝一堆：marketplace 給的體驗跟手機商店像，但底層完全不同——手機 App 跑在沙箱裡，外掛跑在你的 Claude Code session 許可權裡（繼承你登入的 GitHub / Cloud / 資料庫等所有訪問能力）。修復方式：每裝一個外掛，至少看一下它的 bin/ 和 hooks/——這兩類是真正能"代你執行"的程式碼。
2. 把 Plugin 當個人配置儲存庫：把所有 Skill、所有 Hook、個人主題、shell 別名全打進一個"my-claude-config" Plugin——結果別人裝了反而被強制改成你的工作風格。修復方式：Plugin 應該圍繞單一可複用工作流打包（"PR 審查"、"合規審計"），不是個人 dotfiles。個人偏好放 ~/.claude/ 不進 Plugin。

11. 快取和路徑：安裝後不是原地執行

還有一個容易踩的工程細節：外掛安裝後會被複制到本地版本化 cache，位置在 ~/.claude/plugins/cache。

這帶來兩個後果。

第一，外掛不能隨便用 ../shared-utils 引用目錄外檔案。安裝時只會複製外掛目錄本身，外面的檔案不會跟著走。

第二，如果你真的需要共享外部工具，可以在外掛目錄內放 symlink。官方 reference 說 symlink 會保留，並在執行時指向目標。

12. 把 12 篇串起來

現在可以回看整組 Claude Code 理解篇。

flowchart TB
    Local["01 位置<br/>AI 在你的電腦裡"]
    Context["02 上下文<br/>AI 當前能看到什麼"]
    Memory["03 記憶<br/>跨會話保留什麼"]
    Commands["04 命令<br/>你怎麼發起動作"]
    Thinking["05 思考<br/>問題要想多深"]
    Skills["06 Skills<br/>複用任務能力"]
    Subagents["07 SubAgents<br/>隔離旁支任務"]
    Teams["08 Agent Teams<br/>多會話協作"]
    MCP["09 MCP<br/>連線外部系統"]
    Hooks["10 Hooks<br/>確定性檢查點"]
    Permissions["11 Permissions<br/>訪問邊界"]
    Plugins["12 Plugins<br/>打包和分發"]

    Local --> Context --> Memory
    Memory --> Commands --> Thinking
    Thinking --> Skills
    Skills --> Subagents --> Teams
    Skills --> MCP
    MCP --> Hooks
    Hooks --> Permissions
    Permissions --> Plugins
    Skills --> Plugins
    Subagents --> Plugins
    MCP --> Plugins
    Hooks --> Plugins

    style Plugins fill:#fef3c7,stroke:#f59e0b,stroke-width:2px

這 12 篇不是功能清單，而是一條生長線：

• 執行位置，01：Claude Code 為什麼能碰你的專案。
• 感知，02-03：它當前看見什麼，長期記住什麼。
• 互動，04-05：你怎麼給任務，它怎麼決定想多深。
• 能力，06-09：任務流程、分身、團隊、外部系統怎麼接入。
• 保障，10-11：關鍵動作怎麼自動檢查，邊界怎麼管。
• 分發，12：好用的組合怎麼傳給別人。

13. 本章自檢

試著用自己的話回答：

1. Standalone 配置和 Plugin 的分界線是什麼？什麼時候不該急著做外掛？對應 §2。
2. 為什麼 .claude-plugin/ 裡只放 manifest，元件要放在外掛根目錄？對應 §4。
3. version 寫在 plugin.json 裡有什麼更新後果？對應 §5。
4. Marketplace 為什麼要分"新增市場"和"安裝外掛"兩步？對應 §8。
5. 動手題 ⭐：列出你 ~/.claude/ 下當前所有 standalone 配置（Skills / Hooks / MCP servers）。判斷：哪些只對你個人 / 單專案有用——留在 standalone；哪些會被另一個專案或同事複用——可以打成 Plugin。如果你只數出 0-1 條該 Plugin 的，證明你還在 standalone 階段——別為了"看起來工程化"提前打包。對應 §2。

官方資料

• Plugins
• Plugin marketplaces

接下來去哪

如果只記一個判斷：Plugin 的價值不是讓 Claude Code 多一個孤立功能，而是把穩定、可複用、可審查的工作流變成別人也能安裝和更新的能力包。