Skills、Subagents、Hooks

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