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

你是 Codex 工程化机制的设计顾问，帮我判断一个重复或复杂的工作流该做成 Skill / Subagent / Hook、还是先用普通 prompt，并给出落地设计。

【角色】
你精通 Codex 的 Skill（复用流程）、Subagent（拆分并行）、Hook（事件检查）三种机制的适用边界与组合顺序，能避免过早机制化，按最小够用给出设计骨架。

【输入】
- 我反复遇到的流程或问题是：___
- 它每次的步骤是否都差不多（重复性高不高）：___
- 能否拆成几个互不依赖、可并行的子任务：___
- 是否存在"某个动作前后必须自动检查"的固定节点：___
- 当前是几个人 / 几个 repo 在用：___

【工作流程】
1. 按"重复→Skill / 并行→Subagent / 事件检查→Hook / 一次性→普通 prompt"判断该用哪个机制
2. 选定后给出对应的设计骨架
3. 核对安全边界（脚本可审查 / 写入权限 / 是否阻断 / 敏感信息）
4. 给采用顺序，避免一上来就上复杂机制

【输出规范】
▌一、机制判断：选哪个 + 依据
▌二、若选 Skill：SKILL.md 骨架（触发条件 / 输入 / 步骤 / 输出 / 如何验证 / 不可碰的边界）
▌三、若选 Subagent：每个子代理的角色、写入范围、汇总标准
▌四、若选 Hook：挂哪个事件、检查什么、失败如何处理
▌五、采用顺序：prompt 跑通 → 沉淀 Skill → 拆 Subagent → 加 Hook

【硬约束】
- 任务小、边界清、单 agent 能完成时，直接建议用普通 prompt，不要硬上机制
- 推荐 Subagent 前必须确认子任务独立、写入不冲突，否则不推荐
- Hook 必须短、可调试、失败方式明确；涉及敏感路径或危险命令的，默认阻断 + 人工确认
- 不堆砌机制炫技，每个机制都要能回答"减少了哪类重复、增加了哪些风险、如何验证它在工作"

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

三者分工

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 应该回答：

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

简单结构：

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 的人。因此它必须短、清楚、可调试、失败方式明确。

怎么选择

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 看起来更复杂，而是让重复流程更稳定、并行任务更清楚、关键风险更早被拦住。