把 Codex 变成一支会分工的项目团队：Agents 与 Skills 实战

更新时间：2026-07-27

适用范围：本文面向已经在真实 Git 仓库中使用 Codex，希望把重复流程和专项审查沉淀为项目能力的开发者。公开版说明：内容来自一个持续开发的前后端项目。文中保留了仓库相对目录和经过泛化的工作流名称，移除了项目名、账号、端口、私有远端、凭证、本机绝对路径和敏感正文。示例中的路由脚本、验收分级与归档策略是项目自定义实践，不是 Codex 内置规则。版本提醒：Skills、Custom agents、subagents 和配置字段仍会演进。本文以 2026 年 7 月的项目实现与官方资料为基线，复制配置前请核对文末最新文档。

第一次让 Codex 接手真实项目时，我只有一个 Agent。

它既要理解需求，又要读架构、改代码、跑测试、检查敏感信息、截图、整理文档，最后还要判断能不能提交。小任务尚可，一旦改动跨过客户端、服务端和数据边界，同一个上下文里很快就会塞满搜索结果、测试日志、页面状态和审查意见。

问题并不是模型不够聪明，而是所有职责都挤在同一个角色里。

后来，我把其中两类能力拆了出来：

• •把可重复的做事步骤写成 Skill；
• •把需要独立视角的审查职责写成 Custom agent。

根 Agent 仍然负责理解目标、控制范围和做最终决定，但它不再需要临场发明每一套流程，也不必假装自己能在同一轮思考里同时扮演架构师、安全审查员和测试负责人。

这篇文章想回答的核心问题是：

怎样让 Codex 不只是“会写代码”，而是知道什么时候该走哪条流程、什么时候该请哪位审查员，以及什么证据出现后才算完成？

先分清三个经常混在一起的概念

项目里的 AGENTS.md、.agents/skills/ 和 .codex/agents/ 名字很接近，但职责完全不同。

一句话概括：

AGENTS.md 管默认边界，Skill 管流程，Custom agent 管角色，subagent 是角色真正被派出去工作的那一次。

这里还有一个容易误解的地方：.agents/skills/ 中的 agents 是目录约定的一部分，并不表示“每个 Skill 都是一个 Agent”。Skill 可以完全由当前主 Agent 执行，不需要创建任何 subagent。

这个项目最后形成的结构

当前仓库与 Agents、Skills 直接相关的骨架如下：

这不是一棵“越深越高级”的配置树，而是一条逐步收敛的工作链：

主 Agent 始终是调度者和责任主体。

Skill 不替它决定用户授权，脚本不替它判断业务语义，审查 Agent 也不替它合并最终结论。这种“中央决策、流程复用、专项分工”的结构，比让多个 Agent 自由讨论更容易审计。

再往上一层：全局 Agents 与 Skills 从哪里来

前面的结构只画了仓库内部，Codex 真正工作时还有一个全局层。

官方当前区分两类 Custom agent：

• •个人 Agent 放在 ~/.codex/agents/，可以在不同仓库复用；
• •项目 Agent 放在 .codex/agents/，只为当前仓库提供角色。

Skill 的作者目录不同：

• •个人 standalone Skill 放在 ~/.agents/skills/；
• •项目 Skill 放在仓库的 .agents/skills/；
• •Codex 还会提供 System Skill，插件也可以携带自己的 Skill。

注意这个不对称：

不要因为全局配置文件位于 ~/.codex/config.toml，就把个人 Skill 也默认写进 ~/.codex/skills/。官方当前用于个人 Skill 创作和发现的位置是 ~/.agents/skills/；~/.codex/skills/.system/ 是本机 Codex 提供内置能力的实现位置，不应把它当作个人内容目录直接维护。

这台机器当前有哪些全局 Agent

截至本文更新时间，本机全局层没有自建 ~/.codex/agents/，~/.codex/config.toml 里也没有个人 [agents] 覆盖。

因此，项目外默认使用 Codex 内置的三个基础角色：

进入当前仓库后，项目的三个 Custom agent 才加入可调度角色集合：

也就是说，这个项目不是用自己的角色替换全部内置 Agent，而是在通用探索和执行能力之外，增加了三个了解本仓库红线的专项审查员。

官方允许 Custom agent 覆盖模型、推理强度、sandbox、MCP 和 Skill 设置。当前三个项目角色没有固定模型或 sandbox，所以没有写出的设置继续从显式调度参数、Agent 默认配置和父会话继承。

如果自定义角色与内置角色使用相同 name，自定义角色会优先于内置角色。项目实践中更稳妥的做法仍是使用清晰的独立名称，不要无意间把 explorer 或 worker 变成另一个职责。

这台机器当前有哪些全局 Skill

本机没有个人 ~/.agents/skills/，全局可用 Skill 主要来自两处。

第一处是 Codex 内置的 System Skill：

第二处是全局启用的插件。当前显式启用的插件可以按能力分组：

当前会话还可能通过远程插件机制暴露 Figma、Notion 等 Skill。这里必须区分三个概念：

1. 插件文件出现在本机缓存目录；
2. 插件已经安装并启用；
3. 它贡献的 Skill 或工具在当前会话中实际可调用。

只有缓存文件，不能证明后两项。公开盘点全局能力时，应以当前插件启用配置、Skills 界面和会话实际暴露的能力为准，而不是把缓存目录中的所有 SKILL.md 都算成“我现在拥有的 Skill”。

全局 Skill 与项目 Skill 不会合并成一份

进入仓库后，Codex 会同时发现 System、插件、个人和项目 Skill 的元数据，再根据本轮任务显式或隐式选择最小的适用集合。

如果两个 Skill 恰好使用相同 name，官方当前行为不是把两份正文合并；两者都可能出现在选择器里。因此，这个项目统一使用 project- 前缀，既说明它依赖仓库事实，也降低了与全局 Skill 重名的概率。

可以把当前项目的有效能力池理解为：

“同时可发现”不等于“每轮全部加载”。Skill 使用渐进式披露，主 Agent 先看到元数据，选择后才读取完整正文；Custom agent 也只有在真正创建 subagent 时才启动独立线程。

通用能力与项目约束怎样协同

全局能力更适合解决跨仓库都相同的问题，项目能力负责把它收敛到本仓库的事实和安全边界。

这里最重要的原则是：提供工具的全局 Skill，不自动获得项目动作的授权。

GitHub plugin 能访问远端，不等于可以替用户提交当前工作区；Browser 能点击按钮，不等于可以保存或发布；imagegen 能生成图片，也不等于可以复制参考图中的水印和商业素材。

反过来，项目 Skill 也不需要重新实现所有通用能力。它应该描述“在这个仓库里怎样安全使用”，再调用已经存在的全局脚本、插件或工具。

一次任务可能同时使用多个层级。例如，撰写本文时：

1. openai-docs 负责校准 Agents、Skills 和 subagents 的官方术语；
2. 项目 AGENTS.md 负责工作区保护、公开脱敏和文档验证边界；
3. 文档路由脚本判断这只是轻量文档变化；
4. 因为没有运行行为变化，project-acceptance 不应触发；
5. 因为用户没有要求提交，project-commit-push 也不应触发。

这就是协同，而不是优先选择“全局 Skill”或“项目 Skill”中的某一边。

Skill 的价值不是缩短 Prompt，而是固定完成条件

官方文档把 Skill 定义为包含指令、资源和可选脚本的任务能力。Codex 会先看到 Skill 的 name、description 和路径，真正选择它之后才读取完整的 SKILL.md，需要时再继续读取 references/ 或运行 scripts/。

这叫渐进式披露。

它解决的不只是上下文长度问题，还解决了两个工程问题：

1. 不相关任务不会预加载所有详细流程。
2. 同一类任务的完成标准不会每次临场变化。

一个最小 Skill 只有一个目录和一份 SKILL.md：

真正决定它是否好用的，通常不是正文有多长，而是 description 是否把“何时使用”和“何时不要使用”说清楚。

如果 description 只写“帮助完成项目任务”，它几乎匹配一切，也等于什么都没说。

七个 Skill，不是七份操作手册

这个项目目前有七个仓库级 Skill。它们可以分成三组：

它们并没有试图覆盖“开发项目的一切”。每一个 Skill 都对应一个已经反复出现、步骤相对稳定、做错又有明显成本的场景。

project-acceptance：把“测过了”改写成分级证据

功能验收是最容易被一句“测试通过”掩盖的部分。

这个 Skill 只在本轮改变用户可见行为、API、数据流、主协议、迁移或修复可复现 bug 时启用。纯文档、只读审查、状态确认和后续的纯提交轮都明确排除。

它先运行项目路由，再按语义决定最高风险等级：

关键不是这三个名称，而是它强制区分：

• •自动化测试覆盖了什么；
• •当前用户环境是否真的可用；
• •哪些只是建议用户继续验收；
• •哪些风险仍然没有消失。

隔离数据库里的测试成功，不能证明用户此刻打开的本地服务已经刷新；文件存在，也不能证明页面真的显示正确。这些差异如果不进入流程，最终回复很容易写得比证据更乐观。

project-commit-push：把授权做成流程入口

Git Skill 的第一条不是命令，而是授权解析：

这个 Skill 还固定排除本地对话记录、运维记录、测试报告、调试目录、构建产物、缓存、凭证和用户的无关改动。

它体现了一个很重要的设计原则：

Skill 可以规范已获授权动作的执行方式，但不能把相邻动作自动解释成授权。

“工作流连续”不是扩大权限的理由。

project-conversation-archive 与 project-ops-records：保存知识，但不保存秘密

这两个 Skill 都会写本地文档，但触发条件完全不同。

对话归档只处理显式归档、附件复制、自动归档失败或历史恢复。它保存可见消息、公开决定、必要工具摘要、验证和最终结果，同时排除隐藏指令、内部推理、凭证、私有 payload、私有远端和本机绝对路径。

运维记录只在出现新的、未来可复用的 Git、服务、认证、部署、回滚或排障事实时更新。普通 push 成功、一次性命令输出和“今天又正常运行了一次”都不值得形成流水账。

两者共同解决的是知识留存的边界：

“记录得更多”不等于项目更聪明。没有选择和过期治理的记录，只会成为下一轮 Agent 的噪声。

project-product-screenshots：截图也是一次受控的数据访问

产品截图看起来只是“打开页面，按一下快门”，实际会碰到登录态、私有草稿、账号信息、埋点请求和编辑器自动保存。

这个 Skill 把文章叙事与捕获指令分开：

• •Markdown 负责说这张图要证明什么；
• •JSON manifest 负责 route、viewport、稳定 ID、文件名和最小交互；
• •Playwright 脚本负责确定性执行；
• •人负责逐张判断画面是否真的可用。

捕获脚本默认拦截登录完成后的非只读请求，避免截图过程中意外保存文章、创建 AI 会话、触发点赞或写入分析数据。必须写数据的画面，需要再次取得明确授权，并优先使用一次性数据库或公开 fixture。

这里最有价值的不是自动截图，而是把“截图不会改数据”从愿望变成默认 guardrail。

project-product-videos：先把自然语言变成可验证的场景

视频 Skill 与截图 Skill 共享脱敏和最小写入原则，但多了一层时间轴。

用户描述的是一段旅程：

从文章页打开阅读设置，切换主题，再回到正文。

Skill 会把它转成稳定 selector、显式 action、设备模式、精确分辨率、帧率、预热时间和收尾时间。正式录制前先验证 manifest，再完整 rehearsal，最后才生成视频并检查尺寸与帧率。

这条流程故意把三个结论拆开：

1. 自动化动作可以执行；
2. 视频编码参数正确；
3. 画面节奏和叙事质量合格。

前两项可以机械验证，第三项仍然需要视觉判断。

视频产物、临时 manifest 和原始录制都进入本地调试目录，不默认提交。当前能力只承诺静音视频，也不会因为“录到了一个 MP4”就声称产品演示已经通过。

project-extract-layout-variants：领域 Skill 才是复用价值最高的地方

前几个 Skill 偏向通用工程流程。排版变体 Skill 则把项目特有知识带进了 Codex：

• •怎样从杂志、报纸、手账等参考图中识别语义块；
• •怎样区分页面本身与水印、样机边框、阴影和背景；
• •怎样把参考图中的可编辑区域映射到 Canvas Profile 的 Safe Area，再用 64px Composition Cell 搭结构、16px Layout Cell 调布局、4px Atomic Unit 精修并保存为 atomicRect；
• •什么情况下复用共享骨架；
• •什么情况下必须使用独立的语义 DOM；
• •怎样分别检查结构正确和视觉接近。

它不会把参考图中的每个形状都拆成编辑块，也不会为了“像”而复制水印或暗示拥有商业素材。不可用的照片、插图和图表用结构占位表达，语义文本仍然进入真实 DOM。

这个 Skill 最值得借鉴的设计，是把机器判断和人工判断明确分开：

结构检查通过但没有做视觉比较时，只能说“已实现”，不能说“高保真验收通过”。

它还会在实现改变运行行为后继续调用 project-acceptance。Skill 之间可以组合，但组合的方式应是“一个流程交棒给另一个流程”，而不是把验收规则复制进每份 Skill。

三个 Custom agent，分别看三种失败

Skill 固定“怎么做”，Custom agent 固定“站在哪个角度看”。

当前项目定义了三个项目级审查角色：

这种拆法不是按技术栈分工，而是按失败类型分工。

“一个 Agent 看客户端，一个看服务端”经常会让跨层数据流落在两者之间；“一个看架构，一个看安全，一个看证据”更容易覆盖完整改动。

Agent 文件只保留窄职责

一个公开安全的角色示例可以写成：

官方当前要求 Custom agent 至少包含：

• •name；
• •description；
• •developer_instructions。

还可以覆盖 model、model_reasoning_effort、sandbox_mode、MCP 和 Skill 设置。当前项目的三个角色没有固定模型，因此会按调度参数、Agent 默认配置和父会话逐级继承。

这能避免每个角色过早绑定具体模型，也让主任务根据复杂度统一选择成本与推理强度。

“不要修改”与只读权限不是一回事

当前三个角色都在 developer_instructions 中写了“除非明确要求，否则不要实现修复”。

这是一条行为指令，但不是操作系统级或 Codex sandbox 级的只读隔离。因为这些 TOML 当前没有显式设置 sandbox_mode = "read-only"。

两者的差别很重要：

如果一个角色必须在技术上保证只读，可以在当前 Codex 版本支持的前提下增加只读 sandbox，并验证它需要的命令和工具仍能运行。

公开文章里不应该把“提示词要求只读”描述成“权限上绝对无法写入”。

Custom agent 不会因为文件存在就自动审查

把 TOML 放进 .codex/agents/，只是让 Codex知道有这个角色。

真正开始一次审查，还需要：

• •用户直接要求使用 subagents 或并行审查；
• •适用的 AGENTS.md 明确请求调度；
• •某个 Skill 在合适阶段要求调度。

主 Agent 创建 subagent 后，独立线程读取任务、使用工具并返回摘要。主 Agent 再负责去重、处理冲突和形成最终结论。

因此，Custom agent 是“可调用角色定义”，不是常驻后台服务，也不是每次保存文件都会自动启动的 Hook。

一次真实功能任务怎样串起来

假设用户提出下面的任务：

参考三张杂志效果图，为排版实验室新增两种可编辑布局；完成实现和验证，但先不要提交。

主流程可以这样运行：

注意这条链上没有 Git Skill。

用户明确说“先不要提交”，所以即使实现和验证全部完成，主 Agent 也不能因为“流程已经到最后一步”而自动调用 project-commit-push。

如果用户下一轮说“提交这些布局改动，不要推送”，Git Skill 才会启用，并且只创建本地 commit。

这正是把 Skill 当作授权敏感工作流，而不是快捷命令的原因。

怎样写出一个真正可用的 Skill

经过几轮迭代，我认为一个项目 Skill 至少需要回答六个问题。

1. 什么情况下触发

把最典型的用户表达、对象和场景放进 description 前半段：

不要依赖 Skill 正文补救模糊的 description，因为隐式匹配发生在完整正文加载之前。

2. 什么情况下不触发

排除项不是附属说明，而是防误触的一部分：

好的 Skill 会主动缩小自己的适用范围。

3. 输入事实从哪里来

Skill 不应假设工作区干净、服务一定启动、页面一定使用默认端口，也不应把上次会话的结论当成当前事实。

常见的事实入口包括：

• •git status --short；
• •目标代码和真实调用链；
• •当前文章、manifest 或参考图；
• •项目路由结果；
• •用户明确提供的授权和验收标准。

4. 哪些步骤交给脚本

适合脚本的部分通常具有确定输入和确定输出：

• •manifest schema 校验；
• •路径到风险等级的映射；
• •Playwright 动作回放；
• •视频尺寸、帧率和编码检查；
• •固定格式的静态检查。

不适合脚本替代的部分包括：

• •用户是否授权写入；
• •某次改动在业务上是否高风险；
• •参考图的语义分组；
• •截图是否真正支持文章观点；
• •视觉层级是否已经达到可接受标准。

5. 什么时候必须停下

停止条件能防止 Agent 用想象补齐缺失信息。

例如：

• •参考图分辨率不足，只输出候选规格，不声称高保真实现；
• •两种语义分组会导致完全不同的代码结构，先请求用户选择；
• •画面必须写入真实数据，但用户没有授权，不开启 mutation；
• •当前环境无法安全验收，不用隔离测试冒充真实环境已就绪。

6. 最后必须报告什么

一个流程如果没有稳定输出字段，很容易在最后丢掉关键风险。

当前项目常用的交付字段是：

最终回复不需要机械打印英文标签，但必须覆盖这些事实。

SKILL.md、references/、scripts/ 和 agents/openai.yaml 怎样分工

Skill 目录里的文件也需要单一职责。

如果一条安全红线同时复制在四个位置，半年后一定会出现四个版本。

主规则只保留一份，其他文件通过触发或链接引用它。

怎样决定“做成 Skill”还是“做成 Agent”

可以用下面这张判断表：

几个例子：

• •“每次提交前检查范围并拆分 commit/push 授权”适合 Skill。
• •“从安全角度独立检查这批 diff”适合 Custom agent。
• •“记住所有项目规则”两者都不适合，应该回到轻量 AGENTS.md 和专题文档。
• •“每次 CSS 改动都创建三个 Agent”通常是过度设计。

还有一种常见误区：把同一个流程既写成 Skill，又完整复制进 Agent 指令。

如果审查 Agent 需要验收规则，更合理的做法是让它读取项目路由和必要专题，或调用现有 Skill，而不是维护第二份验收制度。

并行什么时候真的有价值

Subagents 的主要价值有两个：

1. 把搜索结果、日志和中间推理留在独立线程，减轻主线程的上下文噪声；
2. 对互不依赖的任务同时推进。

当前项目最适合并行的场景是：

• •架构、安全、测试三个独立审查角度；
• •多个互不依赖代码区的只读探索；
• •独立测试失败或日志片段的归因；
• •大量文档的分块总结。

需要谨慎的场景是：

• •多个 Agent 同时编辑同一文件；
• •后一个子任务依赖前一个结论；
• •数据迁移、回滚和权限决策需要一个统一负责人；
• •任务很小，协调成本比执行本身更高。

Subagent 会单独消耗模型与工具资源。并行不是免费加速，也不是“Agent 越多，答案越可靠”。

当前项目把并行角色控制在直接、窄职责审查上，而不是让审查 Agent 继续无限派生下一层 Agent。这使责任边界和成本都更容易理解。

怎么验证这些配置不是“写着好看”

Agents 和 Skills 都是文本配置，但不能只靠肉眼相信它们会按预期工作。

这个项目从三个层面验证。

静态结构

• •每个 SKILL.md 都有合法的 name 和清晰 description；
• •每个 Custom agent 都有 name、description 和 developer_instructions；
• •Skill 引用的 scripts 和 references 确实存在；
• •TOML、YAML、JSON 与 Markdown 没有明显格式错误。

工作流断言

项目有专门的检查命令：

它会验证路由脚本的风险分类、必要工作流文本和关键 guardrail。它适合发现某条规则被重命名、路径失效或约束意外删除。

但这仍然只是项目脚本测试。

它不能证明 Codex 客户端已经加载新 Skill，也不能证明一次真实 subagent 调度、权限继承和界面展示全部正常。

真实任务演练

真正的验收需要选择一个可控任务，观察：

1. description 是否让 Skill 在正确场景出现；
2. 不适用场景是否没有误触；
3. Skill 是否按需读取 reference 和运行 script；
4. Agent 是否只返回自己的专项发现；
5. 主 Agent 是否能处理重复或冲突结论；
6. 未获授权的 commit、push、写数据和外部操作是否没有发生；
7. 最终交付有没有区分自动检查、运行态和未覆盖风险。

配置存在、测试通过、真实调度可用，是三个不同结论。

我踩过的几个坑

把 description 写成宣传语

“一个强大的项目验收 Skill”没有可用的触发信息。

更好的写法是直接列出对象、触发词和排除项。description 是路由接口，不是产品广告。

Skill 里只有命令，没有授权

自动化程度越高，越需要先写清楚什么动作没有权限。

截图、视频、Git、归档和部署都可能产生副作用。Skill 的第一阶段应该是解析目标与授权，而不是立刻执行脚本。

Custom agent 职责太宽

“全面审查代码质量”会让多个 Agent 输出相同的命名和格式建议。

窄职责应该能明确说出它负责哪种失败、读取哪些事实、返回什么、默认不做什么。

把提示词约束当成权限隔离

“不要写文件”是有用指令，但不等于工具层没有写权限。

高风险只读角色应结合 sandbox、工具白名单和实际权限测试，而不是只靠一句自然语言。

多个 Agent 同时改同一处

这会把节省的执行时间重新花在冲突、覆盖和整合上。

先从并行只读探索和审查开始。写任务按文件或模块明确所有权，或者直接由主 Agent 串行完成。

为了复用而过早抽象

一个流程只出现一次时，当前 prompt 往往已经足够。

当它重复两三次、步骤稳定、错误成本明确，再抽成 Skill，得到的边界通常更真实。

一个小团队的落地顺序

如果从零开始，我建议按下面的顺序建设：

1. 先写轻量 AGENTS.md，只放默认流程、硬红线、任务路由和完成定义。
2. 记录真实发生过的重复错误，不为想象中的问题提前建系统。
3. 选择一个高频且边界清楚的流程做第一个 Skill，例如验收或 Git 提交。
4. 把确定性部分提取成脚本，把低频规格放进 references。
5. 为 Skill 补充反触发条件、停止条件和固定交付字段。
6. 用专项测试检查路径、元数据、脚本和关键 guardrail。
7. 当主线程经常被某类独立审查占满时，再创建第一个 Custom agent。
8. 先做只读、窄职责 Agent，再尝试并行写任务。
9. 给需要强制只读的角色增加真实权限边界，并做一次演练。
10. 定期删除过时流程，避免 Skill 和 Agent 只增不减。

这个顺序的重点是先建立可靠的单 Agent 工作流，再引入分工。

如果一个项目连“谁能提交、测到什么算完成”都没有说清楚，多几个 Agent 只会更快地产生不一致。

设计检查清单

新建 Skill

• description 是否同时写清触发与不触发场景？
• 是否先检查用户目标、权限和当前事实？
• 是否只处理一类可重复工作流？
• scripts 是否只承担确定性步骤？
• references 是否只在需要时读取？
• 是否写了必须停止或缩小结论的条件？
• 是否明确最终交付字段和剩余风险？
• 是否避免复制已有 Skill、AGENTS.md 或专题文档？

新建 Custom agent

• 角色是否只负责一种清晰失败类型？
• description 是否说明什么时候应调度它？
• developer instructions 是否指定事实入口、优先级和输出格式？
• 是否明确默认只审查，还是允许实现？
• 如果声称只读，是否有 sandbox 或工具层证据？
• 是否需要固定模型和推理强度，还是继承更合适？
• 它的结果能否由主 Agent 简洁合并？
• 并行收益是否大于 token 与协调成本？

官方资料

版本敏感能力以官方文档为准：

• •Customization overview
• •Build skills
• •Plugins
• •Subagents and custom agents
• •Custom instructions with AGENTS.md
• •Configuration Reference

最后一句

一个成熟的 Codex 项目，不是给模型写了一段越来越长的总 Prompt。

它更像一个小型工程组织：

• •AGENTS.md 是共同规则；
• •Skill 是标准作业流程；
• •Custom agent 是专项角色；
• •脚本和测试提供可复查的证据；
• •主 Agent 负责调度、授权边界和最终结论。

真正让 AI 稳定的，不是让它“什么都能做”，而是让它清楚：这次由谁做、按什么流程做、做到哪里必须停，以及拿出什么证据才算完成。