08 · Skills、Subagents、Hooks 解決什麼問題

Skills、subagents、hooks 都是讓 Codex 工作流更穩定的機制，但它們解決的問題不同。不要一上來全用；先把單 agent、上下文、許可權和驗證跑順，再逐步引入。

三者分工

flowchart TB
    Codex["Codex 主任務"]
    Skill["Skill<br/>複用穩定流程"]
    Subagent["Subagent<br/>拆分角色或並行任務"]
    Hook["Hook<br/>事件觸發檢查"]

    Codex --> Skill
    Codex --> Subagent
    Codex --> Hook

區別：

• Skill 解決“每次都要重複交代同一套步驟”。
• Subagent 解決“一個任務需要多個角色或並行處理”。
• Hook 解決“某些動作前後必須自動檢查”。

它們都是工程化手段，不是能力炫技。任務小、邊界清楚、單 agent 能完成時，不需要上覆雜機制。

Skill：複用穩定流程

Skill 是一組本地說明、資源和可選指令碼。Codex 根據 skill 描述判斷是否需要載入它。

適合：

• PR review。
• 文件美化。
• release note。
• migration planning。
• incident summary。
• 重複的除錯流程。

一個 skill 應該回答：

• 什麼時候觸發。
• 輸入是什麼。
• 步驟是什麼。
• 輸出是什麼。
• 如何驗證。
• 哪些邊界不能碰。

簡單結構：

my-skill/
  SKILL.md
  scripts/
  templates/
  examples/

Skill 的關鍵是描述準確。Codex 通常先看到 name 和 description，只有判斷任務需要時才進一步載入內容。

Subagent：拆分工作

Subagent 適合任務天然可分工，且分工結果能彙總。

適合：

• 多模組並行審查。
• 一個 agent 負責程式碼探索，另一個負責文件核驗。
• 一個 agent 做只讀 review，另一個做實現。
• 大型任務中不同角色需要不同許可權或模型配置。

不適合：

• 簡單單檔案修改。
• 強序列任務。
• 下一步必須依賴上一步結論的任務。
• 使用者沒有明確要求並行或拆分的任務。

使用 subagent 前先確認：

• 每個 subagent 的任務是否獨立。
• 寫入範圍是否互不衝突。
• 彙總標準是什麼。
• 成本和上下文開銷是否值得。

Subagent 不是預設加速器。拆得不好會增加協調成本。

Hook：自動檢查關鍵事件

Hook 會在 Codex 生命週期的特定事件上執行檢查或命令。

適合：

• 執行 shell 命令前做策略檢查。
• 工具呼叫前後做審計。
• 修改檔案前檢查敏感路徑。
• 長任務中記錄狀態或阻止高風險動作。
• 團隊統一執行安全、合規、格式檢查。

Hook 不適合：

• 大量業務邏輯。
• 難以解釋的隱藏自動化。
• 會頻繁誤報的檢查。
• 需要人工判斷的複雜決策。

Hook 一旦進入專案層，就會影響所有使用該 repo 的人。因此它必須短、清楚、可除錯、失敗方式明確。

怎麼選擇

flowchart TD
    Start["遇到一個重複或複雜問題"]
    Repeat{"是否重複出現?"}
    Parallel{"是否能拆成獨立並行任務?"}
    Event{"是否必須在某個事件上自動執行?"}
    Skill["做成 Skill"]
    Subagent["使用 Subagent"]
    Hook["配置 Hook"]
    Prompt["繼續用普通 prompt"]

    Start --> Repeat
    Repeat -->|是| Skill
    Repeat -->|否| Parallel
    Parallel -->|是| Subagent
    Parallel -->|否| Event
    Event -->|是| Hook
    Event -->|否| Prompt

更具體的判斷：

• 同一流程反覆跑：skill。
• 多人或多角色並行：subagent。
• 固定事件必須自動檢查：hook。
• 一次性小任務：普通 prompt。

組合使用方式

三者可以組合，但要有順序。

推薦成熟路徑：

1. 先用 prompt 把流程跑通。
2. 重複幾次後沉澱成 skill。
3. 流程變大後，再拆 subagent。
4. 發現關鍵動作總要檢查，再加 hook。

例子：

• 先讓 Codex 手動做 PR review。
• 重複後把 review checklist 做成 skill。
• 大 PR 再拆 reviewer / security / docs subagents。
• 最後用 hook 在提交前自動跑必要檢查。

不要反過來一開始就寫 hook 和 subagent。過早機制化會讓錯誤流程固化。

安全邊界

Skills、subagents、hooks 都會擴大自動化能力，因此要看安全邊界：

• Skill 中的指令碼是否可審查。
• Subagent 是否有寫入許可權。
• Hook 是否會阻斷正常任務。
• 是否讀取或記錄敏感資訊。
• 是否能說明失敗原因。
• 是否有關閉和回復方式。

越是共享給團隊的機制，越要寫清楚職責、觸發條件和驗證方式。

最小建議

先做三個小而穩定的機制：

1. 一個文件或 PR review skill。
2. 一個只讀 reviewer subagent 配置。
3. 一個阻止敏感路徑或危險命令的 hook。

每個機制都要能回答：它減少了哪類重複勞動，增加了哪些風險，如何驗證它真的在工作。

進階能力的目標不是讓 Codex 看起來更復雜，而是讓重複流程更穩定、並行任務更清楚、關鍵風險更早被攔住。