---
title: "12 · 怎麼給 AI 裝外掛"
description: "Claude Code Plugin 不是單個新功能，而是把 Skills、Agents、Hooks、MCP、LSP、主題和監控打包成可安裝、可更新、可分發的能力包。"
canonical: "https://xiangyugongzuoliu.com/tag/claude-code"
verifiedAt: "2026-05-08"
---

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

> [!NOTE]
> **這一篇用 15 分鐘換什麼**：前 11 篇講了 Claude Code 的位置、上下文、記憶、命令、思考、Skills、SubAgents、Agent Teams、MCP、Hooks 和 Permissions。最後這一篇講 Plugins：怎麼把這些能力裝進一個包裡，給自己、團隊或社群複用。

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

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

你有：

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

然後同事問：

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

你會發現麻煩來了。

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

> [!IMPORTANT]
> **第一性原理**：Plugin 解決的不是“Claude Code 有沒有某個能力”，而是“這些能力怎麼被打包、安裝、隔離、更新和分發”。

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

## 2. Standalone 和 Plugin 的分界線

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

| 你在做什麼 | 更適合 |
|------|------|
| 給當前專案寫一條規則 | `.claude/` 或 `CLAUDE.md` |
| 試驗一個臨時 Hook | `.claude/settings.local.json` |
| 寫一個只給自己用的 Skill | standalone Skill |
| 同一套能力要給多個專案用 | Plugin |
| 要給同事一鍵安裝 | Plugin |
| 要走 marketplace 分發和更新 | Plugin |

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

```mermaid
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
```

> [!TIP]
> **判斷標準**：只給一個專案用，先別打包；要被第二個專案複用，就開始考慮 Plugin；要給別人安裝，就必須考慮 Plugin。

## 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`：審查結束前檢查是否輸出風險清單。

> [!WARNING]
> **新手坑**：不要把所有個人偏好都打進一個“萬能外掛”。Plugin 應該圍繞可複用任務組織，不是把你的整個電腦配置搬給別人。

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

Plugin 最容易寫錯的是目錄。

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

一個標準結構大概這樣：

```text
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
```

錯誤寫法是這樣：

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

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

> [!IMPORTANT]
> **一句話記住**：`.claude-plugin/` 是身份證夾，不是工具箱本體。工具本體放外掛根目錄。

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

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

但教程裡不建議你省。

正式分發時，至少寫清：

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

欄位怎麼理解：

| 欄位 | 作用 |
|------|------|
| `name` | 外掛唯一標識，也是 skill 名稱空間字首 |
| `description` | `/plugin` 管理介面裡展示給使用者看 |
| `version` | 控制使用者什麼時候收到更新 |
| `author` | 作者歸屬 |
| `homepage` / `repository` / `license` | 分發和信任資訊 |

版本欄位要特別小心。

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

> [!CAUTION]
> **釋出坑**：不要在 `plugin.json` 和 marketplace entry 裡同時維護兩個版本號。官方說明裡 `plugin.json` 的 version 會優先，舊 manifest 版本可能會讓 marketplace 裡的新版本失效。

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

假設你裝了兩個外掛：

- `commit-commands`
- `release-commands`

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

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

```text
/commit-commands:publish
/release-commands:publish
```

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

> [!TIP]
> **命名原則**：外掛名要短、穩定、可讀。不要把版本、團隊臨時專案名、日期塞進 `name`。版本放 `version`，來源放 marketplace。

## 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`：

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

> [!IMPORTANT]
> **邊界**：LSP 外掛通常不自帶 language server binary。使用者機器上仍然要先裝好 `gopls`、`pyright-langserver`、`rust-analyzer` 這類二進位制，否則外掛會報 `Executable not found in $PATH`。

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

Plugin 是包，Marketplace 是目錄。

官方 [Discover plugins](https://code.claude.com/docs/en/discover-plugins) 文件裡，marketplace 的流程是兩步：

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

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

```text
/plugin
```

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

```text
/plugin install github@claude-plugins-official
```

如果要加一個自定義 marketplace：

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

安裝外掛：

```text
/plugin install plugin-name@marketplace-name
```

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

```text
/reload-plugins
```

> [!TIP]
> **別混淆**：新增 marketplace 不等於安裝外掛。新增只是把“應用商店”放進來，安裝才是把具體 app 下載到本機。

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

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

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

命令列預設裝到 user scope：

```text
/plugin install plugin-name@marketplace-name
```

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

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

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

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

> [!WARNING]
> **團隊規則別放錯**：團隊必須共享的外掛用 project scope；你個人喜歡的輸出風格、主題和實驗外掛不要寫進專案級配置。

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

外掛不是普通文件。

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

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

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

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

> [!CAUTION]
> **不要把陌生外掛當主題包裝**：一個主題外掛也可能帶指令碼，一個 LSP 外掛也可能要求本機二進位制。外掛安裝前要按程式碼資產審查，不是按 UI 外掛審查。

**新手最常見的兩類失控**：

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 會保留，並在執行時指向目標。

| 寫法 | 結果 |
|------|------|
| `../shared-utils/script.sh` | 安裝後大機率找不到 |
| `./scripts/helper.sh` | 正常，檔案在外掛目錄內 |
| `./shared-utils -> /path/to/shared-utils` | 可用，但要確認目標機器也有該路徑 |

> [!IMPORTANT]
> **分發原則**：外掛應該儘量自包含。依賴外部檔案越多，別人安裝成功率越低。

## 12. 把 12 篇串起來

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

```mermaid
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**：好用的組合怎麼傳給別人。

> [!TIP]
> **一句話理解全系列**：Claude Code 不是單個“會寫程式碼的聊天框”，而是一套把本機上下文、任務能力、外部工具、安全邊界和團隊分發組合起來的 Agent 執行環境。

## 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。

> [!IMPORTANT]
> **過關標準**：你能把一個已有 `.claude/` 配置拆成外掛結構，並能解釋哪些東西該打包，哪些東西應該留在本機 local scope。

<details id="glossary">
<summary><b>本篇術語速查表</b></summary>

- **Plugin**：外掛，Claude Code 可安裝、可更新、可分發的能力包。
- **Manifest**：清單檔案，`.claude-plugin/plugin.json`，描述外掛身份和元資訊。
- **Marketplace**：外掛市場，`.claude-plugin/marketplace.json` 描述的一組外掛目錄。
- **Skill namespace**：Skill 名稱空間，`/plugin-name:skill-name` 這種防衝突字首。
- **LSP**：語言伺服器協議，給 Claude 提供跳轉定義、引用、診斷等程式碼智慧。
- **Monitor**：後臺監控，外掛裡持續監聽日誌、檔案或外部狀態的配置。
- **Scope**：安裝作用域，外掛安裝到 user、project、local 或 managed 層級。
- **Cache**：外掛快取，安裝後複製到 `~/.claude/plugins/cache` 的本地副本。
- **`enabledPlugins`**：已啟用外掛，專案級 settings 中記錄共享外掛的配置項。
- **`extraKnownMarketplaces`**：額外市場，專案級 settings 中宣告團隊 marketplace 的配置項。

</details>

## 官方資料

- [Plugins](https://code.claude.com/docs/en/plugins)
- [Plugin marketplaces](https://code.claude.com/docs/en/plugin-marketplaces)

## 接下來去哪

<Cards>
  <Card href="/zh-Hant/docs/claude-code" title="回到 Claude Code 教程總覽" description="從總覽頁重新選擇官方教程中文版或深度理解路徑。" />
  <Card href="/zh-Hant/docs/claude-code/understanding/11-permissions" title="11 · 該給 AI 多少許可權（上一篇）" description="安裝外掛前先懂許可權邊界：外掛是高信任元件，不要把陌生外掛當普通配置。" />
  <Card href="/zh-Hant/docs/claude-code/understanding/06-command-files" title="06 · 怎麼複用技能" description="Plugin 最常打包的就是 Skills。分不清 Skill 和 Plugin 時，回到這一篇。" />
</Cards>

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