OpenAI 官方教你怎么用 Codex，其实是在教你怎么写一份「Skill」

摘要：OpenAI 官方的 Codex Manual 里有一套很明确的推荐用法------别把 Codex 当聊天框，把它当工程同事：一个好任务要包含目标、上下文、约束、完成标准；复杂任务先 Plan 再动手；长期项目要靠 AGENTS.md 沉淀规则；跑完一定要验证。本文顺着这套方法论往下拆，你会发现它本质上是在教你怎么写一份结构化的任务说明书，而这份说明书，跟 Agent 生态里的 Skill 是同一个东西。最后聊聊，当每个人都在给自己的 Agent 攒 Skill 时，怎么避免装了一堆不靠谱的东西。

适用人群：正在用 Codex / Claude Code / Cursor 等 Agent 工具写代码的开发者，以及想搞清楚「怎么跟 AI 协作」这件事底层逻辑的人

一、很多人用 Codex，用得像在摇骰子

先说一个很多人都有过的体验。

打开 Codex，丢一句「帮我修一下这个 bug」，然后等结果。结果要么改错了地方，要么改是改了但把别的功能搞挂了，要么干脆一顿操作之后告诉你「我尽力了但没找到问题」。

于是很多人得出一个结论：Codex 不太行，写代码的 AI 还是不靠谱。

但如果你去看 OpenAI 官方的 Codex Manual，会发现问题往往不在 Codex 身上，而在用法上。官方文档里说得很直白：大量效果不好的案例，根源都是把 Codex 当成了一次性问答助手，而不是一个可以配置、验证、持续改进的工程同事。

这句话拆开看，其实是在纠正一个很普遍的认知误区。你跟同事说「帮我修一下那个 bug」，一个刚入职、完全不了解项目的同事，大概率也是懵的。他不知道是哪个 bug，不知道项目原来的设计意图是什么，不知道改了之后要不要跑测试，也不知道改到什么程度才算「修好了」。

Codex 面对一句「帮我修一下这个 bug」，处境跟这个新同事一模一样。它没有偷懒，它是真的信息不够。

二、一个好任务的四个要素：目标、上下文、约束、完成标准

官方给出的建议很具体：一个好的 Codex 任务，最好包含四件事------目标、上下文、约束、完成标准。

拿开头那个「帮我修 bug」的例子对比一下，差距立刻就出来了。

复制代码

❌ 差的任务描述：
「帮我修一下登录跳转的 bug」

✅ 好的任务描述：
目标：修复用户登录成功后跳转失败的问题
上下文：先读一下相关的路由代码和鉴权逻辑，搞清楚现在的跳转链路
约束：不要改动现有的鉴权协议，只改跳转逻辑本身
完成标准：修改后跑一遍测试，最后说明根因是什么、怎么验证的

差别不是「写得更长」，是这四行话分别回答了 Codex 完成任务必须知道的四个问题。

目标告诉它要往哪走，不是泛泛的「优化一下」「看看能不能改善」，而是一个具体的、可判定的结果。上下文 告诉它从哪里开始看，省去它盲目搜索整个代码库的时间，也降低它猜错意图的概率。约束告诉它哪些地方是红线，不能因为「顺手」就把鉴权协议也一起改了------这种越界修改在真实项目里往往比 bug 本身更麻烦。完成标准告诉它什么时候可以停下来，以及停下来之后要不要自证。

这四件事凑齐了，Codex 手里的信息量，才跟一个真正了解需求的工程师差不多。信息给够了，它才有可能干出让人满意的活。反过来想，如果你自己都说不清楚这四点，那本质上是你自己还没想清楚这个任务，这时候指望 Codex 替你想清楚，本身就是不合理的期待。

三、复杂任务先别写代码，先让它 Plan

官方推荐的第二个用法，是关于任务复杂度的分层处理：复杂任务不要直接让 Codex 写代码，先让它做 Plan。

Plan 阶段要做的事情很明确：

markdown 复制代码

Plan 阶段的产出：
1. 读代码，理解现有实现
2. 讲清楚整条链路是怎么跑通的
3. 列出打算改动的点
4. 列出这些改动可能带来的风险

这一步的价值容易被低估。很多人觉得「我都知道要改哪里了，直接让它写不就行了」，但复杂任务的风险往往不在「改哪里」，而在「改了之后牵连了什么」。一个看起来独立的函数，可能被三个完全不相关的模块调用；一个看起来无害的参数调整，可能悄悄改变了某个边界条件下的行为。

先 Plan 再实现，本质上是把「模型的判断」提前暴露出来，让你在真正动手改代码之前，有一次审核的机会。如果 Plan 里的理解链路是错的，你在这一步就能纠正，成本是几句对话；如果直接跳到写代码，等发现理解错了，成本是一堆需要回滚的改动。

这里其实藏着一个更通用的原则：任务越复杂，越应该把"怎么做"和"做"这两步分开。 先对齐方法论，再执行方法论。这个原则不只适用于 Codex，几乎适用于所有人机协作场景，后面还会再回来聊这一点。

四、AGENTS.md：把规矩写一次，用一辈子

如果说前两点是「怎么下发一个任务」，AGENTS.md 解决的是另一个问题------长期项目里，你不可能每次都重新交代一遍规矩。

官方文档里明确提到，长期项目中 AGENTS.md 非常关键，应该写进去的内容包括：

diff 复制代码

AGENTS.md 应该包含：
- 启动命令是什么
- 测试命令是什么
- 代码规范是什么
- 哪些目录绝对不能动
- 什么状态才叫「完成」

这份文件的作用，是把项目级的隐性知识显性化。一个新加入团队的工程师，靠的是老员工口口相传加上踩坑积累，才能搞清楚这些东西。Codex 没有这个学习过程，它每次接到任务都是「刚入职的第一天」，除非你把这些东西写下来，放在它一定会读到的地方。

写一次 AGENTS.md，之后每一个任务，Codex 都能自动带着这些背景知识去执行，不需要你在每次对话里重复「记得用 pnpm 不要用 npm」「测试命令是 pnpm test:unit」「不要动 legacy 目录下的代码」。

这里如果你多想一步，会发现一件挺有意思的事情：AGENTS.md 这个东西，长得跟 Skill 几乎一模一样。

五、往回看一步：这套方法论到底在教你什么

把前面三点放在一起看一遍。

复制代码

好任务的四要素  → 目标 + 上下文 + 约束 + 完成标准
Plan 优先      → 先讲清楚方法，再动手执行
AGENTS.md      → 项目规则、边界、验收标准的固定载体

这三件事拼起来，其实是在教你做同一件事：把一份原本存在你脑子里、模糊的、只有你自己懂的任务知识，转换成一份 Agent 能读懂的、结构化的说明文档。

目标、上下文、约束、完成标准，这四个要素，跟一份标准 Skill 文档里通常包含的「任务目标、执行逻辑、边界条件、使用场景」，几乎是同一套东西换了个名字。AGENTS.md 里写的启动命令、测试命令、代码规范、禁改目录，本质上就是一个项目级 Skill 的「工具链」和「边界条件」两部分。而最后一步「跑测试、lint、类型检查，看报错后继续修」，对应的正是 Skill 体系里常被忽略、但又最关键的「验证机制」。

复制代码

Codex Manual 的推荐用法          Skill 的标准构成
────────────────────────────────────────────────
目标 + 上下文 + 约束 + 完成标准   ≈   MD 文档（任务目标、执行逻辑、边界条件）
Plan（讲清链路、列风险）          ≈   执行前的结构化推理步骤
AGENTS.md（命令、规范、禁区）     ≈   工具链配置 + 边界条件
跑测试、lint、类型检查            ≈   验证机制

换句话说，OpenAI 官方这套「怎么用好 Codex」的方法论，本质上就是在教你怎么给 Codex 写一份临时的、针对当前任务的 Skill。而 AGENTS.md，则是把这份 Skill 从「一次性」升级成「常驻」的做法------写一次，这个项目里的每一次协作都能复用。

这也是为什么官方反复强调「不要把 Codex 当一次性问答助手」。一次性问答，你每次都在从零开始描述任务，Codex 每次都在从零开始理解上下文。而一旦你开始沉淀 AGENTS.md、开始把任务写成结构化的说明，你实际上是在把跟 Codex 的协作，从「一次性对话」升级成「可复用的能力资产」。

这正是 Skill 机制想要解决的核心问题：怎么把一次成功的协作经验，变成下一次可以直接复用的东西，而不是每次都重新造轮子。

六、当每个人都在给自己的 Agent 写 Skill

顺着这个思路往下想，一个自然的结果是：如果写 AGENTS.md、写结构化任务说明这么有用，那大家肯定会开始批量地写、大量地写，甚至把写好的拿出来互相分享。

事实也确实如此。不只是 Codex 场景，Claude Code、Cursor、CatPaw 这些 Agent 工具，都在往「可插拔的 Skill 机制」上靠------你需要什么能力，就装一个对应的 Skill，不需要的时候不占地方。目前各大 Skill 市场加起来，流通的 Skill 已经超过 5 万个，覆盖编程、写作、设计、数据分析、办公自动化等几乎所有你能想到的领域。

生态繁荣是好事，但繁荣的另一面，是前面提到的那套逻辑被规模化之后，产生了一个新问题。

回想一下 AGENTS.md 的价值来源------它之所以有用，是因为里面写的东西是真实的：真实的启动命令、真实的测试命令、真实存在的代码规范。如果一份 AGENTS.md 里写的启动命令根本跑不起来、写的代码规范跟实际代码风格对不上，那这份文件不但没用，还会把 Codex 带偏。

Skill 市场里正在大量发生的，就是这个问题的放大版。一个 Skill 的「能力描述」是开发者自己写的，就像找工作的人自己写简历。我们在实际评测中发现，超过 73% 的 Skill 存在不同程度的能力描述夸大问题。一个只处理过 MySQL 场景的 Skill，描述写成「支持所有主流数据库」；一个接了一个免费新闻接口的 Skill，描述写成「全行业智能资讯引擎」。

Agent 在自主选 Skill 的时候，判断依据主要就是这段描述。描述注水了，Agent 的判断也就跟着失真。这跟前面讲的「垃圾进垃圾出」是同一个道理------你给 Codex 的任务描述如果信息不实，它产出的结果自然也不可靠；Agent 拿到的 Skill 描述如果注水，它选出来的 Skill 自然也靠不住。

装了 Skill 不等于 Agent 就会用对，就像写了 AGENTS.md 不等于内容就是准确的。

七、怎么判断一份「说明书」是不是靠谱

回到 Codex Manual 最后一条建议：一定要验证。跑测试、lint、类型检查，看报错后继续修。

这条建议的底层逻辑，其实适用于所有「靠说明书协作」的场景，不只是代码。它说的是：不要相信一份文档自己怎么说，要看它跑起来到底怎么样。

这个逻辑放到 Skill 选型上，同样成立。一个 Skill 靠不靠谱，不该看它的 Description 写得多漂亮，也不该只看下载量和评分------这些都是「自己怎么说」和「有多少人凑过热闹」，不是「跑得好不好」。真正靠谱的判断依据，是它在真实任务里的执行记录：脚本有没有报错、依赖的接口还活不活着、输出是不是要用户大量返工。

这正是 Deep Skill Finder 想解决的问题。它不看 Skill 自己写的描述，而是从社区里积累的百万级真实执行记录出发，判断一个 Skill 在某类具体任务上的真实表现如何。

用法上也有一个和「写好 Codex 任务」类似的原则：不要只丢关键词，要描述完整的任务。

markdown 复制代码

❌ 「日报」「数据分析」「合同审查」
   → 一堆描述里带这几个字的 Skill，分不清谁真的靠谱

✅ 「每天早上自动搜索 AI 行业最新动态，整理成含摘要和原文链接的日报，
    发到我邮箱，需要真实可用的新闻数据源」
   → 按任务语义匹配，优先推荐在同类任务里真实跑通过的 Skill

这跟 Codex Manual 里「目标 + 上下文 + 约束 + 完成标准」的建议其实是同一套思维在不同场景下的应用：你给 Agent 的信息越具体、越贴近真实任务，它能帮你做出的判断就越准。 无论是让 Codex 帮你写代码，还是让 Agent 帮你挑 Skill，模糊的输入换不来靠谱的输出。

八、总结

把整篇内容捋一遍：

Codex Manual 教的不只是怎么用 Codex，它教的是一套通用的人机协作方法论------把模糊的任务，转换成目标明确、上下文清楚、约束清晰、有验收标准的结构化说明。复杂任务先讲清楚方法再动手，长期项目把规则沉淀成可复用的文档。

这套方法论跟 Skill 的本质是一回事。AGENTS.md 本质上就是一份项目级的 Skill，目标、上下文、约束、完成标准对应的就是 Skill 里的任务目标、执行逻辑、边界条件、验证机制。

规模化之后会出问题。当所有人都在写自己的 Skill、分享自己的 Skill，描述注水、能力边界模糊的问题会被放大，5 万+ 的 Skill 市场里，超过 73% 存在不同程度的描述夸大。

验证永远是最后一道关。不管是 Codex 跑完任务要过测试，还是 Agent 选 Skill 前要看真实执行记录，判断靠不靠谱，永远要看它实际跑出来的结果，而不是它自己怎么说。

Deep Skill Finder 做的事情，就是把「验证」这一步从代码场景搬到 Skill 选型场景，用百万级社区真实执行数据，替你回答那个 Description 回答不了的问题：这个 Skill，在我的具体任务里，到底能不能用。

工具地址 ：meyo.life/skill

获取渠道：

ruby 复制代码

SkillHub：https://skillhub.cn/skills/deep-skill-finder
GitHub： https://github.com/wheelry/deep-skill-finder
ClawHub：https://clawhub.ai/lintong123/skills/deep-skill-finder

如果觉得有帮助，欢迎点赞收藏。你在用 Codex 或其他 Agent 工具时，有没有自己写过 AGENTS.md 或者类似的规则文档？效果怎么样？欢迎在评论区聊聊。