Gemini CLI 的 Skills、Subagents、Hooks

📖 本篇術語速查表

英文 / 縮寫	中文	一句話解釋
Skills	技能	複用重複流程。
Subagents	子代理	拆分並行任務。
Hooks	鉤子	事件上自動檢查。

不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你判斷一個流程在 Gemini CLI 裡該做成 Skill、Subagent、Hook 還是普通用法。

你是 Gemini CLI 工程化機制選型顧問。

【角色】
Gemini CLI 工程化機制選型顧問，按最小夠用、安全優先的原則給可落地方案。

【輸入】
- 反覆遇到的流程：___
- 重複性高嗎、能否並行：___
- 有無必須自動檢查的節點：___
- 個人還是團隊：___

【工作流程】
1. 按重複 / 並行 / 事件判斷該用哪個機制
2. 給對應的設計骨架
3. 核對安全邊界
4. 給採用順序

【輸出規範】
▌一、機制判斷 + 依據
▌二、設計骨架
▌三、安全邊界
▌四、採用順序

【硬約束】
- 小任務用普通方式，不硬上機制
- Subagent 子任務要獨立
- Hook 要短、可除錯
- 不要替我臆測情況或編造不存在的能力，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述

Skills（能力包）、Subagents（分工 agent，注：Gemini CLI 目前為實驗功能 🔬）、Hooks（生命週期鉤子）很容易被混在一起。最簡單的區分是：Skill 是任務能力包，Subagent 是分工角色，Hook 是流程攔截器。

三者都能增強 Gemini CLI，但增強的位置不同：Skill 改變“怎麼做任務”，Subagent 改變“誰來做哪一塊”，Hook 改變“關鍵節點必須發生什麼”。

三者分工

Skill       讓 agent 學會某類任務的固定流程
Subagent    把任務拆給專門角色處理
Hook        在 agent loop 的關鍵節點插入指令碼或策略

它們可以組合，但不應該一開始就全上。

機制	適合解決	失敗風險
Skill	高頻任務標準化、流程沉澱、團隊知識複用	把未跑通流程過早封裝
Subagent	並行查資料、分模組審查、分角色驗證	邊界不清導致重複改同一檔案
Hook	危險命令阻斷、格式化、審計、收尾檢查	邏輯過重導致排障困難

什麼時候用 Skill

Skill 適合高頻、可複用、有明確步驟的任務：

程式碼審查。
釋出前檢查。
文件生成。
框架遷移。
安全掃描。
某個團隊內部流程。

如果任務還沒跑通，不要先寫 Skill。先手動跑 2-3 次，把穩定步驟抽出來，再封裝。

一個合格 Skill 至少要寫清輸入、輸出、步驟、驗證、失敗處理和不適用場景。只有一句 prompt 的 Skill 通常不值得維護。

什麼時候用 Subagent

Subagent 適合拆分工作：

一個 agent 查官方文件。
一個 agent 讀原生程式碼。
一個 agent 寫測試。
一個 agent 做審查。

分工的前提是寫清楚輸入、輸出和邊界。不要把模糊任務扔給 subagent。

多 agent 場景裡，最重要的是檔案歸屬。一個 subagent 負責資料核驗，另一個負責測試，第三個負責文案可以；多個 subagent 同時寫同一批 MDX 或同一個模組，風險會迅速上升。

什麼時候用 Hook

Hook 適合治理和自動化：

會話開始時注入專案狀態。
工具執行前檢查危險命令。
寫檔案後跑輕量檢查。
模型輸出後做脫敏。
記錄工具呼叫審計記錄。

Hook 不是 prompt。它是會執行的指令碼或命令，所以安全風險更接近自動化系統。

Hook 適合處理“忘一次就出事”的規則，例如阻止寫 .env、改完後跑格式化、Stop 前檢查測試是否執行。普通風格偏好仍然放在 GEMINI.md，不要全塞進 Hook。

驗收順序

Skill 看觸發是否準確，Subagent 看職責和工具隔離，Hook 看能否阻斷危險動作且失敗可解釋。三者都要有關閉路徑。沒有關閉路徑的擴充套件，不適合進團隊專案。

第三方 Skill 或 Hook 還要檢查指令碼內容和網路訪問。說明寫得安全，不代表執行體安全。

官方 Skill 啟用會有 consent 和目錄訪問提示；Subagent 則要看它擁有的工具集。教學裡要把這兩個提示當成安全資訊，而不是 UI 噪音。

Hook 的記錄也要可讀。阻斷了什麼、為什麼阻斷、如何恢復，都應該能從記錄裡看出來。

如果記錄不可讀，先停用或修復 Hook，不要讓 agent 忽略阻斷繼續執行。一個解釋不清的 Hook，本身就是新的風險源。

常見誤用

把一句 prompt 包成 Skill。
讓 subagent 修改同一批檔案，互相覆蓋。
用 hook 做複雜業務邏輯。
在專案 hooks 裡讀取金鑰或執行遠端命令。
沒有記錄和確認就讓自動化寫回儲存庫。

組合順序

flowchart LR
    Rule["GEMINI.md 規則"] --> Manual["手動跑通流程"]
    Manual --> Skill["封裝 Skill"]
    Skill --> Subagent["拆分 Subagent"]
    Subagent --> Hook["加 Hook 治理"]
    Hook --> CI["進入 GitHub Action / CI"]

    style Rule fill:#dbeafe,stroke:#3b82f6
    style Skill fill:#dcfce7,stroke:#22c55e
    style Hook fill:#fee2e2,stroke:#ef4444