08 · Skills、Subagents、Hooks 解决什么问题

⏱️ 预计阅读 13 分钟 ｜ 🎯 目标：把 Codex 从"单 Agent 单次任务"升级到"流程复用 + 分工协作 + 自动检查"

上一篇讲完工具栈 4 层。这一篇展开 Skills / Subagents / Hooks —— 三种升级 Codex 工作方式的机制。 关键判断：先把单 Agent 用熟，再上这三个。它们不是越早用越好。

🎬 三种"重复劳动"的痛

回想一下你过去一周，Codex 让你重复做过这些事吗？

💡 判断口诀："重复 5 次以上的事 → 想想能不能 Skill / Subagent / Hook"。 一两次的事不值得做成机制。

🗺️ 三者全景：它们各管什么？

flowchart TB
    User[👤 你提任务]
    Codex[🤖 Codex 主 Agent]

    subgraph Mech1["🛠️ Skill —— 复用流程"]
        S[多步工作流打包]
        S2["例：PR review / 文档生成"]
    end

    subgraph Mech2["👥 Subagent —— 分工并行"]
        Sub[专项 Agent 配置]
        Sub2["例：reviewer / browser-debugger / docs-researcher"]
    end

    subgraph Mech3["🔔 Hook —— 生命周期触发"]
        H[事件钩子]
        H2["例：改完文件自动 typecheck / 跑命令前审计"]
    end

    User --> Codex
    Codex -.调用.-> Mech1
    Codex -.派生.-> Mech2
    Codex -.触发.-> Mech3

    style Mech1 fill:#dcfce7,stroke:#22c55e
    style Mech2 fill:#fef3c7,stroke:#f59e0b
    style Mech3 fill:#dbeafe,stroke:#3b82f6

一句话区分：

🛠️ Skill · 把多步流程做成一键

是什么

Skill = 一份带说明书的工作流包：

my-pr-review-skill/
├── SKILL.md          ← 流程说明（Codex 看这个学怎么做）
├── checklist.md      ← 资源文件
└── scripts/          ← 可选脚本
    └── run-checks.sh

📖 来源：OpenAI Codex · Agent Skills

为什么 Codex 不会被 Skill "撑爆"

设计精巧之处：渐进式披露（progressive disclosure）：

flowchart LR
    A["Codex 启动<br/>只读 Skill 名字 + 描述"] --> B{遇到任务<br/>需要这个 Skill 吗}
    B -->|是| C["完整加载 SKILL.md"]
    B -->|否| D["跳过，节省上下文"]

    style C fill:#dcfce7,stroke:#22c55e
    style D fill:#fef3c7,stroke:#f59e0b

结果：你装 50 个 Skill，启动只读 50 行描述；用到哪个才完整加载。不撑爆上下文窗口。

怎么放 / 怎么用

一个简单的 Skill 例子

`<!-- ~/.codex/skills/pr-review/SKILL.md -->`
---
name: PR Review
description: 系统性地评审一个 PR，检查代码风格、测试覆盖、安全风险
---

# 步骤

1. 拉取 PR 改动列表（用 git diff）
2. 检查每个改动文件：
   - 代码风格符合项目 AGENTS.md
   - 有对应测试
   - 无明显性能问题
3. 跑安全扫描脚本 `./scripts/run-checks.sh`
4. 输出三段：
   - ✅ 通过项
   - ⚠️ 建议项
   - ❌ 阻塞项

💡 写 Skill 的最佳实践：每个 Skill 只做一件事；优先用说明文字而不是脚本（除非要确定性结果）。

Skill vs Plugin 区别

👥 Subagent · 把大任务拆给多个专项 Agent

是什么

Subagent = 主 Agent 派生出的专项分身，并行干活，最后汇总。

flowchart TB
    Main["🤖 主 Agent<br/>接到大任务"]
    S1["📚 docs-researcher<br/>查框架文档"]
    S2["🔍 pr-explorer<br/>读代码库"]
    S3["🐛 browser-debugger<br/>复现 bug"]
    S4["🧪 ui-fixer<br/>改 UI 代码"]
    Result["📦 主 Agent 汇总结果"]

    Main --> S1 & S2 & S3 & S4
    S1 & S2 & S3 & S4 --> Result

    style Main fill:#fef3c7,stroke:#f59e0b
    style Result fill:#dcfce7,stroke:#22c55e

📖 来源：OpenAI Codex · Subagents

何时该用 Subagent

✅ 强并行任务：codebase 探索、多模块同时改、多源信息汇总 ✅ 专项能力分工：让 reviewer agent 用更便宜模型 + 让 architect agent 用最强模型 ✅ 大任务拆分：一个 Agent 做不完，分给多个

❌ 简单任务：单 Agent 几步就完成的，别拆分（拆了反而慢） ❌ 强串行任务：A 必须等 B 输出再做，并行不出来

⚠️ 成本警告：每个 Subagent 自己消耗 token，总开销显著高于单 Agent。预算敏感场景慎用。

Subagent 配置

可以给每个 Subagent 单独配模型 / sandbox / MCP：

# ~/.codex/agents/reviewer.toml

name = "reviewer"
description = "代码评审专家，检查风格 / 测试 / 安全"
model = "gpt-5.4"
model_reasoning_effort = "low"   # 评审用低推理就够
sandbox_mode = "read-only"       # 评审不改代码
mcp_servers = ["github"]         # 只接 GitHub MCP

# 让 UI 显示更友好的实例名
nickname_candidates = ["巡查 A", "巡查 B", "巡查 C"]

启动方式：

请用 reviewer 子 Agent 检查最近 3 个 PR

默认是开还是关

✅ 默认开：当前 Codex 版本里 Subagent 工作流默认启用（在 App / CLI 可见） ⏳ IDE 可见性：陆续接入中

🔔 Hook · 在生命周期事件上自动触发

是什么

Hook = 在 Codex 干活的关键节点上挂一个"检查员"。

flowchart LR
    A[Codex 想做某动作] --> B{🔔 Hook 触发}
    B -->|通过| C[继续]
    B -->|拦截| D[停下问 / 报错]

    style B fill:#dbeafe,stroke:#3b82f6
    style D fill:#fee2e2,stroke:#ef4444

能挂在哪些事件上

✅ MCP 工具调用前后：审计哪个工具被调 ✅ apply_patch 改文件前：审查 diff 是否符合规则 ✅ 长时间 Bash 会话：超时 / 安全扫描

配置方式

# ~/.codex/config.toml

[hooks]
before_apply_patch = "scripts/lint-diff.sh"     # 改文件前先 lint diff
after_mcp_call = "scripts/audit-mcp.sh"         # MCP 调用后审计日志

或者写在独立 hooks.json，企业可通过 requirements.toml 强制下发。

典型用例

📖 Hooks 现已稳定，可在 config.toml 内联或外置 hooks.json，企业可强制管控。

⚖️ 三者怎么选：决策矩阵

🚫 常见误解 → ✅ 正确理解

🔍 想再深一层（点击展开）

# IT 下发的 requirements.toml

[required_hooks]
before_apply_patch = "/opt/security/scan-diff.sh"   # 强制 diff 安全扫描
after_mcp_call = "/opt/audit/log-mcp.sh"            # 强制审计日志

📝 本章自检

✅ 过关标准：能用一句话说清 —— "Skill 复用流程，Subagent 分工并行，Hook 自动检查 —— 各管一摊。"

📚 下一篇

• ➡️ 09 · 控制模型、速度、成本和质量 —— 模型策略背后的工程取舍