Codex 实战：AGENTS.md 与 Skills 配置指南

1. 这次 Codex 更新到底改了什么

1.1 从"能写代码"到"能干活"的分水岭

Codex 这次放出来的东西，圈子里讨论度最高的不是模型本身跑分涨了多少，而是它把AGENTS.md和Skills这两套机制真正打通了。我第一时间把手上几个项目迁过去跑了一遍，最直观的感受是：以前你是在跟一个"很会写代码的聊天框"对话，现在你是在指挥一个"知道项目规矩、能自己翻工具箱的实习生"。

这个区别听起来虚，实际用起来差别巨大。举个我自己的例子：之前让 Codex 帮我改一个前端组件的样式，它每次都要我重新贴一遍项目用的 UI 库、目录结构、命名规范，稍微复杂点的改动就开始瞎猜文件路径。现在有了 AGENTS.md，这些上下文一次性写清楚，它自己会去读，改完的文件路径、导入方式、组件命名基本不用我再纠正。

所以这篇东西我打算按"怎么落地"的思路来写，不吹概念。适合两类人看：一类是刚听说 Codex 想上手但被一堆名词劝退的，另一类是已经在用但总觉得"没发挥出全部实力"的。我会把 AGENTS.md 怎么写、Skills 怎么装怎么自己造、踩过的坑怎么绕，全部摊开讲。

1.2 三个核心概念先理清楚

在动手之前，得先把这几个词的关系搞明白，不然很容易混。

Codex是主体，你可以理解成那个干活的"人"。它负责理解你的指令、读文件、写代码、跑命令。

AGENTS.md是给这个"人"看的项目说明书。放在项目根目录，它规定了"在这个项目里你要遵守什么规矩"——用什么技术栈、代码风格怎样、哪些目录不能碰、提交信息怎么写。它解决的是"上下文一致性"问题。

Skills是给这个"人"配的工具箱。一个 Skill 就是一套封装好的能力，比如"生成一张图""做 LaTeX 排版""按某个规范审查代码"。它解决的是"能力扩展"问题。

三者关系一句话：Codex 是执行者，AGENTS.md 告诉它规矩，Skills 给它加装备。你把这三样配齐，它才真正像个能独立干活的角色，而不是一个每次都要从头解释的陌生人。

提示：很多人卡在第一步就是因为把 AGENTS.md 和 Skills 当成一回事。记住，前者是"约束"，后者是"能力"，方向完全不同。

1.3 为什么这次值得重新上手

我去年也试过早期版本的 Codex，当时的感觉是"能用但费劲"，主要问题就是上下文管理太原始，每次对话都像失忆。这次更新之后，AGENTS.md 的读取优先级和 Skills 的加载机制都做了调整，实际体验下来有几个明显变化：

• 项目级配置的生效范围更清晰了，不会再出现"我明明写了规范它却不遵守"的情况
• Skills 的安装和调用路径统一了，不用再手动改一堆配置文件
• 对多文件改动的处理更稳，改完能自己检查引用关系

这些变化单看都不算惊天动地，但叠在一起，就从"玩具"变成了"工具"。下面我按实际操作的顺序，一步步拆。

2. AGENTS.md 怎么写才真正管用

2.1 最小可用版本长什么样

很多人一上来就想写个几百行的规范文档，结果 Codex 读起来反而抓不住重点。我的建议是先从最小可用版本开始，跑通了再逐步加。

一个能立刻见效的 AGENTS.md，核心就四块内容：

# 项目说明 ## 技术栈 - 前端：React 18 + TypeScript + Vite - 样式：Tailwind CSS - 状态管理：Zustand ## 代码规范 - 组件用函数式，禁止 class 组件 - 所有导出必须有类型标注 - 文件命名用 kebab-case ## 目录约定 - 组件放 src/components - 工具函数放 src/utils - 禁止修改 src/generated 下的任何文件 ## 提交规范 - commit message 用中文，格式：类型: 描述

就这么多，先跑起来。你会发现 Codex 生成代码时明显"上道"了，不再给你整出 class 组件或者 camelCase 的文件名。

2.2 哪些内容必须写，哪些写了反而添乱

这里有个反直觉的经验：AGENTS.md 不是越详细越好。我踩过的坑是，一开始把整个 ESLint 配置、所有依赖版本号都抄进去，结果 Codex 反而被这些细节干扰，抓不住真正重要的约束。

必须写的，是那些"它猜不到、又必须遵守"的东西：

我现在的做法是：AGENTS.md 控制在 100 行以内，只写"约束性"内容，把"参考性"内容留给它自己去读文件。

2.3 让规范真正生效的三个细节

写完 AGENTS.md 不代表它就一定遵守，还有几个细节决定成败。

第一，位置要对。AGENTS.md 放在项目根目录，Codex 启动时会自动读取。如果你有多个子项目，可以在子目录再放一份，就近覆盖。我实测下来，子目录的配置优先级更高，这个特性很适合 monorepo。

第二，用命令式语气。别写"我们倾向于使用函数式组件"，直接写"使用函数式组件，禁止 class 组件"。前者是建议，后者是命令，Codex 对命令式表述的遵守率明显更高。

第三，关键约束加粗或单独成段。比如"禁止修改 src/generated"这种硬性红线，我会单独拎出来加粗。实测下来，被强调过的约束，违反概率能降一大截。

注意：AGENTS.md 里不要写任何密钥、token、内部地址。这东西是要进版本库的，写敏感信息等于公开泄露。

2.4 一个真实项目的完整配置拆解

拿我手上一个前端项目举例，完整配置大概是这样，你可以对照着改：

# AGENTS.md ## 项目概述 内部数据看板，React 18 + TS + Vite，部署在内部环境。 ## 技术栈 - React 18.2，函数式组件 + Hooks - TypeScript 5.x，strict 模式 - Tailwind CSS 3.x - 数据请求用 TanStack Query ## 硬性约束 - **禁止修改 src/api/generated 下的文件**（自动生成） - **禁止引入新的第三方 UI 库**，统一用现有组件 - **所有网络请求必须走 src/api/client.ts 封装** ## 代码风格 - 组件文件用 PascalCase，工具文件用 kebab-case - 每个组件必须有 Props 类型定义 - 复杂逻辑抽成自定义 Hook，放 src/hooks ## 提交规范 - 格式：feat/fix/refactor: 中文描述 - 一次提交只做一件事

这份配置我用了两个月，Codex 基本没再犯过"乱引库""乱改生成文件"这类低级错误。关键就在于那三条加粗的硬性约束，把最容易出问题的地方钉死了。

3. Skills 安装与使用全流程

3.1 Skills 到底是什么，和插件有什么区别

先把概念说清楚。Skills 不是传统意义上的"插件"，它更像是一份"操作手册 + 脚本"的组合包。一个 Skill 通常包含一个描述文件（告诉 Codex 这个技能是干嘛的、什么时候用）和若干执行脚本或模板。

和插件的区别在于：插件是往宿主程序里加功能，Skills 是给 Codex 提供"遇到某类任务时该怎么做"的知识。比如一个"图片生成 Skill"，它不是给 Codex 装了个画图引擎，而是告诉它"当用户要生成图片时，调用哪个接口、传什么参数、怎么处理返回结果"。

这个设计的好处是轻量、可组合。你可以按需装，不用为了一个小功能装一整个大插件。

3.2 安装一个 Skill 的标准步骤

不同来源的 Skill 安装方式略有差异，但核心流程是一致的。我以最常见的从代码仓库安装为例：

# 1. 进入你的 Codex 配置目录（通常在用户主目录下） cd ~/.codex # 2. 创建 skills 目录（如果还没有） mkdir -p skills # 3. 把 Skill 克隆或复制进来 git clone <skill-repo-url> skills/<skill-name> # 4. 检查 Skill 的描述文件是否完整 ls skills/<skill-name> # 应该能看到 SKILL.md 或类似的描述文件

装完之后，重启 Codex 或者重新加载配置，它就能识别到这个新技能了。

这里有个容易忽略的点：Skill 的目录名最好和它内部声明的名字一致。我遇到过目录名和内部名字对不上，导致 Codex 加载失败的情况，排查了半天才发现是命名问题。

3.3 手动安装 GitHub 上的 Skill

很多人问怎么手动装 GitHub 上的 Skill，其实就三步，但每步都有坑。

第一步，找到 Skill 的描述文件。一个规范的 Skill 仓库，根目录或子目录里会有一个SKILL.md，里面写明了这个技能的用途、依赖、使用方法。先读这个文件，确认它是不是你要的。

第二步，确认依赖。有些 Skill 依赖特定的命令行工具或 API。比如一个 LaTeX 排版 Skill，可能依赖你本地装了 TeX 环境。装之前先看依赖说明，不然装完调用报错，你还以为是 Skill 本身的问题。

第三步，放到正确的位置并验证。复制到 skills 目录后，用 Codex 的列表命令确认它被识别：

# 列出当前已加载的所有 skills codex skills list

如果列表里没有，检查目录结构对不对、描述文件在不在、名字有没有冲突。

提示：手动装 Skill 时，优先选那些有明确 README 和 SKILL.md 的仓库。没有文档的 Skill，装上去大概率是给自己找麻烦。

3.4 常用 Skill 类型和选型建议

市面上的 Skill 五花八门，我按使用频率和实用性排了个序，供你参考：

我的建议是：先装代码审查和文档生成这两类，它们几乎对所有项目都有用，而且不依赖外部服务，装完就能用。图片生成、排版这类，等你有具体需求了再装，避免装一堆用不上的占地方。

3.5 自己动手写一个 Skill

装别人的不如自己造。写一个 Skill 其实不难，核心就是把"你平时怎么教别人做这件事"写下来。

一个最小 Skill 的结构：

my-skill/ ├── SKILL.md # 描述文件 └── scripts/ └── run.sh # 执行脚本（可选）

SKILL.md 的内容大致这样：

# Skill 名称：代码注释生成 ## 用途 为指定的 TypeScript 文件生成符合 JSDoc 规范的注释。 ## 触发条件 当用户要求"给这个文件加注释"或"生成文档注释"时使用。 ## 执行步骤 1. 读取目标文件 2. 识别所有导出函数和类型 3. 按 JSDoc 格式生成注释 4. 保留原有代码逻辑不变 ## 注意事项 - 不要修改函数签名 - 注释用中文 - 复杂参数要说明类型和含义

就这么简单。写完之后放到 skills 目录，Codex 就能在合适的时候调用它。我自己的经验是，把你重复做过三次以上的事情，都值得封装成一个 Skill。

4. 实操中踩过的坑和排查方法

4.1 配置不生效的常见原因

这是问得最多的问题："我明明写了 AGENTS.md，它怎么还是不遵守？"

按我的排查经验，原因基本逃不出这几个：

文件位置错了。确认 AGENTS.md 在项目根目录，而不是在某个子目录里。如果你在子目录启动 Codex，它读的是那个子目录的配置。

格式有问题。Markdown 的标题层级、列表符号如果写乱了，解析可能出问题。我遇到过用全角符号导致解析失败的情况，换成半角就好了。

内容太模糊。"尽量用函数式组件"这种表述，Codex 可能理解成"可以用也可以不用"。改成"必须用函数式组件"就明确了。

缓存没刷新。改完配置后，重启一下 Codex 或者重新加载，别指望它实时生效。

排查顺序建议：先看位置，再看格式，再看表述，最后重启。

4.2 Skill 加载失败的排查清单

Skill 装完不生效，按这个清单逐条过：

我印象最深的一次是 Skill 调用一直报"找不到命令"，查了半天发现是脚本没加执行权限。这种低级问题最容易浪费时间，所以装完 Skill 第一件事就是检查权限。

4.3 上下文冲突怎么处理

当你装了多个 Skill，又写了详细的 AGENTS.md，有时候会出现"指令打架"的情况。比如 AGENTS.md 说"禁止引入新依赖"，某个 Skill 却建议装个新库。

我的处理原则是：AGENTS.md 的约束优先级最高。因为它是项目级的硬规矩，Skill 只是能力扩展。如果冲突频繁，说明这个 Skill 不适合当前项目，果断卸掉。

另外，Skills 之间也可能冲突。比如两个 Skill 都想处理"生成文档"这个任务，Codex 可能随机选一个。解决办法是在 AGENTS.md 里明确指定"文档生成统一用 XX Skill"。

4.4 性能与额度的实际感受

装了太多 Skill 会拖慢响应速度，这个我实测过。Skills 越多，Codex 每次决策时要考虑的可能性就越多，响应会变慢。

我的建议是：常驻 Skill 控制在 5 个以内，其他的按需临时启用。具体做法是把不常用的 Skill 移出 skills 目录，需要时再放回来。

至于额度消耗，代码审查和文档生成这类纯本地的 Skill 基本不额外消耗，图片生成、外部接口调用这类会消耗额度。用之前心里有个数，别到月底发现额度没了。

5. 进阶玩法与组合技巧

5.1 AGENTS.md 和 Skills 的联动

真正把这两样用出花来的关键，是在 AGENTS.md 里"指挥" Skills。比如：

## Skill 使用约定 - 代码提交前，必须调用 code-review Skill 自检 - 生成文档时，统一使用 doc-gen Skill - 涉及数据处理的改动，先调用>