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 反而被这些细节干扰抓不住真正重要的约束。必须写的是那些它猜不到、又必须遵守的东西内容类型是否必写原因技术栈和主要依赖必写它猜不到你用的是 Vite 还是 Webpack目录结构和禁区必写防止它乱建文件、乱改生成代码命名和风格约定必写团队协作的底线完整依赖版本号不必写它读 package.json 就行详细 ESLint 规则不必写交给 lint 工具别塞给它业务背景长篇大论慎写占上下文除非真的影响代码决策我现在的做法是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.xstrict 模式 - 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 五花八门我按使用频率和实用性排了个序供你参考Skill 类型典型用途推荐指数备注代码审查类按规范检查代码高配合 AGENTS.md 效果最好文档生成类自动写注释、README高省大量重复劳动排版类LaTeX 等论文、报告排版中依赖本地环境配置稍麻烦图片生成类生成配图、示意图中依赖外部接口注意额度数据处理类清洗、转换数据中按项目需求装建模辅助类竞赛、算法建模低场景太窄按需我的建议是先装代码审查和文档生成这两类它们几乎对所有项目都有用而且不依赖外部服务装完就能用。图片生成、排版这类等你有具体需求了再装避免装一堆用不上的占地方。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.md 是否在正确位置列表里有但调用报错依赖缺失按 SKILL.md 装齐依赖调用后无反应触发条件没匹配换个说法或检查触发描述报权限错误脚本没有执行权限chmod x scripts/*.sh名字冲突两个 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 - 涉及数据处理的改动先调用>