真正高频使用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 Workflow

OpenAI目前给出的典型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-payments

Codex会在开始工作前读取相应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需要先判断：

当前任务到底要不要调用这个Skill？

OpenAI明确说明，Skill的 name 和 description 是Codex决定是否选择它的重要信号；如果description过于模糊或者一个Skill承担太多职责，就可能出现“不该调用时调用、该调用时又没有调用”的问题。

例如下面这个description：

帮助处理开发任务。

几乎没有意义。

因为：

什么叫开发任务？

修Bug？

Review？

测试？

部署？

重构？

更合理的方式是：

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-bug

Skill。

它真正应该解决的不是：

帮我修Bug。

而是一套稳定执行协议。

例如：

Step 1：建立Baseline

先确认：

当前错误能否复现；

测试现状；

Build现状。

---

Step 2：定位Root Cause

明确区分：

Code
Dependency
Environment
Configuration

不要一看到错误就直接修改业务代码。

---

Step 3：控制Scope

优先修改：

和Root Cause直接相关的最小文件范围。

禁止：

无关重构；

顺手升级依赖；

扩大架构修改。

---

Step 4：Implement

进行最小必要修改。

---

Step 5：Verify

重新运行：

失败测试；

相关测试；

必要的Lint / Build。

---

Step 6：Evidence

最终输出：

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 C

Skill解决的就是：

把个人习惯变成显式协议。

以后流程修改也不是：

告诉团队所有人：

“以后记得加这一步。”

而是：

修改Skill。

例如发现：

每次修Bug以后都应该检查是否修改了lockfile。

那就把它加入Skill。

下一次任务自然继承。

OpenAI当前也建议从一个已经成功的工作样例开始创建Skill，再在真实任务中持续修正；如果Skill用了错误测试命令、遗漏Review规则或者输出不符合预期，可以直接让Codex把这次纠正更新到Skill里。

这其实就是：

Workflow
↓
Use
↓
Feedback
↓
Update Skill
↓
Better Workflow

形成闭环。

---

九、什么时候应该给Skill加入script？

OpenAI当前的Skill Creator默认推荐先从 instruction-only 开始，而不是所有Skill一上来都塞脚本。

这个原则很合理。

因为很多工作流真正需要的是：

决策流程。

例如：

Code Review；

Bug Root Cause分析；

架构检查；

需求拆分。

这些事情无法简单写成脚本。

但某些动作如果每一次都完全相同，就适合script。

例如：

收集CI日志

如果每一次都需要执行同样5条命令，

可以封装。

又例如：

生成API Schema差异报告

如果操作是确定性的，

也适合脚本。

我比较推荐一个判断方式：

需要Agent判断

放Instructions。

需要Agent查阅

放References。

需要机器稳定重复执行

放Scripts。

这个边界比：

“所有东西都写在SKILL.md”

清晰得多。

---

十、Skill应该做多大？

这是决定Skill最后会不会失控的问题。

例如：

software-development

这种Skill基本太大。

里面可能同时包含：

Bug；

Feature；

Review；

Testing；

Release；

Architecture。

最后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 Done

Skill只定义：

做什么。

没有定义：

怎么证明完成。

最后很容易停在：

代码已经生成。

---

5. 一次加入太多规则

Skill变成巨型说明书。

最终虽然“什么都写了”，但Agent真正执行时反而难以识别最重要步骤。

这5个问题本质上都指向同一个原则：

Skill不是知识仓库，而是执行协议。

---

十四、真正成熟的Codex配置，应该形成四层

把最近几篇内容放在一起，其实已经能看出一个非常清楚的Codex工程结构。

第一层：AGENTS.md

负责：

Behavior。

告诉Codex：

在这个项目里应该遵守什么。

---

第二层：Skill

负责：

Workflow。

告诉Codex：

这一类任务应该怎样完成。

---

第三层：MCP / Tools

负责：

Capability。

告诉Agent：

可以连接哪些外部系统和工具。

---

第四层：Subagents

负责：

Delegation。

把复杂任务拆给：

Explorer；

Implementer；

Verifier

等专门角色。

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真正进入开发工作流之后，最值得关注的变化。