Appearance
Codex 定制化分三个层次：AGENTS.md 给 Codex 写项目级固定规则（跟着仓库走）；Skills 封装可复用的工作流程（本地 SKILL.md 文件）；MCP 负责连接代码仓库之外的外部系统（Linear、GitHub、Figma 等）。三层分工明确，不互相替代。本文覆盖每层的适用场景、配置方式，以及推荐的搭建顺序。
OpenAI Codex 定制化指南
定制化就是让 Codex 按你们团队的方式工作。Codex 的定制化分几个层次，协同工作：
这几层是互补关系，不是竞争关系：AGENTS.md 塑造行为，Skills 打包可重复的流程，MCP 把 Codex 连接到本地代码之外的系统。
AGENTS.md：项目规则的固化
AGENTS.md 给 Codex 提供持久化的项目指导，随仓库一起存在，在代理开始工作前就已生效。保持简洁。
用来写 Codex 在这个仓库里每次都要遵守的规则，比如：
- 构建和测试命令
- Code review 标准
- 仓库特定的约定
- 针对某个子目录的专项指令
当代理对你的代码库做了错误假设，在 AGENTS.md 里纠正它，并让代理更新 AGENTS.md——这样修复会在未来的所有会话里生效，形成正向反馈循环。
什么时候更新 AGENTS.md
- 重复犯错：同一个错误出现两次，写进去
- 读太多文件：找到对的文件了但读了太多不相关的文档，加路由指导（优先读哪些目录/文件）
- PR 反复收到同样的反馈：同样的 review 意见出现两次以上，写进去
- 在 GitHub 上：在 PR 评论里 tag
@codex让它把建议更新到 AGENTS.md，委托给云端任务自动完成 - 自动化漂移检查：用 automations 定期（比如每天）自动检查 guidance 缺口并建议补充到
AGENTS.md
把 AGENTS.md 和 pre-commit hooks、linters、type checkers 配合使用：基础设施负责强制执行，AGENTS.md 负责传递意图，两者让系统越来越聪明。
文件层级
Codex 可以从多个位置加载指导：
~/.codex/
AGENTS.md # 全局（你个人的开发偏好）
repo-root/
AGENTS.md # 仓库级（团队和项目规则）靠近工作目录的文件优先级更高。全局文件用来配置 Codex 和你的沟通方式（review 风格、详细程度、默认值），仓库文件专注于团队和代码库规则。
完整说明参考：使用 AGENTS.md 自定义指令
Skills：可复用工作流的封装
Skills 给 Codex 提供可复用的能力，适合打包可重复的工作流程。
Skills 通常是一个 SKILL.md 文件，加上可选的脚本、参考文档和资源：
my-skill/
SKILL.md # 必须：指令 + 元数据
scripts/ # 可选：可执行脚本
references/ # 可选：参考文档
assets/ # 可选：模板、资源scripts/ 目录可以放 Codex 在工作流中调用的 CLI 脚本（比如填充测试数据或运行验证）。当工作流需要外部系统时，配合 MCP 一起用。
一个 SKILL.md 的例子
markdown
---
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 的作用域
Skills 可以是全局的（在你的用户目录，所有仓库都可用）或者仓库级（签入到 .agents/skills，团队共享）：
| 层级 | 全局 | 仓库级 |
|---|---|---|
| AGENTS | ~/.codex/AGENTS.md | 仓库根目录或子目录的 AGENTS.md |
| Skills | $HOME/.agents/skills | 仓库的 .agents/skills |
Codex 使用渐进式加载策略：
- 先加载元数据（
name、description）用于发现 - 当 Skill 被选中时才加载
SKILL.md - 仅在需要时读取 references 或运行脚本
Skills 可以显式调用，也可以由 Codex 根据任务描述匹配隐式触发。清晰的 description 能大幅提高自动触发的准确率。
完整说明：Agent Skills
MCP：连接外部系统
MCP（Model Context Protocol）是 Codex 连接外部工具和上下文提供方的标准方式。特别适合那些不在本地仓库里的远程托管系统，比如 Figma、Linear、GitHub 或你团队依赖的内部知识库。
当 Codex 需要本地代码仓库之外的能力时用 MCP：issue trackers、设计工具、浏览器、共享文档系统。
可以这样理解三者的关系：
- Host：Codex
- Client：Codex 内部的 MCP 连接
- Server：外部工具或上下文提供方
MCP 服务端可以暴露：
- Tools（动作）
- Resources（可读数据）
- Prompts（可复用的 prompt 模板）
这种分离让你能清楚地划分信任边界和能力边界——有些服务端主要提供上下文，有些暴露强力动作。
MCP + Skills 的最佳组合：Skill 定义工作流并指定要用哪些 MCP tools，这是最强的组合方式。
Subagents：委托专项任务
你可以创建多个具有不同角色的代理，让它们使用不同的工具。比如一个代理专跑特定的测试命令和配置，另一个代理有 MCP 服务端来拉取生产日志用于调试。每个子代理专注于自己的领域，使用最合适的工具。
完整说明：Subagent 概念
推荐的搭建顺序
按这个顺序搭建，收益最大：
AGENTS.md：写好仓库规则，配好 pre-commit hooks 和 linters，让 Codex 从一开始就遵守你的规范。
Plugins：如果已有适合的 Plugin，先装好复用成熟方案。否则创建 Skill，等你想分享时再打包成 Plugin。
MCP：当工作流需要外部系统时（Linear、GitHub、文档服务器、设计工具）再接入。
Subagents：当你准备好把嘈杂或高度专业化的任务委托出去时再用。
常见问题
Q: AGENTS.md 和 Skills 的核心区别是什么，分别该用在哪里？
A: AGENTS.md 是"规则"：这个仓库里你必须遵守这些约定，每次都生效。Skills 是"流程"：这是一套可复用的工作步骤，需要时调用。简单来说，AGENTS.md 定义约束，Skills 封装流程。
Q: Skills 可以调用 MCP 工具吗？
A: 可以。在 Skill 的 SKILL.md 里声明需要哪些 MCP tools，然后在 agents/openai.yaml 里配置依赖，Codex 会自动安装和连接。
Q: 全局 Skills 和仓库级 Skills 哪个优先？
A: 两者可以共存，不互相覆盖。仓库级 Skills 存在 .agents/skills 里，全局 Skills 在 $HOME/.agents/skills 里，Codex 都能发现和使用。