02-5 Skills / Hooks / Subagents / Plugins 機制總覽

這個單元解決什麼問題這四個機制把 Claude Code 從「會聊天的代理」變成「貼合你工作流的自動化系統」。它們常被混用：該保證一定發生的事寫成 Skill 求模型照做、該隔離的子任務塞進主上下文、該打包分發的設定靠手動複製。這個單元先給你「何時用哪一個」的判準，再逐一拆每個機制的格式、放置位置、優先序與安全邊界。深入製作留給 Part IV，這裡建立的是選型總覽。

學習目標

能說明 Skill / Hook / Subagent / Plugin 各自解決什麼問題，給一個任務能判斷該用哪一個。
能讀懂 SKILL.md 與 subagent 的 frontmatter 主要欄位。
能列出主要 Hook 事件與 handler 類型，並說出一個確定性把關的實用範例。
能從官方與社群市集安全地安裝 plugin，並知道安裝前該掃描什麼。

時效聲明機制與欄位查證截至 2026-05；Claude Code 演進快，精確欄位與事件清單以官方文件為準，製作細節見 Part IV 各專屬單元。

1. 先決定用哪一個：四機制選型

四個機制不是平行的替代品，它們回答的是不同問題。先看這張選型表，再往下讀各自細節：

你要的是	用	為什麼
一個可重用的流程，要 Claude 按步驟處理某類任務	Skill	body 隨需載入，平時只佔一行描述，省 token
一件保證一定發生的確定性動作（格式化、擋危險指令）	Hook	事件驅動、由 Claude Code 強制執行，不靠模型自覺
把一個子任務隔離到乾淨上下文（探索、審查），主代理只收結論	Subagent	獨立 context window，省主線 token 又提升品質
把上述元件打包分發給團隊或他人	Plugin	一次安裝帶齊 skills / agents / hooks / MCP

選型原則：要「保證發生」用 Hook，要「可重用流程」用 Skill，要「隔離上下文」用 Subagent，要「打包分發」用 Plugin。 它們正交但可組合，一個 plugin 可以同時帶 skill、hook 與 subagent。

最常見的選錯：把該用 Hook 的事寫成 Skill 或 CLAUDE.md「每次存檔後格式化」「禁止寫入某些路徑」這類要保證發生的事，寫進 CLAUDE.md 或 Skill 是求模型照做，模型可能漏。要它必然發生，用 Hook（見第 3 節與 01-6 的策略 vs 規則分界）。

互動選型工具

用下方工具回答幾個問題，直接給出機制建議：

2. Skills：可重用的流程

Skill 是以 SKILL.md（YAML frontmatter + Markdown 本體）定義的可重用流程。和 CLAUDE.md 開機即全文載入不同，Skill 走 progressive disclosure：session 啟動時只有它的 description 進 context，被觸發後 SKILL.md 全文才作為一條訊息載入 [1]。這讓你能裝幾十個 Skill 而不撐爆 context。 主要 frontmatter 欄位（全部 optional，只有 description 建議必填）[1]：

欄位	用途
`description`	用途與觸發時機，Claude 據此決定是否自動載入（與 `when_to_use` 合計上限 1536 字元）
`allowed-tools` / `disallowed-tools`	此 Skill 活躍期間免詢問可用 / 移除的工具
`model` / `effort`	此 Skill 活躍期間覆寫模型或 effort 等級，當輪結束恢復
`disable-model-invocation`	`true` 則 Claude 不自動載入、描述也不進 context，只能手動 `/name`
`user-invocable`	`false` 則不出現在 `/` 選單，但 Claude 仍可自動載入
`context: fork` + `agent`	在 forked subagent 裡執行，`agent` 指定 subagent 類型
`paths`	glob，僅在操作到符合路徑的檔案時才自動觸發

一個最小 SKILL.md

---
name: tidy-refs
description: 依本實驗室格式整理文獻清單。當使用者要整理參考文獻、bib 條目時觸發。
allowed-tools: Read, Edit
---

# 整理文獻
1. 讀取使用者指定的文獻檔。
2. 依 IEEE 編號制重排，三位以上作者用 et al.。
3. 缺年份的條目標記 `n.d.`（no date），不臆造。

放在 ~/.claude/skills/tidy-refs/SKILL.md（個人）或 .claude/skills/tidy-refs/SKILL.md（專案）。觸發後 Claude 才讀到這套步驟。

放置與優先序（高到低）：企業受管理（managed policy）> 個人 ~/.claude/skills/ > 專案 .claude/skills/ > plugin（plugin skill 用 plugin-name:skill-name 命名空間，不與其他層衝突）[1]。 動態 context 注入：SKILL.md 內可放會在載入前先執行、並用輸出替換的指令，讓你把即時資訊（git 狀態、日期）注入流程 [1]。行首語法如下，另也支援以三個反引號加驚嘆號起始的多行區塊：

!`git status --short`

可用 settings.json 的 disableSkillShellExecution: true 停用此行為。 與舊式 commands 的關係：.claude/commands/<name>.md 仍支援且生成同樣的 /name；與同名 Skill 衝突時 Skill 優先 [1]。Command 與 Skill 的取捨見 04-3、04-4。

3. Hooks：事件驅動的確定性把關

Hook 是掛在生命週期事件上的自訂指令。它和 Skill / CLAUDE.md 的根本差別是強制性：CLAUDE.md 是「請你遵守」，Hook 是「我來確保」。需要保證發生的事用 Hook，不要寫進指令祈禱模型照做。事件：Claude Code 截至 2026-06 有 30 個 hook 事件 [2]，總覽階段你會先用到這幾個：

事件	觸發時機	典型用途
`SessionStart`	session 開始	注入專案上下文、環境檢查
`UserPromptSubmit`	你送出 prompt 後	注入動態 context、攔截
`PreToolUse`	工具執行前	擋危險指令、改寫參數
`PostToolUse`	工具執行後	自動格式化 / lint / 型別檢查
`Stop`	回合結束	確定性收尾驗證（收斂哨兵）
`SessionEnd`	session 結束	清理、最終驗證

完整事件清單（含 PermissionRequest、SubagentStart / SubagentStop、PreCompact 等）見官方與 04-6。 handler 類型：command（執行 shell 指令 / 腳本）、http（POST 事件 JSON 到 URL）、mcp_tool（呼叫 MCP 工具）、prompt（以 LLM 評估）、agent（帶工具的 agentic verifier）[2]。協定：hook 從 stdin 收一段 JSON（含 session_id、tool_name、tool_input 等）；exit code 2 是阻擋性錯誤（stderr 顯示給 Claude、動作被擋）；exit 0 時解析 stdout 的 JSON 取得決策 [2]。PreToolUse 要擋一個工具呼叫，回傳：

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database writes not allowed"
  }
}

存檔後自動格式化的 PostToolUse hook在 settings.json 的 hooks 鍵掛一個指向腳本的 PostToolUse，matcher 用 Edit|Write：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": ".claude/hooks/format.sh" }]
      }
    ]
  }
}

hook 腳本從 stdin 的 JSON 取得被改動的檔案路徑（tool_input.file_path），對它執行 formatter。注意 Claude Code 並未提供 $CLAUDE_FILE_PATHS 這類環境變數帶路徑（截至 2026-05）[2]，路徑要從 stdin JSON 讀。

4. Subagents：隔離上下文的子代理

Subagent 是定義在 .claude/agents/*.md（YAML frontmatter + 系統提示）的子代理，用 /agents 管理。它的核心價值是上下文隔離：把探索性或大量讀取的子任務丟給一個乾淨上下文的 subagent，主代理只收最終結論，既省主線 token 又避免無關內容稀釋（呼應 01-4）[3]。 主要 frontmatter 欄位（只有 name、description 必填）[3]：

欄位	用途
`name` / `description`	識別符與「何時委派」的依據
`tools` / `disallowedTools`	工具白名單 / 黑名單；省略 `tools` 則繼承主對話全部工具
`model`	`sonnet` / `opus` / `haiku` / 完整 ID / `inherit`（預設 inherit）
`skills`	啟動時直接注入完整內容的 Skill 清單
`memory`	`user` / `project` / `local`，各對應不同的 agent-memory 目錄
`isolation`	唯一有效值 `worktree`，在臨時 git worktree 執行

放置與優先序（高到低）：受管理 > --agents CLI > 專案 .claude/agents/ > 使用者 ~/.claude/agents/ > plugin [3]。 內建 subagent：Explore（Haiku、唯讀、跳過 CLAUDE.md，用於搜尋分析）、Plan（唯讀規劃）、general-purpose（全工具、複雜多步任務）[3]。一個重要限制：subagent 不能再生成 subagent（無巢狀委派）。

一個唯讀 review subagent

---
name: kb-reviewer
description: 審查知識庫單元是否符合撰寫規格。標記單元完成前使用。
tools: Read, Grep, Glob, Bash
model: inherit
---
你是唯讀品質審查者。依 writing-spec.md 檢查語氣、全形標點、死連結、時效標註，
回傳分級問題清單，不修改任何檔案。

給它唯讀工具就是最小權限的落地。主代理委派後只收這份清單，不讓審查過程的大量讀取稀釋主上下文（完整 subagent 製作見 04-5）。

5. Plugins 與 Marketplaces：打包與分發

Plugin 把 skills / agents / hooks / MCP server 打包成一個可安裝單位，讓團隊一次裝齊一致的設定。 市集與安裝（截至 2026-05）[4]：

官方市集 claude-plugins-official 啟動時自動可用：/plugin install <name>@claude-plugins-official，瀏覽於 claude.com/plugins。
社群市集 anthropics/claude-plugins-community：先 /plugin marketplace add anthropics/claude-plugins-community，再 /plugin install <name>@claude-community。
任意市集：/plugin marketplace add owner/repo（GitHub）、Git URL 或本地路徑（該 repo 需含 .claude-plugin/marketplace.json）。

plugin 結構：根目錄的 .claude-plugin/plugin.json 是 manifest（唯一放在此目錄的檔案），元件放在外層的 skills/、agents/、commands/、hooks/hooks.json、.mcp.json、.lsp.json、monitors/monitors.json、bin/，外加 plugin 自身的 settings.json（僅 agent 與 subagentStatusLine 兩個 key 生效）[4]。官方明確警告：不要把 commands/、agents/、skills/、hooks/ 放進 .claude-plugin/ 目錄裡，只有 plugin.json 放那。完整目錄結構：

my-plugin/

.claude-plugin/

plugin.json · 唯一放這裡的檔

skills/

agents/

hooks/

commands/

.mcp.json

settings.json · 僅 agent / subagentStatusLine 生效

安裝前先掃描：plugin 與 Skill 是供應鏈資產社群 Skill / plugin 等於把別人的程式碼與指令拉進你的 agent。安裝前掃描：隱藏 Unicode（提示注入）、curl | bash 之類的外連執行、過寬的工具權限、ANTHROPIC_BASE_URL 覆寫、enableAllProjectMcpServers 自動核准。star 數高不等於安全或有維護。完整的威脅模型、掃描指令與 CVE 見 03-3，正確使用見 04-7。

工具對照

四機制在其他工具的對應參差不齊（截至 2026-05，精確機制以各官方文件為準，詳見 02-6）：

概念	Anthropic Claude（主範本）	OpenAI (Codex)	Google (Gemini CLI)	GitHub Copilot	Cursor
可重用流程（Skill / command）	`SKILL.md` + `.claude/commands/` [1]	prompt / 自訂指令（以官方文件為準）	自訂指令（以官方文件為準）	`.prompt.md`（以官方文件為準）	`.cursor/rules/*.mdc`
事件驅動 Hook	`hooks` 事件（約 30 個）[2]	以官方文件為準	以官方文件為準	以官方文件為準	無對等的 Hook 機制
子代理 / 上下文隔離	`.claude/agents/*.md` + 內建 Explore / Plan [3]	以官方文件為準	以官方文件為準	以官方文件為準	以官方文件為準
Plugin / 擴充市集	plugin + marketplace [4]	以官方文件為準	extensions（以官方文件為準）	以官方文件為準	以官方文件為準

對照只給座標各家對機制的命名與成熟度差異大，精確細節以各官方文件為準。Claude Code 提供約 30 個 hook 事件與內建 subagent 上下文隔離 [2, 3]；多數其他工具偏「指令 / 規則」層，無對等的確定性事件機制。深入對照見 02-6。

動手做

寫一個最小 Skill

照第 2 節範例，在 ~/.claude/skills/ 下建一個 SKILL.md（例如「依本實驗室格式整理文獻」），只給 description 與步驟。觸發它，確認 Claude 真的按步驟做。

加一個 PostToolUse Hook 在存檔後跑 lint / 格式化

照第 3 節範例，在 settings.json 掛 Edit|Write matcher 的 PostToolUse，指向一個從 stdin JSON 讀 tool_input.file_path 的腳本。改一個檔，確認 hook 真的執行。

建一個唯讀 review subagent

照第 4 節範例，在 .claude/agents/ 建一個只給 Read / Grep 的審查 subagent，用 /agents 確認它載入，派它審查一段內容、只收結論。

常見誤區

反模式清單

把該用 Hook 保證的事寫進 CLAUDE.md 祈禱模型遵守：格式化、擋危險指令這類要保證發生的事用 Hook，CLAUDE.md 與 Skill 都靠模型自覺。
裝高 star 但無維護、權限過寬的 plugin：star 反映行銷觸及，不反映安全與維護。安裝前掃描（見 03-3）。
subagent 給過多工具權限：審查型 subagent 給寫入工具違反最小權限。唯讀任務就只給唯讀工具。
用 Skill 做該隔離的探索任務：大量讀取的探索丟給主上下文會稀釋它，該用 subagent 隔離、只收結論。
把元件放進 .claude-plugin/ 目錄：只有 plugin.json 放那，skills/、agents/、hooks/ 放外層 [4]。

自我檢核

通過本單元的標準

給你一個重複任務（例如「每次提交前跑測試並擋掉失敗的提交」），你能判斷該用 Skill、Hook 還是 Subagent 嗎？依據是什麼？
disable-model-invocation: true 與 user-invocable: false 兩個 Skill 欄位，效果差在哪？
你要 Claude Code 在每次存檔後一定執行格式化，你會用哪個 hook 事件？為什麼不寫進 CLAUDE.md？
一個審查型 subagent 該給哪些工具權限？給了寫入工具會違反什麼原則？
從社群市集裝一個 plugin 前，你會掃描哪幾類風險訊號？

來源與延伸閱讀

事實主張依官方文件，快變動項標註截至 2026-05。

[1] Anthropic, “Skills,” Claude Code Docs.（SKILL.md frontmatter 欄位；progressive disclosure 隨需載入；放置優先序企業 > 個人 > 專案 > plugin；!`command` 動態注入與 disableSkillShellExecution；與 .claude/commands/ 同名時 Skill 優先） https://code.claude.com/docs/en/skills （截至 2026-05）
[2] Anthropic, “Hooks,” Claude Code Docs.（約 30 個 hook 事件；handler 類型 command / http / mcp_tool / prompt / agent；stdin JSON 協定、exit code 2 阻擋、exit 0 + JSON 決策；PreToolUse 的 permissionDecision: deny；matcher 語法；未提供 $CLAUDE_FILE_PATHS 環境變數，路徑由 stdin JSON tool_input.file_path 取得） https://code.claude.com/docs/en/hooks （截至 2026-05）
[3] Anthropic, “Subagents,” Claude Code Docs.（.claude/agents/*.md frontmatter；放置優先序受管理 > --agents > 專案 > 使用者 > plugin；內建 Explore / Plan / general-purpose；上下文隔離只回傳結論；subagent 不能巢狀；isolation: worktree） https://code.claude.com/docs/en/sub-agents （截至 2026-05）
[4] Anthropic, “Plugins,” Claude Code Docs.（官方市集 claude-plugins-official 自動可用、社群 anthropics/claude-plugins-community；/plugin install、/plugin marketplace add；plugin 結構 .claude-plugin/plugin.json + 外層 skills/ agents/ hooks/hooks.json .mcp.json；只有 plugin.json 放 .claude-plugin/） https://code.claude.com/docs/en/plugins （截至 2026-05）

銜接：01-6 策略 vs 規則分界（Hook 的設計起點）、04-3 Command、04-4 Skill、04-5 Subagent、04-6 Hooks、04-7 Plugin 建置細節、03-3 安全與供應鏈威脅模型。

總覽

Part I 基礎與進階認識

Part II 進階調適與設定

Part III 認知與思維

Part IV 客製化、整合與自動化

Part V Agentic 案例研究

附錄

02-5 Skills / Hooks / Subagents / Plugins 機制總覽

學習目標

1. 先決定用哪一個：四機制選型

互動選型工具

2. Skills：可重用的流程

3. Hooks：事件驅動的確定性把關

4. Subagents：隔離上下文的子代理

5. Plugins 與 Marketplaces：打包與分發

工具對照

動手做

常見誤區

自我檢核

來源與延伸閱讀

​學習目標

​1. 先決定用哪一個：四機制選型

​互動選型工具

​2. Skills：可重用的流程

​3. Hooks：事件驅動的確定性把關

​4. Subagents：隔離上下文的子代理

​5. Plugins 與 Marketplaces：打包與分發

​工具對照

​動手做

​常見誤區

​自我檢核

​來源與延伸閱讀

學習目標

1. 先決定用哪一個：四機制選型

互動選型工具

2. Skills：可重用的流程

3. Hooks：事件驅動的確定性把關

4. Subagents：隔離上下文的子代理

5. Plugins 與 Marketplaces：打包與分發

工具對照

動手做

常見誤區

自我檢核

來源與延伸閱讀