---
title: "08 · Skills、Subagents、Hooks 解决什么问题"
description: "区分三种进阶机制：skills 复用流程，subagents 拆分工作，hooks 自动检查关键事件。"
canonical: "https://xiangyugongzuoliu.com/openai-codex-skills-subagents-hooks"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

Skills、subagents、hooks 都是让 Codex 工作流更稳定的机制，但它们解决的问题不同。不要一上来全用；先把单 agent、上下文、权限和验证跑顺，再逐步引入。

> [!TIP]
> 判断口诀：重复流程用 skill，大任务分工用 subagent，关键节点自动检查用 hook。

<Cards>
  <Card title="Skills" href="https://developers.openai.com/codex/skills">
    把重复工作流打包成可触发的 `SKILL.md`。
  </Card>
  <Card title="Subagents" href="https://developers.openai.com/codex/subagents">
    为复杂任务配置专门角色或并行工作流。
  </Card>
  <Card title="Hooks" href="https://developers.openai.com/codex/hooks">
    在工具调用、命令执行等生命周期事件上运行检查。
  </Card>
</Cards>

## 三者分工

```mermaid
flowchart TB
    Codex["Codex 主任务"]
    Skill["Skill<br/>复用稳定流程"]
    Subagent["Subagent<br/>拆分角色或并行任务"]
    Hook["Hook<br/>事件触发检查"]

    Codex --> Skill
    Codex --> Subagent
    Codex --> Hook
```

区别：

- Skill 解决“每次都要重复交代同一套步骤”。
- Subagent 解决“一个任务需要多个角色或并行处理”。
- Hook 解决“某些动作前后必须自动检查”。

它们都是工程化手段，不是能力炫技。任务小、边界清楚、单 agent 能完成时，不需要上复杂机制。

## Skill：复用稳定流程

Skill 是一组本地说明、资源和可选脚本。Codex 根据 skill 描述判断是否需要加载它。

适合：

- PR review。
- 文档美化。
- release note。
- migration planning。
- incident summary。
- 重复的调试流程。

一个 skill 应该回答：

- 什么时候触发。
- 输入是什么。
- 步骤是什么。
- 输出是什么。
- 如何验证。
- 哪些边界不能碰。

简单结构：

```text
my-skill/
  SKILL.md
  scripts/
  templates/
  examples/
```

Skill 的关键是描述准确。Codex 通常先看到 name 和 description，只有判断任务需要时才进一步加载内容。

## Subagent：拆分工作

Subagent 适合任务天然可分工，且分工结果能汇总。

适合：

- 多模块并行审查。
- 一个 agent 负责代码探索，另一个负责文档核验。
- 一个 agent 做只读 review，另一个做实现。
- 大型任务中不同角色需要不同权限或模型配置。

不适合：

- 简单单文件修改。
- 强串行任务。
- 下一步必须依赖上一步结论的任务。
- 用户没有明确要求并行或拆分的任务。

使用 subagent 前先确认：

- 每个 subagent 的任务是否独立。
- 写入范围是否互不冲突。
- 汇总标准是什么。
- 成本和上下文开销是否值得。

Subagent 不是默认加速器。拆得不好会增加协调成本。

## Hook：自动检查关键事件

Hook 会在 Codex 生命周期的特定事件上运行检查或命令。

适合：

- 运行 shell 命令前做策略检查。
- 工具调用前后做审计。
- 修改文件前检查敏感路径。
- 长任务中记录状态或阻止高风险动作。
- 团队统一执行安全、合规、格式检查。

Hook 不适合：

- 大量业务逻辑。
- 难以解释的隐藏自动化。
- 会频繁误报的检查。
- 需要人工判断的复杂决策。

Hook 一旦进入项目层，就会影响所有使用该 repo 的人。因此它必须短、清楚、可调试、失败方式明确。

## 怎么选择

```mermaid
flowchart TD
    Start["遇到一个重复或复杂问题"]
    Repeat{"是否重复出现?"}
    Parallel{"是否能拆成独立并行任务?"}
    Event{"是否必须在某个事件上自动执行?"}
    Skill["做成 Skill"]
    Subagent["使用 Subagent"]
    Hook["配置 Hook"]
    Prompt["继续用普通 prompt"]

    Start --> Repeat
    Repeat -->|是| Skill
    Repeat -->|否| Parallel
    Parallel -->|是| Subagent
    Parallel -->|否| Event
    Event -->|是| Hook
    Event -->|否| Prompt
```

更具体的判断：

- 同一流程反复跑：skill。
- 多人或多角色并行：subagent。
- 固定事件必须自动检查：hook。
- 一次性小任务：普通 prompt。

## 组合使用方式

三者可以组合，但要有顺序。

推荐成熟路径：

1. 先用 prompt 把流程跑通。
2. 重复几次后沉淀成 skill。
3. 流程变大后，再拆 subagent。
4. 发现关键动作总要检查，再加 hook。

例子：

- 先让 Codex 手动做 PR review。
- 重复后把 review checklist 做成 skill。
- 大 PR 再拆 reviewer / security / docs subagents。
- 最后用 hook 在提交前自动跑必要检查。

不要反过来一开始就写 hook 和 subagent。过早机制化会让错误流程固化。

## 安全边界

Skills、subagents、hooks 都会扩大自动化能力，因此要看安全边界：

- Skill 中的脚本是否可审查。
- Subagent 是否有写入权限。
- Hook 是否会阻断正常任务。
- 是否读取或记录敏感信息。
- 是否能说明失败原因。
- 是否有关闭和回滚方式。

越是共享给团队的机制，越要写清楚职责、触发条件和验证方式。

## 最小建议

先做三个小而稳定的机制：

1. 一个文档或 PR review skill。
2. 一个只读 reviewer subagent 配置。
3. 一个阻止敏感路径或危险命令的 hook。

每个机制都要能回答：它减少了哪类重复劳动，增加了哪些风险，如何验证它真的在工作。

进阶能力的目标不是让 Codex 看起来更复杂，而是让重复流程更稳定、并行任务更清楚、关键风险更早被拦住。
