真正高频使用Codex以后很容易遇到一个问题同样的话为什么我每天都在重新说例如每次让Codex修Bug都要重新提醒先复现问题。不要直接重构。找到Root Cause以后再修改。修改完成必须跑测试。最后给我Diff和验证结果。做Code Review时又要重新告诉它先看高风险逻辑。不要纠结格式问题。权限、并发、数据一致性优先。每个问题必须说明影响和修改建议。发布版本时还可能有另一套固定流程检查Git状态 ↓ 运行测试 ↓ Build ↓ 生成Release Notes ↓ 检查Breaking Change ↓ 形成发布清单这些要求第一次写成Prompt没有问题。第二次也可以复制。但如果一个流程已经重复执行十次、几十次还要依赖开发者每次复制一大段Prompt就说明问题已经发生变化这已经不应该继续是一条Prompt而应该变成一个可复用的Workflow。这正是Codex Skills真正有价值的地方。OpenAI当前把Skill定义为一种可复用工作流它可以把指令、参考资料以及可选脚本组织到一个目录中让ChatGPT和Codex在需要时调用而不是每次把整套流程重新塞进Prompt。所以理解Skills最重要的不是SKILL.md怎么写而是先理解什么东西值得从Prompt升级成Skill一、Skill解决的不是“Prompt不会写”而是“流程不能复用”先看普通Prompt。例如帮我检查这个PR重点关注权限、安全、错误处理和并发问题不要纠结格式。如果发现Bug请给出文件、原因、风险和修改建议最后总结是否建议合并。第一次使用完全合理。但如果团队所有PR都希望按照这套方式Review那么问题就出现了。你必须保证每个人记得这套规则复制的是最新版本没有漏掉某一项知道需要运行哪些检查知道结果应该用什么格式输出。这时候Prompt实际上已经开始承担Workflow Definition。而Skill真正做的就是把它从一次性输入Prompt升级成Reusable WorkflowOpenAI目前给出的典型Skill使用场景就包括保存一段已经验证过的Codex工作流、Review规则、测试命令、发布Checklist、设计规范、写作示例或仓库脚本让未来任务直接复用。所以一个很实用的判断标准是只出现一次的要求继续放Prompt。每个任务都必须遵守的项目规则考虑AGENTS.md。经常重复、拥有明确步骤和输出的工作考虑Skill。这三者不要混在一起。二、AGENTS.md和SKILL.md到底有什么区别这是Skills最容易被混淆的地方。很多人已经开始使用AGENTS.md于是自然会问我把工作流都写进AGENTS.md不就行了吗理论上可以写。但长期来看并不合理。OpenAI当前对Codex定制体系的划分其实非常清楚AGENTS.md负责持久项目指导Skills负责可重复工作流MCP负责连接外部工具Subagents负责把工作委派给专门Agent。可以简单理解成AGENTS.md回答在这个项目里永远应该怎么做例如统一使用pnpm 提交前运行pnpm lint 不要直接修改生产数据库 公共API必须保持兼容 修改payments目录时运行make test-paymentsCodex会在开始工作前读取相应AGENTS.md并按照目录层级组合全局与项目指导越靠近当前工作目录的规则可以覆盖更上层的指导。这类内容的特点是长期有效。SKILL.md回答当我要执行某一类任务时具体应该按照什么流程完成例如fix-ci-failure读取失败日志 ↓ 定位首个根因 ↓ 区分代码/依赖/环境错误 ↓ 最小修改 ↓ 重新运行失败检查 ↓ 执行完整测试 ↓ 输出验证证据或者review-security-pr识别安全边界 ↓ 检查身份认证 ↓ 检查权限变化 ↓ 检查Secrets ↓ 检查输入验证 ↓ 输出风险等级这不是项目永远需要加载的规则。只有执行这种任务时才需要。这就是Skill。三、为什么不能把所有东西都塞进AGENTS.md原因其实和Context Engineering有关。假设AGENTS.md同时放代码规范架构说明Review流程Bug排查流程Release流程数据库Migration流程前端设计流程Incident流程测试生成规则。最后它可能越来越长。但今天用户只是修改按钮颜色。Codex还是必须带着大量当前完全用不到的信息进入任务。这就是典型的Always-On Context。而Skill采用的思路更接近Progressive Disclosure。OpenAI当前的Skills机制不会一开始就把所有Skill全文全部塞入上下文。ChatGPT和Codex首先看到Skill的名称和description当系统判断当前任务确实需要某个Skill时才加载完整的SKILL.md。Codex还会限制初始Skill列表占用的上下文预算避免安装大量Skills以后挤占主要任务空间。也就是说AGENTS.md 默认生效的项目规则而Skill 需要时才加载的专门流程这是两者最核心的区别。四、一个Skill实际上由什么组成最简单的Skill并不复杂。OpenAI目前定义的基本目录可以理解成my-skill/ │ ├── SKILL.md │ ├── scripts/ ├── references/ ├── assets/ └── agents/ └── openai.yaml其中真正必须存在的是SKILL.md。其他目录都是按需添加。SKILL.md负责Metadata Workflow Instructions。最基础结构类似--- name: fix-ci-failure description: Diagnose and repair failing CI checks for an existing pull request. --- 具体执行流程……目前至少需要name和description。scripts/适合放真正需要稳定重复执行的脚本。例如收集日志生成测试报告比较Schema处理固定格式数据。references/适合放API说明Runbook团队规范复杂流程文档。而不是把几十页内容全部直接塞进SKILL.md。assets/适合放模板示例静态资源输出骨架。于是Skill真正可以形成Instructions References Scripts Assets这就已经比单独一条Prompt强很多。五、Skill里最重要的一行可能不是Instructions而是description很多人第一次写Skill会把90%的精力放在正文。实际上description非常关键。为什么因为Codex需要先判断当前任务到底要不要调用这个SkillOpenAI明确说明Skill的name和description是Codex决定是否选择它的重要信号如果description过于模糊或者一个Skill承担太多职责就可能出现“不该调用时调用、该调用时又没有调用”的问题。例如下面这个description帮助处理开发任务。几乎没有意义。因为什么叫开发任务修BugReview测试部署重构更合理的方式是Diagnose failing CI checks on an existing pull request, identify the first actionable root cause, make the smallest safe fix, rerun affected checks, and report verification evidence.这样Codex很容易理解什么时候使用。同样重要的是什么时候不要使用。所以一个好的description应该包含三个东西Trigger Scope Boundary也就是什么情况下触发解决什么问题不要扩大到什么范围。六、不要一上来就给Skill写一千行说明这是很容易犯的另一个错误。既然Skill可以保存长期工作流很多人第一反应就是那我把所有经验全部写进去。于是一个Bug Skill逐渐变成项目架构 测试规范 Git规范 错误分类 数据库规则 前端规则 后端规则 几十个案例 全部命令 完整API文档 ……最后SKILL.md变成一份“小型Wiki”。这其实违背了Skill真正的优势。OpenAI目前在Skill Creator和相关实践里都强调一个方向主指令保持简洁需要的资料再通过references和scripts组织。更合理的结构应该像SKILL.md ↓ 定义流程 ↓ 需要详细规则时 ↓ references/ ↓ 需要稳定执行动作时 ↓ scripts/而不是SKILL.md 整个公司的知识库这里其实和上一篇讲的Context Engineering是同一个逻辑不是把信息全部提前加载而是在正确时间加载正确的信息。七、一个真正实用的Bug排查Skill应该怎么设计假设你发现自己每次让Codex修Bug最终都需要不断提醒同样的事情。那么可以做成fix-bugSkill。它真正应该解决的不是帮我修Bug。而是一套稳定执行协议。例如Step 1建立Baseline先确认当前错误能否复现测试现状Build现状。Step 2定位Root Cause明确区分Code Dependency Environment Configuration不要一看到错误就直接修改业务代码。Step 3控制Scope优先修改和Root Cause直接相关的最小文件范围。禁止无关重构顺手升级依赖扩大架构修改。Step 4Implement进行最小必要修改。Step 5Verify重新运行失败测试相关测试必要的Lint / Build。Step 6Evidence最终输出Root Cause Changed Files Why Tests Run Test Results Unverified Areas现在你下一次只需要告诉Codex使用fix-bug处理这个问题。真正变化的只有Bug本身。流程不需要重新定义。这就是Skill真正开始产生复利的地方。八、Skill最大的价值不是省Prompt而是减少“流程漂移”很多人会觉得Skills的主要价值是少打几句话。这其实只是最表面的收益。真正更重要的问题叫Workflow Drift。例如同一个Bug排查流程。第一次你记得修改前跑测试。第二次忘了。第三次记得测试却忘了检查Diff。第四次别人使用时又直接开始重构。于是同一个“标准流程”实际变成User A → Workflow A User B → Workflow B User C → Workflow CSkill解决的就是把个人习惯变成显式协议。以后流程修改也不是告诉团队所有人“以后记得加这一步。”而是修改Skill。例如发现每次修Bug以后都应该检查是否修改了lockfile。那就把它加入Skill。下一次任务自然继承。OpenAI当前也建议从一个已经成功的工作样例开始创建Skill再在真实任务中持续修正如果Skill用了错误测试命令、遗漏Review规则或者输出不符合预期可以直接让Codex把这次纠正更新到Skill里。这其实就是Workflow ↓ Use ↓ Feedback ↓ Update Skill ↓ Better Workflow形成闭环。九、什么时候应该给Skill加入scriptOpenAI当前的Skill Creator默认推荐先从instruction-only开始而不是所有Skill一上来都塞脚本。这个原则很合理。因为很多工作流真正需要的是决策流程。例如Code ReviewBug Root Cause分析架构检查需求拆分。这些事情无法简单写成脚本。但某些动作如果每一次都完全相同就适合script。例如收集CI日志如果每一次都需要执行同样5条命令可以封装。又例如生成API Schema差异报告如果操作是确定性的也适合脚本。我比较推荐一个判断方式需要Agent判断放Instructions。需要Agent查阅放References。需要机器稳定重复执行放Scripts。这个边界比“所有东西都写在SKILL.md”清晰得多。十、Skill应该做多大这是决定Skill最后会不会失控的问题。例如software-development这种Skill基本太大。里面可能同时包含BugFeatureReviewTestingReleaseArchitecture。最后Skill又变成一个万能Prompt。更合理的是拆成fix-bug review-pr write-tests prepare-release investigate-ci migration-check一个Skill最好对应一种相对稳定、可以重复验证的工作流。这样它才容易判断什么时候调用流程是否正确输出是否合格。这和软件设计中的Single Responsibility非常类似一个Skill最好有一个清晰责任。十一、Skill和项目应该放在哪里Codex目前支持不同范围的Skills。用户级Skill可以放在类似~/.codex/skills/这样的用户范围中在不同仓库之间复用仓库范围的Skill则可以随项目保存、提交让团队成员共同使用。所以可以进一步分成Personal Skill例如my-code-review my-debug-workflow my-doc-writing属于个人工作习惯。Repository Skill例如release-payment-service debug-order-sync verify-schema-migration明显依赖具体项目。这种就应该跟Repository走。这和AGENTS.md一样本质是在解决哪些能力属于个人哪些能力属于项目。十二、Skill触发以后也不代表它一定执行正确这是很多人容易产生的一个误区。创建Skill以后Codex成功调用了。并不等于Skill设计成功。真正应该检查至少四件事。OpenAI目前针对Agent Skills的评估方法也把检查分成Outcome、Process、Style和Efficiency几类不仅要看最终任务是否成功还要看Skill是否被正确调用、是否执行了预期步骤、输出是否符合规则以及有没有明显无效操作。可以简单理解成1. Trigger该触发的时候触发了吗2. Process有没有按照预期流程执行3. Outcome任务最终完成了吗4. Efficiency有没有反复搜索执行无关命令读取大量无关内容产生明显流程抖动所以Skill同样需要Verification。十三、一个Skill最容易失败的5种方式真正用起来以后我认为最值得注意的是下面五类。1. Description太宽例如用于代码开发。结果任何任务都可能触发。2. Skill承担太多职责既修Bug又Review又Release。最后没有稳定行为。3. 把项目永久规则塞进Skill比如项目统一使用pnpm。这种应该进入AGENTS.md。4. 没有Definition of DoneSkill只定义做什么。没有定义怎么证明完成。最后很容易停在代码已经生成。5. 一次加入太多规则Skill变成巨型说明书。最终虽然“什么都写了”但Agent真正执行时反而难以识别最重要步骤。这5个问题本质上都指向同一个原则Skill不是知识仓库而是执行协议。十四、真正成熟的Codex配置应该形成四层把最近几篇内容放在一起其实已经能看出一个非常清楚的Codex工程结构。第一层AGENTS.md负责Behavior。告诉Codex在这个项目里应该遵守什么。第二层Skill负责Workflow。告诉Codex这一类任务应该怎样完成。第三层MCP / Tools负责Capability。告诉Agent可以连接哪些外部系统和工具。第四层Subagents负责Delegation。把复杂任务拆给ExplorerImplementerVerifier等专门角色。OpenAI当前对Codex Customization的划分本身也是这几类能力互补而不是彼此替代。最后就形成AGENTS.md 规则 ↓ Skill 流程 ↓ Tools / MCP 能力 ↓ Subagents 执行这时候Codex才逐渐从一个每次都需要重新解释的AI助手变成一个拥有固定规则、可复用流程和工具能力的工程Agent。十五、从Prompt Engineering到Skill Engineering真正变化的是什么最开始使用AI编程我们关注Prompt Engineering。核心问题是这一句话怎么问模型回答更好进入Agent阶段以后我们开始关注Context Engineering。核心问题变成Agent在整个任务生命周期里应该知道什么而Skills继续往前推进了一层Workflow Engineering。它解决的是这类任务以后每一次应该按照什么方式执行可以把三者理解成Prompt 一次沟通Context 一次任务的信息环境Skill 多次任务之间复用的执行经验这也是Skills真正值得关注的原因。它不是又一种Prompt文件。而是开始把成功经验从人的脑子里提取出来变成Agent可以反复执行的流程资产。最后真正长期使用Codex以后我认为判断某段内容要不要做成Skill可以问三个问题第一我是不是已经说过很多次如果只出现一次继续用Prompt。第二这是不是一个明确流程如果只是项目长期规则放AGENTS.md。第三它未来还能不能复用如果同类型任务以后还会持续出现就值得沉淀成Skill。最终一个成熟的Codex工作方式应该越来越少依赖“我记得每次要提醒它什么。”而越来越多依赖Project Rules Reusable Skills Tools Verification当一个优秀的Bug排查过程、PR Review方法、CI修复流程或者Release Checklist第一次跑通以后真正有价值的下一步已经不只是下次我还记得这么做。而是把这次成功变成Codex下次可以直接调用的Skill。从这个角度看SKILL.md真正保存的并不是一组Markdown文字。它保存的是团队解决问题的方法。而当越来越多解决问题的方法可以被结构化、验证并复用以后AI编程也就开始从“每次重新教Agent怎么做”走向“让Agent调用已经沉淀好的工程能力”。这才是Skills真正进入开发工作流之后最值得关注的变化。