定制 Codex 行为

Customization 的目标，是让 Codex 按你和团队的工作方式运行。

在 Codex 中，customization 由几个层次共同组成：

Project guidance (AGENTS.md)：持久 instructions。
Memories：从过去工作中学到的有用 context。
Skills：可复用 workflows 和 domain expertise。
MCP：连接 external tools 和 shared systems。
Subagents：把工作委派给 specialized subagents。

这些层次是互补关系，不是竞争关系。AGENTS.md 塑造行为；memories 延续本地 context；skills 封装可重复流程；MCP 把 Codex 连接到 local workspace 外的系统。

AGENTS Guidance

AGENTS.md 给 Codex 提供 durable project guidance。这些 guidance 会随 repository 一起存在，并在 agent 开始工作前生效。文件要保持小而清晰。

适合写进 AGENTS.md 的内容：

build and test commands
review expectations
repo-specific conventions
directory-specific instructions

当 agent 对 codebase 做出错误假设时，把正确规则补进 AGENTS.md，并让 agent 更新 AGENTS.md，这样修正能保留下来。把它当成 feedback loop。

更新原则：从真正重要的 instructions 开始；把反复出现的 review feedback codify；把 guidance 放到离适用目录最近的位置；当你纠正 Codex 时，让它把规则更新进 AGENTS.md，让未来 sessions 继承修正。

When to update `AGENTS.md`

场景	做法
Repeated mistakes	agent 反复犯同一个错误时，添加规则。
Too much reading	agent 能找到正确 files，但读了太多无关文档时，添加 routing guidance，说明优先读哪些 directories/files。
Recurring PR feedback	同样 feedback 留了不止一次，就写成规则。
In GitHub	在 pull request comment 中 tag `@codex`，例如 `@codex add this to AGENTS.md`，把更新委派给 cloud task。
Automate drift checks	用 automations 定期检查 guidance gaps，并建议补充 `AGENTS.md`。

AGENTS.md 应该和能执行这些规则的基础设施配合：pre-commit hooks、linters、type checkers 可以在你看到问题前捕获它们，让系统更擅长预防重复错误。

Codex 可以从多个位置加载 guidance：

Codex home directory 中的 global file，面向你这个 developer。
teams 可以 check in 的 repo-specific files。

越靠近 working directory 的 files 优先级越高。

Global file 适合塑造 Codex 如何和你沟通，例如 review style、verbosity、defaults。Repo files 应聚焦 team 和 codebase rules。

常见结构：

~/.codex/
  AGENTS.md        # Global: for you as a developer

repo-root/
  AGENTS.md        # repo-specific: for your team

官方指南：

https://developers.openai.com/codex/guides/agents-md

Skills

Skills 让 Codex 获得可复用能力，适合重复 workflows。

它们通常比单纯写进 prompt 更适合复用，因为 skills 支持更丰富的 instructions、scripts 和 references，同时可以跨 tasks 重复使用。

Skills 会被加载并对 agent 可见，至少 metadata 可见，因此 Codex 可以发现并隐式选择它们。这让复杂 workflow 不必一开始就塞满 context。

用 skill folders 在本地 author 和 iterate workflows。如果已有 plugin 能覆盖该 workflow，优先安装 plugin 复用成熟 setup。当你想把自己的 workflow 分发给团队，或把它和 app integrations 打包在一起时，把它 package 成 plugin。Skills 是 authoring format；plugins 是 installable distribution unit。

一个 skill 通常包含 SKILL.md，以及可选的 scripts、references、assets。

my-skill/
  SKILL.md         # Required: instructions + metadata
  scripts/         # Optional: executable code
  references/      # Optional: documentation
  assets/          # Optional: templates, resources

如果 workflow 需要 seed data 或 validations，可以把 CLI scripts 放在 scripts/ folder 中，Codex 会在 workflow 中调用。若 workflow 依赖 external systems，例如 issue trackers、design tools 或 docs servers，把 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 适合：

repeatable workflows，例如 release steps、review routines、docs updates
team-specific expertise
需要 examples、references 或 helper scripts 的 procedures

Skills 可以是 global，也可以是 repo-specific：

Layer	Global	Repo
AGENTS	`~/.codex/AGENTS.md`	repo root 或 nested directories 中的 `AGENTS.md`
Skills	`$HOME/.agents/skills`	repo 中的 `.agents/skills`

当 workflow 只适用于某个 project，把 repo skills 放在 .agents/skills。跨所有 repos 都想用的 skills 放在 user directory。

Codex 对 skills 使用 progressive disclosure：

先读取 metadata，也就是 name 和 description，用于 discovery。
只有 skill 被选择时，才加载 SKILL.md。
只有需要时，才读 references 或运行 scripts。

Skills 可以显式调用；当 task 匹配 skill description 时，Codex 也可以隐式选择它们。清晰的 skill descriptions 能提升触发可靠性。

Agent Skills 文档：

https://developers.openai.com/codex/skills

MCP

MCP，也就是 Model Context Protocol，是把 Codex 连接到 external tools 和 context providers 的标准方式。

它特别适合远程托管系统，例如 Figma、Linear、GitHub，或团队依赖的 internal knowledge services。

当 Codex 需要 local repo 外的能力时使用 MCP，例如：

issue trackers
design tools
browsers
shared documentation systems

理解 MCP 的一种方式：

角色	含义
Host	Codex
Client	Codex 内部的 MCP connection
Server	external tool 或 context provider

MCP servers 可以暴露：

Tools：actions
Resources：readable data
Prompts：reusable prompt templates

这种分离有助于理解 trust 和 capability boundaries。有些 servers 主要提供 context，另一些会暴露强 action。

实践中，MCP 和 skills 搭配最有价值：skill 定义 workflow，并说明要使用哪些 MCP tools。

MCP 文档：

https://developers.openai.com/codex/mcp

Subagents

你可以创建不同 roles 的 agents，并提示它们用不同方式使用 tools。

例如：

一个 agent 专门运行特定 testing commands 和 configurations。
另一个 agent 配置 MCP servers，用来获取 production logs 并辅助 debugging。

每个 subagent 都保持 focused，并使用适合自己工作的 tools。

Subagent concepts：

https://developers.openai.com/codex/concepts/subagents

Skills + MCP together

Skills + MCP 是这套 customization 的组合点：skills 定义可重复 workflows，MCP 把它们连接到 external tools 和 systems。

如果某个 skill 依赖 MCP，在 agents/openai.yaml 中声明该 dependency，这样 Codex 可以自动 install 并 wire。详见 Agent Skills。

Next step

建议按这个顺序建设：

先用 Custom instructions with AGENTS.md 让 Codex 遵守 repo conventions，并用 pre-commit hooks 和 linters 强制这些规则。
当已有 reusable workflow 时，安装 plugin。否则创建 skill，需要分享时再 package 成 plugin。
当 workflows 需要 external systems，例如 Linear、GitHub、docs servers、design tools 时，再接入 MCP。
当你准备把 noisy 或 specialized tasks 委派出去时，再使用 Subagents。