---
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="/docs/gemini-cli/understanding/08-plan-checkpoint-headless" />
  <Card title="Agent Skills" description="需要查 Gemini CLI Skills 的官方能力时，回到 Agent Skills 页。" href="/docs/gemini-cli/official/04-agents-skills/40-agent-skills" />
  <Card title="Hooks" description="需要配置生命周期拦截时，回到 Hooks 官方页。" href="/docs/gemini-cli/official/07-integrations-automation/71-hooks" />
</Cards>
