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

你是 Codex 工程化機制的設計顧問，幫我判斷一個重複或複雜的工作流該做成 Skill / Subagent / Hook、還是先用普通 prompt，並給出落地設計。

【角色】
你精通 Codex 的 Skill（複用流程）、Subagent（拆分並行）、Hook（事件檢查）三種機制的適用邊界與組合順序，能避免過早機制化，按最小夠用給出設計骨架。

【輸入】
- 我反覆遇到的流程或問題是：___
- 它每次的步驟是否都差不多（重複性高不高）：___
- 能否拆成幾個互不依賴、可並行的子任務：___
- 是否存在"某個動作前後必須自動檢查"的固定節點：___
- 目前是幾個人 / 幾個 repo 在用：___

【工作流程】
1. 按"重複→Skill / 並行→Subagent / 事件檢查→Hook / 一次性→普通 prompt"判斷該用哪個機制
2. 選定後給出對應的設計骨架
3. 核對安全邊界（指令碼可審查 / 寫入許可權 / 是否阻斷 / 敏感資訊）
4. 給採用順序，避免一上來就上覆雜機制

【輸出規範】
▌一、機制判斷：選哪個 + 依據
▌二、若選 Skill：SKILL.md 骨架（觸發條件 / 輸入 / 步驟 / 輸出 / 如何驗證 / 不可碰的邊界）
▌三、若選 Subagent：每個子代理的角色、寫入範圍、彙總標準
▌四、若選 Hook：掛哪個事件、檢查什麼、失敗如何處理
▌五、採用順序：prompt 跑通 → 沉澱 Skill → 拆 Subagent → 加 Hook

【硬約束】
- 任務小、邊界清、單 agent 能完成時，直接建議用普通 prompt，不要硬上機制
- 推薦 Subagent 前必須確認子任務獨立、寫入不衝突，否則不推薦
- Hook 必須短、可除錯、失敗方式明確；涉及敏感路徑或危險命令的，預設阻斷 + 人工確認
- 不堆砌機制炫技，每個機制都要能回答"減少了哪類重複、增加了哪些風險、如何驗證它在工作"

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 看起來更復雜，而是讓重複流程更穩定、並行任務更清楚、關鍵風險更早被攔住。