古法编程

OpenAI Codex 的自定义能力由多层协同完成：AGENTS.md 管项目规则，Memories 记录历史上下文，Skills 复用流程，MCP 连接外部工具，Subagents 负责分派专项任务。把规则写进离工作目录更近的位置，优先级更高；如果技能依赖 MCP，需要在 agents/openai.yaml 里声明，Codex 才能自动安装并连接。

OpenAI Codex 自定义配置与技能

OpenAI Codex 的自定义配置，核心就是让它按你的团队方式工作。

它不是单一开关，而是由几层能力组合而成：

  • Project guidance (AGENTS.md)：持久化项目规则
  • Memories：从之前工作中学到的上下文
  • Skills：可复用的工作流和领域知识
  • MCP：访问外部工具和共享系统
  • Subagents：把任务分给专门的子代理

这些层不是互相替代，而是互补。AGENTS.md 负责塑造行为，memories 负责把本地上下文带到后续任务，skills 负责打包可重复流程，MCP 负责把 Codex 接到本地工作区之外的系统。

AGENTS 指南

AGENTS.md 会为 Codex 提供持久的项目级指导，它跟着代码库走，并且会在 agent 开始工作前生效。内容要短，别堆太多。

适合写进这里的规则包括：

  • 构建和测试命令
  • 代码审查期望
  • 代码库特有约定
  • 目录级别的说明

当 agent 对你的代码库产生错误假设时，直接在 AGENTS.md 里修正，并让 agent 更新 AGENTS.md，这样修复就能保留下来。把它当成一个反馈闭环。

更新 AGENTS.md 的方法： 先只写真正重要的指令；把反复出现的 review 反馈固化进去；把指导放到最接近它生效的目录；当你纠正错误时，让 agent 顺手更新 AGENTS.md，这样后续会话会继承这次修正。

什么时候更新 AGENTS.md

  • 重复犯错：如果 agent 反复犯同一个错误，就加一条规则。
  • 读太多文件：如果它找对了文件，却读了太多无关文档，就补路由提示，说明哪些目录或文件应优先查看。
  • 重复的 PR 反馈：如果你不止一次给出同样的反馈，就把它写成规则。
  • 在 GitHub 里更新：在 pull request 评论里标记 @codex 并写请求，例如 @codex add this to AGENTS.md，可以把更新委派给云端任务。
  • 自动化检查漂移：用 automations 定期运行检查，比如每天一次，找出指导缺口并建议补进 AGENTS.md。

AGENTS.md 最好和能强制执行这些规则的工具配套使用：pre-commit hooks、linters、type checkers 都可以在你看到问题前把它拦住，这样系统会更擅长避免重复错误。

Codex 可以从多个位置加载指导：开发者个人目录里的全局文件，以及团队可以提交进仓库的项目文件。离工作目录更近的文件优先级更高。

全局文件适合调节 Codex 和你沟通的方式，比如 review 风格、输出长度和默认行为；仓库文件则应该专注于团队规则和代码库规则。

相关文档： Custom instructions with AGENTS.md

Skills

Skills 让 Codex 拥有可复用能力，适合重复执行的工作流。

很多情况下，skills 比直接把流程写进提示词更合适，因为它们支持更丰富的指令、脚本和参考资料，同时还能在不同任务之间复用。Skills 会被加载，并且至少会暴露元数据给 agent，这样 Codex 可以自动发现并选择它们，而不用一开始就把大量上下文塞满。

你可以先用 skill 文件夹在本地编写和迭代工作流。若该工作流已经有现成 plugin，先安装 plugin，复用成熟配置。若你要把自己的工作流分发给团队，或者和应用集成打包在一起，就把它做成 plugin。Skills 仍然是编写格式，plugins 才是可安装的分发单元。

一个 skill 通常由一个 SKILL.md 文件，加上可选的脚本、参考资料和资源组成。

一个 skill 目录通常长这样：

  • SKILL.md：必需，包含说明和元数据
  • scripts/：可选，可执行代码
  • references/：可选，文档
  • assets/：可选，模板和资源

skill 目录里可以放 scripts/ 文件夹，里面的 CLI 脚本会被 Codex 在工作流中调用，比如初始化测试数据或运行校验。当工作流还需要外部系统时，比如 issue tracker、设计工具或文档服务器，就把 skill 和 MCP 配合使用。

示例 SKILL.md：

---
name: commit
description: Stage and commit changes in semantic groups. Use when the user wants to commit, organize commits, or clean up a branch before pushing.
---

1. Do not run `git add .`. Stage files in logical groups by purpose.
2. Group into separate commits: feat → test → docs → refactor → chore.
3. Write concise commit messages that match the change scope.
4. Keep each commit focused and reviewable.

Skills 适合用在这些场景：

  • 可重复工作流，比如发布步骤、review 流程、文档更新
  • 团队专属知识
  • 需要示例、参考资料或辅助脚本的流程

Skills 可以放在全局目录，也可以放在仓库里。放到仓库中的 .agents/skills，适合项目内共享；放到用户目录，适合你在所有仓库里复用。

层级 全局 仓库
AGENTS ~/.codex/AGENTS.md 仓库根目录或嵌套目录中的 AGENTS.md
Skills $HOME/.agents/skills 仓库中的 .agents/skills

Codex 使用渐进式披露来加载 skills：

  • 先读取元数据（name、description）用于发现
  • 只有在选中某个 skill 后才加载 SKILL.md
  • 只有在需要时才读取 references 或运行 scripts

你也可以显式调用 skill；当任务与 skill 描述匹配时，Codex 也可能自动选中它。skill 描述写得越清楚，触发就越稳定。

相关文档： Agent Skills

MCP

MCP（Model Context Protocol）是把 Codex 连接到外部工具和上下文提供方的标准方式。

它特别适合远程托管的系统，比如 Figma、Linear、GitHub，或者团队依赖的内部知识服务。

当 Codex 需要本地代码库之外的能力时，就该用 MCP，比如 issue tracker、设计工具、浏览器，或者共享文档系统。

可以这样理解：

  • Host：Codex
  • Client：Codex 里的 MCP 连接
  • Server：外部工具或上下文提供方

MCP servers 可以暴露三类内容：

  • Tools：动作
  • Resources：可读取的数据
  • Prompts：可复用的 prompt 模板

这种拆分方式有助于你判断信任边界和能力边界。有些 server 主要提供上下文，有些则会暴露更强的动作能力。

实际使用中，MCP 常常和 skills 搭配：

  • skill 定义工作流，并说明要使用哪些 MCP tools

相关文档： Model Context Protocol

Subagents

你可以创建不同角色的 agent，并让它们以不同方式使用工具。比如，一个 agent 只负责运行特定测试命令和配置，另一个 agent 则接入 MCP servers 拉取生产日志用于 debug。每个 subagent 都保持聚焦，只做它最适合的事。

相关文档： Subagent concepts

Skills 和 MCP 一起用

Skills 加 MCP，才是最完整的组合：skills 负责定义可重复的工作流，MCP 负责把这些流程接到外部工具和系统上。

如果某个 skill 依赖 MCP，要在 agents/openai.yaml 里声明这个依赖，这样 Codex 才能自动安装并完成连接配置。具体写法可以参考 Agent Skills。

下一步怎么做

建议按这个顺序搭建：

  1. 先用 Custom instructions with AGENTS.md 让 Codex 按你的仓库规范工作，再加 pre-commit hooks 和 linters 去强制执行这些规则。
  2. 如果已有可复用工作流，就先安装 plugin。如果没有，但你想把流程共享出去，就创建 skill 并在之后打包成 plugin。
  3. 当工作流需要 Linear、GitHub、文档服务器或设计工具这类外部系统时，再接入 MCP。
  4. 当你要把噪声大或专业性强的任务交给专门角色处理时，再使用 Subagents。

常见问题

OpenAI Codex 里 AGENTS.md 应该放在哪里

可以放在开发者个人目录的 ~/.codex/AGENTS.md，也可以放在仓库根目录或更深层目录的 AGENTS.md。离工作目录更近的文件优先级更高。

Skills 和 plugin 有什么区别

Skills 是编写工作流的格式，通常包含 SKILL.md、脚本和参考资料；plugin 是可安装的分发单位。已有成熟工作流时，先装 plugin；需要自己沉淀并复用流程时，再写 skill。

skill 依赖外部工具时怎么接入

当 workflow 需要 issue tracker、设计工具或文档服务器时，把 skill 和 MCP 配合使用；如果 skill 依赖 MCP，还要在 agents/openai.yaml 里声明依赖，Codex 才能自动安装和连接。