檢視擴充套件能力地圖

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

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 嵌入自己的程式或平臺。

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

2. 一句話決策

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

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

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

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

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

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

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

適合放：

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

不適合放：

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

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

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

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

適合放：

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

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

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

## API Rules

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

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。

7. Skill 與 CLAUDE.md 的區別

這兩個最容易混。

CLAUDE.md 適合：

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

Skill 適合：

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

判斷句：

• “Claude 每次都必須知道這條規則”放 CLAUDE.md。
• “Claude 做這個任務時才需要這份資料”放 Skill。
• “這是一套可複用動作流程”放 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 限制只能執行只讀查詢工具。

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

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

適合：

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

不適合：

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

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

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

Agent teams 比 Subagents 更重。

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

適合：

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

不適合：

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

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

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 是事件發生時確定性觸發的自動化。

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。

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

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

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

適合：

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

不適合：

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

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

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。

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

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

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

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 覆蓋了上層，其實兩份都在上下文裡。

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 + 以上全部：

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

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

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

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

19. 新手常見坑

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

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
• How Claude remembers your project
• Extend Claude with skills
• Create custom subagents
• Automate workflows with hooks
• Commands
• Create plugins
• Agent SDK overview