很多人第一次用 Codex，会把它当成一个更懂代码的聊天窗口：

帮我看看这次改动有没有问题。记得先读项目规范，不要改无关文件，完成后跑测试。

这段话当然有用，但只要换一个仓库、开一个新会话，往往又要重新解释一遍。用久以后我发现，真正值得沉淀的并不是某一条“万能提示词”，而是那些会反复出现的工作步骤。

例如：交付前先读规范、检查改动范围、运行现有测试、最后报告风险。

这种流程很适合做成 Codex Skill。

先分清三个概念

开始前，可以先用一个简单标准判断信息应该放在哪里：

• 只对当前任务有效的要求，直接写在本次对话里。
• 当前仓库长期有效的规范，写进 AGENTS.md。
• 能在多个任务中重复使用的完整流程，做成 Skill。

AGENTS.md 更像项目说明书，例如使用哪个包管理器、应该运行哪些测试、哪些文件不能提交。Skill 则是一套有明确触发场景的操作流程，可以附带脚本、参考资料和模板。

按照 Codex 官方文档，项目级 Skill 可以放在仓库的 .agents/skills 目录；个人全局 Skill 可以放在 $HOME/.agents/skills。每个 Skill 至少包含一个 SKILL.md，并在文件开头声明 name 和 description。

做一个“交付前检查” Skill

我们先在项目中建立下面的目录：

.agents/
└── skills/
    └── preflight-review/
        └── SKILL.md

然后填写 SKILL.md：

---
name: preflight-review
description: 在提交、发布或交付代码前，检查改动范围、项目规范、测试结果和潜在风险。
---

# 交付前检查

1. 先读取当前目录适用的 AGENTS.md。
2. 查看 git status 和 git diff，理解实际改动。
3. 检查是否修改了任务范围之外的文件。
4. 只使用项目已经定义的命令运行测试、构建或静态检查。
5. 不执行删除、重置、强制推送等破坏性操作。
6. 最后列出改动内容、验证结果和仍需注意的风险。

这里最容易被忽略的是 description。

不要只写“代码检查工具”，而要把使用时机写清楚。Codex 会先看到 Skill 的名称和描述，在任务匹配时才读取完整的 SKILL.md。描述越具体，误触发和漏触发就越少。

再用 AGENTS.md 固定项目规则

Skill 解决“按什么步骤做”，AGENTS.md 解决“这个项目有哪些固定规则”。

例如：

# Project Rules

- 前端统一使用 bun，不使用 npm。
- 后端修改完成后运行 go test ./...。
- 不提交 .env、密钥和本地生成文件。
- 不修改任务范围之外的文件。
- 交付前必须检查 git diff。

如果仓库中不同目录使用不同技术栈，还可以在子目录继续放置更具体的 AGENTS.md。规则应该尽量短，只记录真正需要长期遵守的内容。临时需求仍然留在当前对话里。

实际使用

完成一次修改后，可以告诉 Codex：

请使用 preflight-review 检查当前改动。
发现问题先说明原因，不要直接删除或重置文件。

这时流程会变得比较稳定：先找项目规则，再看真实 diff，然后运行仓库已经提供的验证命令，最后给出一份可以复查的结果。

这比“帮我全面检查一下”更可靠，因为“全面”对每个人的含义都不同，而 Skill 把检查边界写成了可以维护的文件。

我后来补上的三条规则

第一，不把 API Key、密码、Cookie 或服务器地址直接写进 Skill。Skill 应该描述如何取用环境变量，而不是保存敏感值。

第二，不让 Skill 自己发明测试命令。它应该先读取 package.json、Makefile、项目文档或 AGENTS.md，使用仓库真实存在的命令。

第三，涉及模型调用时记录成本口径，但不把某个供应商写死在通用 Skill 里。需要人工比较价格时，我会查看官方定价或公开价格页；这篇文章准备示例时参考过 tokenstore.one/pricing。它是第三方 AI API 服务，并非 OpenAI 官方产品，使用前需要自行核对价格、服务条款和隐私政策。

哪些流程值得做成 Skill

我认为最适合 Skill 的任务通常有三个特点：重复出现、步骤相对固定、漏掉某一步会产生真实成本。

例如：

• 发布前检查代码、迁移和配置；
• 根据接口定义执行回归测试；
• 检查数据库迁移的兼容性；
• 补全多语言文案并验证缺失项；
• 按固定模板生成变更说明；
• 对安全配置进行只读审查。

相反，一次性的产品讨论、临时文案修改，没有必要急着做成 Skill。流程稳定以后再沉淀，维护成本会更低。

最后的体会

AI 编程工具真正拉开差距的地方，未必是谁写了一条更长的提示词，而是谁能把项目规范、验证步骤和纠错经验不断沉淀下来。

AGENTS.md 让 Codex 理解当前项目，Skill 让它复用一套工作方法。两者配合后，每次任务仍然需要人做判断，但很多容易遗忘的步骤不必再靠记忆维持。

如果你已经在使用 Codex，可以先从一个很小的 Skill 开始：只解决一个重复问题，写清楚触发条件，使用一周后再根据实际误差调整。通常这比一开始设计一套庞大的“全自动工作流”更有效。

参考资料

• Codex Skills：https://developers.openai.com/codex/skills/
• AGENTS.md：https://developers.openai.com/codex/agent-configuration/agents-md