【干货】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 阶段要做的事情很明确Plan 阶段的产出 1. 读代码理解现有实现 2. 讲清楚整条链路是怎么跑通的 3. 列出打算改动的点 4. 列出这些改动可能带来的风险这一步的价值容易被低估。很多人觉得「我都知道要改哪里了直接让它写不就行了」但复杂任务的风险往往不在「改哪里」而在「改了之后牵连了什么」。一个看起来独立的函数可能被三个完全不相关的模块调用一个看起来无害的参数调整可能悄悄改变了某个边界条件下的行为。先 Plan 再实现本质上是把「模型的判断」提前暴露出来让你在真正动手改代码之前有一次审核的机会。如果 Plan 里的理解链路是错的你在这一步就能纠正成本是几句对话如果直接跳到写代码等发现理解错了成本是一堆需要回滚的改动。这里其实藏着一个更通用的原则任务越复杂越应该把怎么做和做这两步分开。先对齐方法论再执行方法论。这个原则不只适用于 Codex几乎适用于所有人机协作场景后面还会再回来聊这一点。四、AGENTS.md把规矩写一次用一辈子如果说前两点是「怎么下发一个任务」AGENTS.md 解决的是另一个问题——长期项目里你不可能每次都重新交代一遍规矩。官方文档里明确提到长期项目中 AGENTS.md 非常关键应该写进去的内容包括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 任务」类似的原则不要只丢关键词要描述完整的任务。❌ 「日报」「数据分析」「合同审查」 → 一堆描述里带这几个字的 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在我的具体任务里到底能不能用。如果觉得有帮助欢迎点赞收藏。你在用 Codex 或其他 Agent 工具时有没有自己写过 AGENTS.md 或者类似的规则文档效果怎么样欢迎在评论区聊聊。