---
title: "檢視擴充套件能力地圖"
description: "Claude Code 擴充套件不是越多越好。用一張決策地圖分清 CLAUDE.md、Rules、Skills、MCP、Subagents、Hooks、Commands、Plugins 和 Agent SDK。"
canonical: "https://xiangyugongzuoliu.com/tag/claude-code"
verifiedAt: "2026-05-05"
---

Claude Code 的擴充套件層不是一堆可選外掛，而是接在 agent loop 不同位置的能力。你要先知道問題屬於“記憶、流程、工具、隔離、自動化、分發、產品化”哪一類，再決定加哪一層。——Aaron

> [!NOTE]
> **這一章用 14 分鐘換什麼**：前一組已經講完 settings、permissions、memory 和 MCP。現在進入擴充套件與自動化。讀完你應該能在遇到重複提示詞、上下文汙染、外部系統、強制動作、多儲存庫複用和 SDK 產品化時，選對擴充套件點，而不是把所有問題都塞進 `CLAUDE.md`。

## 1. 先看總圖：擴充套件接在 agent loop 的不同位置

Claude Code 的核心是 agentic loop：理解任務、讀檔案、呼叫工具、執行命令、改程式碼、彙報結果。

擴充套件能力不是替代這個 loop，而是在不同位置增強它：

- `CLAUDE.md`：會話開始時載入，讓 Claude 每次都知道專案約定。
- `.claude/rules/`：把規則按路徑、語言、目錄拆開，避免根檔案過長。
- Skills：按需載入知識、參考資料和可呼叫工作流。
- MCP：連線外部系統、資料庫、API、設計稿、監控和業務工具。
- Subagents：把子任務放到隔離上下文，最後只把摘要帶回主會話。
- Agent teams：多個獨立 Claude Code 會話協同，適合更復雜的並行任務。
- Hooks：生命週期事件觸發指令碼、HTTP 請求、prompt 或 subagent。
- Commands：會話內的 `/` 命令，包括內建命令、bundled skills 和 MCP prompts。
- Plugins：把 skills、hooks、subagents、MCP servers 打包分發。
- Agent SDK：把 Claude Code 的 agent loop 嵌入自己的程式或平臺。

```mermaid
flowchart TD
    User["使用者任務"]
    Context["會話上下文"]
    Agent["Claude Code agent loop"]
    Tools["內建工具"]
    External["外部系統"]
    Automation["自動化事件"]
    Package["可分發能力"]
    Product["產品或後臺服務"]

    ClaudeMd["CLAUDE.md / Rules"]
    Skills["Skills"]
    MCP["MCP"]
    Subagents["Subagents / Agent teams"]
    Hooks["Hooks"]
    Commands["Commands"]
    Plugins["Plugins"]
    SDK["Agent SDK"]

    User --> Context
    ClaudeMd --> Context
    Skills --> Context
    Context --> Agent
    Commands --> Agent
    Agent --> Tools
    Agent --> Subagents
    Agent --> MCP
    MCP --> External
    Agent --> Automation
    Hooks --> Automation
    Skills --> Package
    Subagents --> Package
    Hooks --> Package
    MCP --> Package
    Package --> Plugins
    Agent --> Product
    SDK --> Product

    style ClaudeMd fill:#e0f2fe,stroke:#0284c7,stroke-width:2px
    style Skills fill:#dcfce7,stroke:#22c55e,stroke-width:2px
    style MCP fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
    style Hooks fill:#fee2e2,stroke:#ef4444,stroke-width:2px
```

> [!IMPORTANT]
> **第一性原理**：擴充套件不是按功能名選擇，而是按“這件事應該什麼時候載入、誰觸發、是否強制、是否隔離、是否分發”選擇。

## 2. 一句話決策

遇到擴充套件需求，先用這組判斷：

- Claude 第二次忘記同一條專案約定：寫進 `CLAUDE.md`。
- 規則只對某些目錄、語言或檔案型別生效：寫進 `.claude/rules/`。
- 同一段提示詞或流程第三次手打：做成 Skill。
- Claude 需要訪問外部系統：接 MCP。
- 子任務會讀很多檔案，但主會話只需要結論：用 Subagent。
- 多個獨立 Claude Code 會話需要協作：用 Agent team。
- 某個動作必須每次發生：寫 Hook。
- 會話裡要快速切換、管理、執行流程：用 Command。
- 多儲存庫或團隊要複用整套能力：打包 Plugin。
- 你要把 Claude Code 做進產品或後臺服務：用 Agent SDK。

> [!TIP]
> **預設順序**：先從 `CLAUDE.md` 和 Skills 開始。不要為了“架構完整”提前上 Plugin 或 SDK。

## 3. 決策流程：先問五個問題

```mermaid
flowchart TD
    Need["我想擴充套件 Claude Code"]
    Always["每次會話都應該知道？"]
    Path["只對部分路徑生效？"]
    Repeat["是不是可複用流程？"]
    External["需要外部系統？"]
    Isolate["需要隔離上下文？"]
    Force["必須確定性執行？"]
    Share["要跨儲存庫分發？"]
    Product["要嵌入產品？"]

    ClaudeMd["CLAUDE.md"]
    Rules[".claude/rules/"]
    Skill["Skill"]
    MCP["MCP"]
    Subagent["Subagent"]
    Hook["Hook"]
    Plugin["Plugin"]
    SDK["Agent SDK"]

    Need --> Always
    Always -->|是| Path
    Path -->|是| Rules
    Path -->|否| ClaudeMd
    Always -->|否| Repeat
    Repeat -->|是| Skill
    Repeat -->|否| External
    External -->|是| MCP
    External -->|否| Isolate
    Isolate -->|是| Subagent
    Isolate -->|否| Force
    Force -->|是| Hook
    Force -->|否| Share
    Share -->|是| Plugin
    Share -->|否| Product
    Product -->|是| SDK
    Product -->|否| Skill

    style ClaudeMd fill:#e0f2fe,stroke:#0284c7,stroke-width:2px
    style Skill fill:#dcfce7,stroke:#22c55e,stroke-width:2px
    style Hook fill:#fee2e2,stroke:#ef4444,stroke-width:2px
```

這個流程不是絕對規則，但足夠處理大多數新手場景。

> [!WARNING]
> **不要把所有問題都歸到 prompt**：prompt 能提醒，但不能保證執行；prompt 能裝知識，但會佔上下文；prompt 能描述工具，但不能替代連線。

## 4. `CLAUDE.md`：每次會話都要知道的專案常識

`CLAUDE.md` 的定位是 always-on context。

適合放：

- 專案結構。
- 構建、測試、釋出命令。
- 程式碼風格和命名約定。
- 生成檔案不要手改。
- 關鍵目錄的職責。
- 團隊每次都要遵守的工作方式。

不適合放：

- 一次性任務背景。
- 長篇 API 文件。
- 可複用 checklist 的完整正文。
- 只對一個目錄生效的細規則。
- 金鑰、token、賬號。
- 許可權邊界。

如果根 `CLAUDE.md` 超過 200 行，通常已經開始混入參考資料或流程細節。官方建議把參考內容移到 Skills，把路徑相關規則拆到 `.claude/rules/`。

> [!IMPORTANT]
> **CLAUDE.md 不是知識庫入口頁**：它只裝每次會話都值得進入上下文的少量規則。

## 5. `.claude/rules/`：把規則按路徑拆開

Rules 解決的是“不是所有規則都應該全域性載入”的問題。

適合放：

- `src/api/**` 的介面規範。
- `db/migrations/**` 的資料庫遷移規範。
- `docs/**` 的文件寫作規範。
- `*.test.ts` 的測試規則。
- `packages/mobile/**` 和 `packages/web/**` 的差異規則。

帶 `paths` frontmatter 的 rule 只在 Claude 處理匹配檔案時載入。

```md
---
paths:
  - "src/api/**/*.ts"
---

## API Rules

- Validate input before business logic.
- Use the shared error response shape.
- Update API docs when adding endpoints.
```

> [!TIP]
> **判斷標準**：如果一條規則只在某些檔案裡有意義，放 rules，不要放根 `CLAUDE.md`。

## 6. Skills：把知識和工作流做成按需能力

Skills 是官方擴充套件層裡最靈活的一類。一個 Skill 本質上是一個 Markdown 檔案，裡面包含說明、參考資料、流程和可選指令碼。

適合放：

- 釋出流程。
- 程式碼審查 checklist。
- API 風格指南。
- 排障 playbook。
- 資料庫查詢模式說明。
- 多步遷移流程。
- 需要 Claude 自己判斷如何應用的經驗。

Skills 可以由使用者顯式呼叫，也可以由 Claude 根據描述自動載入。官方還說明 Claude Code 的 skills 相容 Agent Skills open standard，並在此基礎上擴充套件了 invocation control、subagent execution 和 dynamic context injection。

> [!IMPORTANT]
> **Skill 是能力，不是強制邊界**：它告訴 Claude 怎麼做一件事，但不能保證某個動作必定發生，也不能阻止工具呼叫。

## 7. Skill 與 `CLAUDE.md` 的區別

這兩個最容易混。

`CLAUDE.md` 適合：

- 每次會話都要知道。
- 專案核心約定。
- 簡短穩定。
- 不需要使用者顯式呼叫。

Skill 適合：

- 只在某類任務需要。
- 內容較長。
- 有步驟、有參考資料、有例子。
- 可以透過 `/skill-name` 呼叫。

判斷句：

- “Claude 每次都必須知道這條規則”放 `CLAUDE.md`。
- “Claude 做這個任務時才需要這份資料”放 Skill。
- “這是一套可複用動作流程”放 Skill。

> [!WARNING]
> **不要把 Skill 當隱形全域性規則**：如果任務沒有觸發它，Claude 可能不會載入。必須每次都知道的內容不要只放 Skill。

## 8. MCP：連線外部系統，不是裝知識

MCP 解決的是外部連線問題。

適合用 MCP：

- GitHub issue / PR。
- Jira / Linear。
- Sentry / Statsig。
- PostgreSQL / 資料倉儲。
- Figma / Notion / 內部文件。
- Slack / Gmail / 內部 API。
- 瀏覽器、桌面、業務工具。

MCP 給 Claude “能訪問什麼”。Skill 可以告訴 Claude “怎麼正確使用這些訪問能力”。這兩者經常配合。

示例：

- MCP 連線資料庫。
- Skill 記錄業務表結構、常見查詢、危險查詢邊界。
- permissions 限制只能執行只讀查詢工具。

> [!CAUTION]
> **MCP 會擴大外部訪問面**：接入前先確認 server 來源、OAuth scope、token 許可權、輸出大小和 permissions。

## 9. Subagents：隔離上下文裡的專門 worker

Subagent 適合把一個子任務隔離出去，讓它自己讀檔案、搜尋、驗證，最後只把結論返回主會話。

適合：

- 程式碼庫探索。
- 安全審查。
- 並行方案比較。
- 大量檔案閱讀。
- 專門領域 worker。
- 主會話不需要保留中間過程的任務。

不適合：

- 需要你即時逐步決策的任務。
- 必須連續編輯同一批檔案的主路徑任務。
- 子任務結果會立刻影響下一步，且你不能等摘要。
- 只是為了“看起來更自動化”的簡單任務。

官方說明：Subagent 有自己的上下文視窗，結果以摘要返回。它不會繼承主會話的完整歷史，也不會自動繼承主會話中已呼叫的 skills；需要顯式指定。

> [!TIP]
> **使用標準**：如果中間過程會汙染主上下文，而主會話只需要結論，用 Subagent。

## 10. Agent teams：多個獨立會話協作

Agent teams 比 Subagents 更重。

Subagent 是主會話管理的隔離 worker。Agent team 是多個獨立 Claude Code session 之間協作，適合需要互相溝通、共享任務、並行推進的複雜工作。

適合：

- 多假設研究。
- 大型功能拆分。
- 多維程式碼審查。
- 需要角色之間互相質詢的任務。

不適合：

- 單檔案修改。
- 簡單調研。
- 主線已經很清晰的實現任務。
- 你還沒有穩定的本地流程。

官方說明 Agent teams 仍屬於更高階的協作形態，使用前要理解它比 Subagent 更消耗 token，也更需要協調規則。

> [!WARNING]
> **不要把 Agent team 當預設並行按鈕**：先用普通 Subagent 解決隔離問題；只有需要多個獨立會話溝通時再升級。

## 11. Hooks：必須發生的自動化

Hooks 解決的是“這件事不能只靠 Claude 記得”的問題。

適合：

- `PreToolUse` 阻止危險命令。
- `PostToolUse` 編輯後執行 formatter 或 linter。
- `UserPromptSubmit` 注入執行環境資訊。
- `SessionStart` 初始化上下文。
- `Stop` 或 `SessionEnd` 發通知、寫日誌、收尾。
- permission 事件上做額外審批。

Hook 可以執行：

- shell command。
- HTTP request。
- LLM prompt。
- subagent。

Skill 和 Hook 的區別很重要：

- Skill 是 Claude 讀取並應用的工作流。
- Hook 是事件發生時確定性觸發的自動化。

> [!IMPORTANT]
> **強制動作要用 Hook**：例如阻止 `rm -rf /`、編輯後跑格式化、會話結束髮通知。這些不要只寫在 prompt 或 Skill 裡。

## 12. Commands：會話內的控制入口

Commands 是你在 Claude Code 會話裡輸入 `/` 看到的命令體系。

它包含三類：

- 內建命令：行為由 CLI 實現，比如 `/mcp`、`/memory`、`/permissions`、`/compact`。
- Bundled skills：官方打包的 skills，比如 `/debug`、`/batch`、`/simplify` 等，具體可用性取決於版本、平臺和賬號。
- MCP prompts：MCP server 暴露的 prompt 會顯示為 slash command。

命令只在訊息開頭識別，命令後面的文本會作為引數傳入。

常見用途：

- 管理上下文：`/compact`、`/clear`、`/context`。
- 管理配置：`/config`、`/permissions`、`/memory`。
- 管理外部連線：`/mcp`、`/plugin`。
- 執行工作流：bundled skills 或自定義 skills。

> [!TIP]
> **Commands 是入口，不是另一套能力模型**：很多命令背後其實是 settings、memory、MCP、skills 或 CLI 內建邏輯。

## 13. Plugins：把穩定能力打包分發

Plugin 是 packaging layer。官方說明 plugin 可以打包：

- Skills。
- Hooks。
- Subagents。
- MCP servers。
- Commands。
- 其他配置元件。

適合：

- 多儲存庫複用同一套 skills。
- 團隊統一安裝 hooks 和 MCP。
- 內部平臺分發標準能力。
- 透過 marketplace 給外部使用者安裝。

不適合：

- 還在頻繁改的個人實驗。
- 單專案專用規則。
- 沒有文件、版本、相容邊界的指令碼集合。

Plugin skills 會 namespace，例如 `/my-plugin:review`，這樣多個 plugin 的同名能力可以共存。

> [!WARNING]
> **不要過早 Plugin 化**：先在一個專案裡把 Skill、Hook、MCP 跑穩，再打包。否則你只是把不穩定擴散到更多儲存庫。

## 14. Agent SDK：把 agent loop 嵌到程式裡

Agent SDK 是產品化和服務化入口，不是普通專案的第一步。

適合：

- 自己的 CLI。
- 後臺自動化服務。
- 內部平臺。
- CI / review agent。
- Web app 裡的 coding agent。
- 自定義許可權、hooks、MCP、subagents 的程式化編排。

不適合：

- 你還沒在 Claude Code CLI 跑通流程。
- 需求只是寫一份提示詞。
- 只是想少敲一個命令。
- 沒有日誌、錯誤處理、許可權和釋出邊界。

官方 Agent SDK 支援用程式碼執行 agent loop，並配置 MCP、hooks、permissions、subagents、slash commands、skills 和 plugins。

> [!IMPORTANT]
> **先 CLI，後 SDK**：互動流程沒跑通前，不要急著把不確定性寫進程式碼。

## 15. 上下文成本：擴充套件不是免費的

每個擴充套件都會以不同方式影響上下文。

- `CLAUDE.md`：啟動時載入全文，每次請求都帶著。
- Rules：無 `paths` 的啟動載入；有 `paths` 的按檔案觸發。
- Skills：預設啟動時載入名稱和描述，使用時載入全文；手動-only skill 可以降低啟動成本。
- MCP：啟動時載入 tool names；Tool Search 預設延遲載入完整 schema。
- Subagents：隔離上下文，不汙染主會話，但仍然消耗自己的 token。
- Hooks：預設不進上下文；只有返回輸出時才會進入會話。
- Plugins：取決於它打包了哪些元件。

> [!CAUTION]
> **上下文噪音會降低質量**：擴充套件越多，不一定越強。真正有效的 setup 是“少量穩定規則 + 按需載入的能力 + 清晰的許可權邊界”。

## 16. 載入和覆蓋規則也不同

不同擴充套件的合併方式不一樣。

- `CLAUDE.md` 是 additive：多個層級都會進入上下文，衝突需要 Claude 自己判斷。
- Skills 按名稱覆蓋：不同 scope 同名時會按優先順序選一個。
- Subagents 按名稱覆蓋：scope 和 CLI flag 會影響最終定義。
- MCP server 按名稱覆蓋：local 優先於 project，project 優先於 user。
- Hooks 是 merge：匹配同一事件的 hooks 都會觸發。
- Plugin skills 會 namespace：降低同名衝突。

這解釋了很多排障現象：

- 你改了 project MCP，但 local 同名 server 仍然生效。
- 你寫了多個 hook，它們不是互相覆蓋，而是都執行。
- 你以為下層 `CLAUDE.md` 覆蓋了上層，其實兩份都在上下文裡。

> [!TIP]
> **排障先問載入模型**：是 additive、override、merge，還是 namespace？先搞清楚這個，再看具體檔案。

## 17. 常見組合方式

實際專案通常不是單獨用一個擴充套件，而是組合。

`CLAUDE.md` + Skills：

- `CLAUDE.md` 放核心規則。
- Skill 放長參考資料和流程。
- 適合 API 風格、釋出流程、程式碼審查。

Skill + MCP：

- MCP 提供外部連線。
- Skill 教 Claude 如何正確使用這些連線。
- 適合資料庫、Sentry、GitHub、Slack。

Skill + Subagent：

- Skill 定義審查流程。
- Subagent 隔離執行審查。
- 適合安全、效能、測試覆蓋。

Hook + MCP：

- Hook 在事件發生時觸發。
- MCP 把結果發到外部系統。
- 適合通知、審計、同步狀態。

Plugin + 以上全部：

- 把穩定能力打包給多個儲存庫。
- 適合團隊標準化。

> [!IMPORTANT]
> **組合的前提是職責清楚**：不要讓 `CLAUDE.md`、Skill、Hook 同時重複表達同一個規則。重複越多，衝突越難排查。

## 18. 一個專案的推薦演進順序

不要一次性把所有擴充套件上齊。推薦按觸發器演進：

1. Claude 第二次犯同一個專案級錯誤：補 `CLAUDE.md`。
2. 根規則變長或目錄差異明顯：拆 `.claude/rules/`。
3. 同一流程第三次手打：做 Skill。
4. 外部系統頻繁複制貼上：接 MCP。
5. 子任務汙染主上下文：用 Subagent。
6. 某動作必須確定性發生：寫 Hook。
7. 同一套能力要給多個儲存庫：打包 Plugin。
8. 流程已經穩定並需要產品化：上 Agent SDK。

> [!TIP]
> **擴充套件是沉澱，不是預設**：先在真實工作中出現重複，再把重複變成能力。

## 19. 新手常見坑

- 把所有專案資料都塞進 `CLAUDE.md`。
- 把一次性提示詞做成 Skill。
- 把 Skill 當許可權系統。
- 用 prompt 代替 Hook 做強制動作。
- 接太多 MCP，只為“看起來功能多”。
- Subagent 任務太模糊，最後只返回一堆不可執行摘要。
- 一開始就做 Plugin，導致每次改動都要分發。
- 過早上 Agent SDK，把互動流程的不確定性固化成程式碼。
- 忽略上下文成本，導致 Claude 反而更難選對規則。

> [!WARNING]
> **能刪掉的擴充套件才是健康擴充套件**：如果你刪掉某個擴充套件後說不清失去什麼能力，它大機率還沒必要存在。

## 20. 驗收標準

這一章學完，你應該能做到：

- 我能說清每個擴充套件點解決的問題。
- 我能判斷“規則、流程、連線、隔離、自動化、分發、產品化”分別放哪層。
- 我知道強制邊界不應該只寫在 prompt、`CLAUDE.md` 或 Skill 裡。
- 我知道 MCP 負責外部連線，Skill 負責使用方法。
- 我知道 Subagent 和 Agent team 的差別。
- 我知道 Hook 和 Skill 的差別。
- 我知道 Commands 只是會話入口，背後可能是內建邏輯、Skill 或 MCP prompt。
- 我知道 Plugin 是穩定能力的分發層，不是早期實驗容器。
- 我知道 Agent SDK 應該在 CLI 流程穩定後再用。
- 我能解釋每個擴充套件的上下文成本。

## 21. 術語速查

- `CLAUDE.md`：每次會話載入的專案說明和長期規則。
- `.claude/rules/`：可按路徑或主題拆分的規則目錄。
- `Skill`：可按需載入的知識、參考資料和工作流。
- `MCP`：連線外部工具、服務、資料庫和 API 的協議。
- `Subagent`：在隔離上下文中執行子任務的 worker。
- `Agent team`：多個獨立 Claude Code 會話組成的協作團隊。
- `Hook`：生命週期事件觸發的確定性自動化。
- `Command`：會話內以 `/` 開頭的控制入口。
- `Bundled skill`：官方隨 Claude Code 提供的 skill 命令。
- `MCP prompt`：MCP server 暴露成 slash command 的 prompt。
- `Plugin`：把 skills、hooks、subagents、MCP servers 等打包分發的元件。
- `Agent SDK`：用程式碼呼叫 Claude Code agent loop 的開發介面。
- `Tool Search`：MCP tool schema 的按需載入機制。

## 22. 官方資料

- [Extend Claude Code](https://code.claude.com/docs/en/features-overview)
- [How Claude remembers your project](https://code.claude.com/docs/en/memory)
- [Extend Claude with skills](https://code.claude.com/docs/en/skills)
- [Create custom subagents](https://code.claude.com/docs/en/sub-agents)
- [Automate workflows with hooks](https://code.claude.com/docs/en/hooks-guide)
- [Commands](https://code.claude.com/docs/en/commands)
- [Create plugins](https://code.claude.com/docs/en/plugins)
- [Agent SDK overview](https://code.claude.com/docs/en/agent-sdk/overview)

<Cards>
  <Card href="/zh-Hant/docs/claude-code/official/02-extensions-automation/skills" title="Skills" description="下一章專門講 Skills：什麼時候自動載入、什麼時候手動呼叫、怎麼組織參考資料和可複用流程。" />
  <Card href="/zh-Hant/docs/claude-code/official/01-core-capabilities/mcp" title="連線 MCP（上一篇）" description="MCP 是擴充套件地圖裡最容易擴大外部訪問面的能力。先確認 scope、OAuth、permissions 和輸出限制。" />
  <Card href="/zh-Hant/docs/claude-code/understanding/08-multi-agent" title="深度理解：多 Agent 協作" description="如果想繼續理解 Subagents 和 Agent teams 背後的協作模型，可以讀理解篇多 Agent。" />
</Cards>
