OpenAI Codex Skills、Subagents、Hooks 新手指南：三个进阶概念新手什么时候用哪个

预计阅读 12 分钟 ｜ 目标：用新手能听懂的话讲清 OpenAI Codex 的 Skills（技能）、Subagents（子代理）、Hooks（钩子）三个进阶概念分别管什么、什么时候用哪个，看完知道自己该不该学、先学哪个、怎么搭配。

如果你装好了 OpenAI Codex，开始在文档和社区里反复看到 Skills、Subagents、Hooks 这三个词，又分不清它们到底是不是一回事——这篇就是写给你的。先给一句话结论：它们是三个不同维度的进阶能力，互相补充、不互相替代。Skills 是「可复用的工作流模板」，Subagents 是「让多个 AI 并行干活的执行架构」，Hooks 是「在 Codex 干活的关键节点自动插脚本做检查的治理机制」。把这三句记住，剩下的细节都好懂了。

决策树：什么时候用 Skills、什么时候用 Subagents、什么时候用 Hooks

整篇文章的核心就是下面这张决策树。三者不是三选一的竞品，而是回答三个不同问题的工具，所以判断的入口不是「我想学哪个」，而是「我现在卡在哪个问题上」。顺着问题往下走，每条路径终点只指向一个工具——这正是「三选一」的正确姿势：一次只解决一个问题。

flowchart TD
    A[你现在遇到的问题是?] --> B{同一套流程<br/>反复对 Codex 解释?}
    B -->|是| C[上 Skills<br/>把流程写成 SKILL.md 复用]
    B -->|否| D{一个任务能拆成<br/>几块互不依赖、可并行的子任务?}
    D -->|是| E[上 Subagents<br/>多代理并行, 但更费 token]
    D -->|否| F{有条规则必须强制执行<br/>不能靠 AI 每次自觉?}
    F -->|是| G[上 Hooks<br/>用代码在关键节点卡死]
    F -->|否| H[三个都先别碰<br/>继续用 Codex 攒手感]
    C --> I{封装好的流程<br/>还要并行拆块?}
    I -->|是| E
    I -->|否| J{流程里有<br/>必须强制的红线?}
    J -->|是| G
    J -->|否| K[一个 Skill 就够]

把这张图压成三句判断，随手就能用：

• 「同一套话我已经重复解释好几遍了」 → 上 Skills，把流程沉淀成模板。
• 「这活能切成几块同时干、彼此不等」 → 上 Subagents，多代理并行。
• 「这条规则必须每次都守住，不能指望 AI 自觉」 → 上 Hooks，用代码强制卡死。

🔥 翔宇判断：新手最容易犯的错，是一上来三个全开、对着官方文档逐字配置。正确顺序是反过来的——先用 Codex 干活，等你发现「这套流程我又解释了一遍」，再去封装成 Skill；等你发现「这个任务能拆成几块并行跑」，再去碰 Subagents；等你发现「我必须强制某条规则、不能靠 AI 自觉」，再去上 Hooks。需求倒逼工具，而不是工具找需求——这是这三件套唯一正确的上手顺序。

后面的章节就是把这张决策树的每条分支讲透：先用一个比喻把三者的维度拉开，再分别讲每个工具「解决哪个问题、什么时候该上」，最后讲它们怎么搭着用、有哪些坑。你随时可以回到这张图，对照自己现在卡在哪一层。

一、用一个比喻讲清楚 Skills、Subagents、Hooks 的分工

文档里每个词单独看都认识，放一起就糊涂——这是因为三个概念处在不同的维度，硬放在一条线上比当然乱。先用一个贯穿全文的类比把维度拉开：把 Codex 想成一个帮你干活的助手，那么——

• Skills（技能）= 一本 SOP（标准作业流程手册）。你把「干某类任务时该按哪个流程走」写成一份说明书，需要时助手翻出来照着做。它管的是「怎么做这件事」。
• Subagents（子代理）= 一群能同时上工的专业同事。一个大活拆成几块，派给几个各有专长的同事同时干，干完汇总给你。它管的是「谁来做、能不能并行做」。
• Hooks（钩子）= 装在工位门口的自动检查门。助手每次伸手拿工具（跑命令、改文件）之前或之后，门会自动拦一道、查一道。它管的是「做之前做之后，必须卡住哪些规则」。

💡 通俗讲：Skills 回答「按什么流程做」，Subagents 回答「派几个人一起做」，Hooks 回答「做的时候哪些红线必须自动卡住」。一个是剧本，一个是班组，一个是质检关。三者层次完全不同，所以才能搭配着用，而不是二选一。

这根类比锚后面每一节都会用到。只要你心里清楚现在讲的是「剧本、班组、还是质检关」，就不会被术语带偏。

二、Skills（技能）是什么：把重复流程写成一份说明书

Skills 是 Codex 的「可复用工作流模板」。按官方文档（developers.openai.com/codex/skills）的定义，一个 Skill 就是一个文件夹，里面放一份 SKILL.md 说明书，外加可选的 scripts/（脚本）、references/（参考资料）、assets/（模板素材）。SKILL.md 必须包含两个字段：name（精确名字）和 description（描述——决定 Codex 什么时候会用它）。

最简单的 SKILL.md 长这样：

---
name: skill-name
description: 准确说明这个技能什么时候该触发、什么时候不该触发。
---

给 Codex 照着走的具体步骤。

它解决的痛点很具体：同一套流程，你在对话里翻来覆去解释。比如「做 PR 评审时先看测试覆盖、再看安全、最后看命名规范」，这套话你说一次是教学，说十次就是浪费。把它写进一个 Skill，下次只要任务匹配，Codex 自己就调出来照做。

Codex 调用 Skill 有两种方式：

• 显式调用：在提示词里直接点名。在命令行界面（CLI）或集成开发环境（IDE）里输入 /skills 或打 $ 提及某个技能。
• 隐式调用：Codex 根据你任务的内容，匹配某个 Skill 的 description 自动选用。

正因为隐式匹配靠的是 description，官方建议把关键场景词和边界前置写进描述里——比如「PR 评审专用，不用于普通 code review」——这样即使描述被压缩，Codex 也还能匹配上。

⚠️ 常见踩坑：很多人第一份 Skill 把 description 写得很笼统（「帮助代码相关任务」），结果 Codex 要么该用时不用、要么不该用时乱用。描述要写清「什么时候触发、什么时候不触发」，这是 Skill 能不能被正确调用的命门。

新手第一份 Skill 怎么起步？最快的路径是用 Codex 内置的 $skill-creator（它本身就是个系统级 Skill）。在命令行里输入 $skill-creator，它会反向访谈你：这个技能干什么、什么时候触发、要不要带脚本（默认只带说明、不带脚本），然后生成 SKILL.md 草稿，你修订即可。第一个 Skill 控制在几十行、跑顺再迭代，别上来就写大而全的流程。

三、Subagents（子代理）是什么：让几个 AI 并行干活

Subagents 是 Codex 的「多代理执行架构」。按官方文档（developers.openai.com/codex/subagents），Codex 可以同时派出多个专门的子代理并行干活，再把它们的结果汇总成一个回复。它特别适合那种「能拆开、能并行」的复杂任务——典型场景是探索陌生代码库、或者按一份多步计划同时推进多块。

这里有两个新手必须先记住的硬事实：

• 子代理只在你明确要求时才会启动。Codex 不会自作主张开子代理——你得在提示词里说清「派一个代理查安全、派一个查性能……」它才动。
• 子代理消耗的令牌（token）比单代理多得多。官方明说：因为每个子代理都要自己跑模型、自己调工具，子代理工作流的总消耗显著高于单代理。这是成本，不是免费的并行。

Codex 内置了三个开箱即用的子代理：

💡 通俗讲：explorer 像只看不动手的侦察兵，worker 像负责动手改的施工队，default 是没指定时的全能工。新手探索一个看不懂的大项目时，让几个 explorer 同时扫不同模块，比你自己一个文件一个文件翻快得多。

你也可以定义自己的子代理：在 ~/.codex/agents/（个人）或 .codex/agents/（项目）下放 TOML 配置文件，每个文件定义一个代理，必须写 name、description、developer_instructions 三个字段，还能可选地指定 model（模型）、sandbox_mode（沙箱模式）等。官方给的 PR 评审范式就是三个自定义代理分工：pr_explorer 摸清代码、reviewer 找正确性和安全问题、docs_researcher 通过文档服务器核对接口。

子代理有两个全局参数，新手务必知道但通常不用动，都在配置里的 [agents] 段：

• max_threads（最大并发线程）：主代理最多同时开几个子代理。默认 6。
• max_depth（最大嵌套深度）：子代理还能不能再开下一层。默认 1，意思是允许子代理再开一层、但禁止更深。

官方对 max_depth 有一句明确警告：调高这个值会增加令牌消耗、延迟和本机资源占用。

⚠️ 常见踩坑：max_depth 默认 1，别去动它。深层嵌套的成本会快速放大——孙代理再开重孙代理，每多一层都要自己跑模型、自己调工具，token 像滚雪球。真要做更复杂的多代理流程，宁可拆成几个「主代理 + 一层子代理」串行跑，也比纵向加深稳得多。max_threads 默认 6 对新手也够了，超过 6 通常说明任务被拆得过碎。这里要厘清一个容易混的点：子代理工作流在当前版本已默认启用，但「默认可用」不等于「会自动开」——Codex 只在你明确要求时才派子代理，单文件小任务永远单代理最划算。

四、Hooks（钩子）是什么：在关键节点自动插一道检查

Hooks 是 Codex 的「生命周期治理机制」。按官方文档（developers.openai.com/codex/hooks），它是一套扩展框架，让你把自己的脚本插进 Codex 干活的循环里，在关键节点自动执行——比如把对话发给日志系统、扫描提示词防止误粘 API 密钥、在某次操作前拦下危险命令、在对话结束时自动总结存档。

Hooks 默认开启。它和 Skills、Subagents 最大的区别是：Skills 和 Subagents 是「让 AI 更会做」，Hooks 是「不靠 AI 自觉、用代码强制卡住」。这是为什么治理类的事一定要用 Hooks，而不是写进 Skill 里指望 AI 每次都照做——确定性检查交给代码，推理判断才交给模型。

Codex Hooks 支持的生命周期事件远不止社区早期文章说的那几个。按官方文档，当前支持这些事件（一部分在「对话回合」范围运行，一部分在「会话/子代理启动」范围运行）：

💡 通俗讲：把 Codex 干一件事的过程想成一条流水线——开工、收到你的指令、伸手拿工具、拿完工具、收工。Hooks 就是在这条线的每个节点装一个可编程的检查岗，你想在哪个节点卡、卡什么，自己写脚本决定。

新手真正要记住的只有两个事件：PreToolUse（命令执行前拦截，比如发现命令里有 rm -rf / 就拦下）和 PostToolUse（命令执行后校验，比如自动跑一遍 lint、检查提交信息格式）。「该不该上 Hooks」的判断到这里就够了——剩下的「具体怎么配」（配置文件放哪、脚本怎么写、用 permissionDecision: "deny" 还是退出码拦截）是另一个话题，我们专门写在 Claude Code Hooks 怎么配 那篇里逐字段拆，本文不展开。

但有一个原理新手必须先建立，因为它直接影响「Hooks 能不能解决你的问题」：

⚠️ 常见踩坑：有两点新手容易误解，想清楚才知道 Hooks 该卡在哪一步。一是 PostToolUse 并不能撤销已经跑完的命令——命令执行了就收不回来，hook 能做的只是把反馈替换成工具结果、让模型从你给的反馈继续，相当于「跑完了再纠正」而不是「不让跑」。所以真要「不让某条命令跑」，必须用 PreToolUse 在执行前拦。二是 Hooks 是护栏（guardrail）不是铁牢——它能拦命令、文件编辑和工具调用服务器（MCP）调用这类常见路径，但 Codex 有时能换一条工具路径绕过去，所以别把它当成唯一的安全边界。

五、4 类身份对号入座：你现在该上哪一个

讲清三个概念之后，回到最实际的问题——以你现在的状态，三个里先碰哪个？对号入座。

① 刚装好 Codex 的纯新手：三个都先别碰。你现在最该做的是用 Codex 干真实的活，建立手感。等你某个流程重复解释到烦了，再把它写成第一个 SKILL.md。理解这三个概念有意义，但动手顺序是「先用、后封装、再治理」。

② 用了几周的个人开发者：从 Skills 入手。把你重复最多的那套流程（PR 评审 SOP、新项目脚手架、bug 修复套路）封装成 Skill。如果你开始要啃一个陌生的大型代码库，可以试试让几个 explorer 子代理并行扫不同模块——这是 Subagents 对个人开发者最实在的用途。Hooks 这阶段一般还用不上。

③ 团队 / 项目维护者：直接上 Hooks。团队场景的核心诉求是「强制规则」——不能靠每个人、每个 AI 自觉。用 PreToolUse 拦危险命令、用 PostToolUse 强制 lint 和提交规范，配合信任审查机制，把治理变成代码而不是口头约定。

④ 想搭复杂多代理流程的进阶者：三件套组合。但有顺序——先用 Skill 把完整流程定义清楚，再用自定义 Subagents 把流程拆成并行的专业代理，最后用 Hooks 给每个代理跑工具时兜底。关键是别一上来三个全开，学习曲线太陡，先单独把一种用顺。

这四类身份其实就是开头那张决策树的四个出口：纯新手停在「先别碰」，个人开发者落在「Skills」（顺带试 explorer），团队维护者落在「Hooks」，进阶者把三条路径串起来。拿不准自己是哪一类时，回到决策树问自己那三个问题就行——它认的是你卡在哪个问题，不是你自封哪个段位。

六、Skills 和 AGENTS.md 有什么区别：判断「该不该用 Skills」的关键边界

新手最常问的一个问题：既然有了 AGENTS.md（项目指令文件），为什么还要 Skills？两者都是「告诉 AI 该怎么做」，区别在加载方式和职责：

判断很简单：高频、每次都要遵守的内容进 AGENTS.md；低频、特定任务才用的完整流程进 Skill。 这背后有一个实测佐证：Vercel 团队做过一组对比评测，把同一份框架文档分别放进每次自动加载的 AGENTS.md 和靠 AI 自己决定要不要读的 Skill，结果嵌入式上下文（AGENTS.md）的通过率是 100%，而按需检索的 Skill 在不加额外提示时只有 53%——和「完全没文档」的基线一样，因为有 56% 的情况 AI 根本没去调用那个 Skill（数据见 Vercel 官方博客）。换句话说，你真正高频依赖的内容应该放进 AGENTS.md，而不是指望 AI 每次都正确地选中那个 Skill。

这条分工的本质是「确定性对灵活性」：AGENTS.md 是确定的、强制的、每次都在的；Skill 是灵活的、按需的、靠匹配触发的。所以判断「该不该用 Skills」就一句话——必须每次遵守的写进 AGENTS.md（交给确定性），不固定、只在特定任务才需要的完整流程才写进 Skill（交给灵活匹配）。把强制规则塞进 Skill，等于把确定性的事交给不确定的匹配机制，迟早漏；把一次性流程塞进 AGENTS.md，又会撑大每次对话的上下文。各归各位。

七、三者能不能搭配使用：能，而且经常这么用

三件套不是三选一，恰恰相反——成熟的工作流经常三个一起上，因为它们处在不同维度。两个典型组合：

组合一：PR 自动评审。 先用一个 Skill 定义「PR 评审完整流程」，再用 Subagents 把流程拆成 reviewer（查正确性和安全）、docs_researcher（核对接口文档）、pr_explorer（摸清代码）三个子代理并行跑，最后用 PreToolUse Hook 在每个子代理跑命令前拦危险操作。

组合二：bug 修复标准流程。 Skill 定义「修 bug 的标准套路」，先用 explorer 子代理扫清代码，主代理用 worker 改代码，改完用 PostToolUse Hook 自动跑 lint 校验。

⚠️ 常见踩坑：能搭配不等于该一上来全搭。三者层次不同——Skills 是工作流定义、Subagents 是执行架构、Hooks 是治理机制——彼此独立设计但能协同。新手的正确做法是先单独把一种用顺，再考虑组合；三个一上来全开，学习曲线陡到容易直接放弃。

八、Skills 装多了有副作用吗：会，别囤

这是个真实存在的坑。Codex 用一种叫渐进式披露（progressive disclosure）的机制管理上下文：它先把每个 Skill 的 name、description 和文件路径放进上下文供选择，不是一上来就塞完整内容。但这份「初始技能列表」有预算上限——大约是模型上下文窗口的 2%，上下文窗口未知时是 8000 字符。

Skill 装太多、超出预算时，Codex 会按这个顺序退让：先缩短 description（影响触发准确度），再干脆省略掉一部分 Skill（你以为装了、其实没进选择列表），并显示警告。

社区里的经验共识大致是：起步 5-10 个覆盖最高频工作流，多数团队 10-30 个有价值，超过这个量级可见性就成了瓶颈、需要专门治理。

🔥 翔宇判断：新手第一个月装一两个就够，别看见好用的 Skill 就往里囤。判断要不要新增一个 Skill 的信号很简单——当你发现「同一套流程，我已经在提示词里手敲了好几遍」时，才封装它。没有这个痛点就先不装。囤 Skill 不仅不提速，还会因为渐进式披露的预算挤占，让真正常用的那个反而被省略。

九、拿一个真实任务走一遍决策树

抽象的判断说再多，不如拿一个具体任务过一遍。假设你要做的是「给团队仓库做 PR 自动评审」，顺着开头那张决策树往下走，看每一步该上哪个工具——这也是检验你是否真听懂「三选一」的最好方式。

1. 「这套评审流程是不是会反复用？」 是。每个 PR 都要走一遍同样的步骤（看测试覆盖、查安全、核接口、读改动）。→ 第一步上 Skills，把这套流程写成一个 SKILL.md，下次匹配到 PR 评审任务就自动调出来。
2. 「这套流程能不能拆成几块同时干？」 能。查安全、核接口文档、摸代码这三件事互不依赖，可以并行。→ 第二步上 Subagents，按官方范式拆成 reviewer（查正确性和安全）、docs_researcher（核对接口文档）、pr_explorer（摸清代码）三个子代理并行跑。
3. 「这里面有没有必须强制、不能靠 AI 自觉的红线？」 有。比如「评审过程绝不允许跑写操作命令」。→ 第三步上 Hooks，在 PreToolUse 上挂一个拦截，子代理一旦想跑危险命令就 deny。

同一个任务，三个工具各解决一段问题，顺序由决策树自然推出来，不是凭感觉排的。

反过来，如果任务是「在一个文件里连续改十几处」——走第一问可能值得封个 Skill，但走到第二问「能不能拆成并行几块」就卡住了：这些修改前后依赖、必须串着改，硬上子代理只会徒增 token 消耗和协调成本，更慢更贵。这时就该在决策树这一步降级——停在 Skills，不碰 Subagents。

⚠️ 常见踩坑（第三人称泛化）：新手阶段最常见的弯路，是把 Subagents 当成「更强的单代理」来用——以为开了子代理就更聪明。其实判断标准只有一条，就是决策树的第二问：这个任务能不能真正拆成几块互不依赖、可并行的子任务？ 能（多维度评审、批量审计、多模块探索），才值得为多出来的 token 买单；不能（一个文件里的连续修改），单代理永远更划算。想清楚这一条，能省下大量无效开销。

十、5 个新手常见坑

1. 一上来三个全开。学习曲线陡到劝退。正确做法：先用 Codex 攒手感，需求倒逼着上工具。
2. 把必须每次遵守的规则写进 Skill。Skill 是按需匹配的，不保证每次命中。强制规则进 AGENTS.md，不进 Skill。
3. 囤 Skill。渐进式披露有预算上限，装太多会被缩描述、被省略。起步一两个，按真实痛点增。
4. 乱调 max_depth。默认 1 不要动，深层嵌套 token 指数级涨。要复杂流程就横向拆、串行跑。
5. 指望 PostToolUse Hook 撤销已跑的命令。它撤不了，只能跑完再纠正。要「不让跑」得用 PreToolUse 在执行前拦。

十一、进阶路径：跑两周后下一步

• 第 1 天：用 Codex 干一个真实小任务，不碰任何进阶概念，建立基础手感。
• 第 1 周：发现某套流程重复解释了好几遍，把它写成第一个 SKILL.md（用 $skill-creator 起步），跑顺。
• 第 1 个月：如果在团队里，给项目加上 PreToolUse / PostToolUse Hook 做基础治理；如果常啃大代码库，试一次 explorer 子代理并行探索。
• 更进一步：把成熟流程做成「Skill 定流程 + 自定义 Subagents 并行 + Hooks 兜底」的组合，但每次只加一个能力、加完验证。

十二、自检清单

读完这篇，下面几条你应该能答上来——答不上来说明对应章节要回看：

• [ ] 能复述决策树的三个判断问题：流程反复解释？任务可并行？规则要强制？分别对应哪个工具。
• [ ] 能一句话说清 Skills、Subagents、Hooks 各管哪个维度（剧本 / 班组 / 质检关）。
• [ ] 知道什么内容进 AGENTS.md、什么进 Skill（确定性进前者，按需流程进后者）。
• [ ] 知道 Subagents 只在你明确要求时启动、且更费 token，判断硬标准是「能不能真正拆成可并行的子任务」。
• [ ] 知道 Hooks 是用代码强制、不靠 AI 自觉，且 PostToolUse 撤不了已跑的命令、要拦得用 PreToolUse。
• [ ] 拿一个自己手头的真实任务，能顺着决策树走到该上的那一个工具。

一句话收官

回到开头那张决策树：Skills、Subagents、Hooks 不是要一起学的「高级功能套餐」，而是回答三个不同问题的工具——流程反复解释就上 Skills，任务能真正并行就上 Subagents，规则必须强制就上 Hooks。新手最该做的不是把三个都配好，而是看清自己现在卡在哪个问题上，只上真正需要的那一个。需求倒逼工具，永远比工具找需求稳。

同系列下一步：

• openai-codex-complete-overview
• openai-codex-cli-app-ide-cloud
• openai-codex-prompt-to-task
• openai-codex-context-engineering

• OpenAI Codex MCP 工具配置指南
  跨系列参考：
• claude-code-claude-md-guide
• claude-code-hooks-guide（Hooks 怎么配的逐字段拆解）

外部参考：

• https://developers.openai.com/codex/skills
• https://developers.openai.com/codex/subagents
• https://developers.openai.com/codex/hooks
• https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals（AGENTS.md 对 Skills 的评测数据来源）

📚 更多 Agent 工作流内容：Agent 工作流实战指南：从单个 Agent 到十人团队的完整搭建路径