---
title: "Skills、Subagents、Hooks"
description: "理解 Gemini CLI 的三層擴充套件：Skills 負責專門流程，Subagents 負責分工，Hooks 負責生命週期攔截。"
verifiedAt: "2026-05-09"
---

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

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

## 三者分工

```text
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。

## 推薦落地順序

```text
GEMINI.md -> 手动流程 -> Skill -> Subagent -> Hook -> GitHub Action
```

先把規則寫清楚，再封裝能力；先在本地跑通，再進自動化。

## 驗收順序

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

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

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

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

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

## 常見誤用

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

## 組合順序

```mermaid
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
```

## 官方資料

- Agent Skills：[docs/cli/skills.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/skills.md)
- Subagents 🔬（實驗功能）：[docs/core/subagents.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/core/subagents.md)
- Hooks：[docs/hooks/index.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/hooks/index.md)
- Skills 入門教程：[docs/cli/tutorials/skills-getting-started.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/tutorials/skills-getting-started.md)

## 下一篇

<Cards>
  <Card title="Plan mode、Checkpoint、Headless" description="擴充套件能力之前，先理解風險控制、回退和自動化呼叫。" href="/zh-Hant/docs/gemini-cli/understanding/08-plan-checkpoint-headless" />
  <Card title="Agent Skills" description="需要查 Gemini CLI Skills 的官方能力時，回到 Agent Skills 頁。" href="/zh-Hant/docs/gemini-cli/official/04-agents-skills/40-agent-skills" />
  <Card title="Hooks" description="需要配置生命週期攔截時，回到 Hooks 官方頁。" href="/zh-Hant/docs/gemini-cli/official/07-integrations-automation/71-hooks" />
</Cards>
