自定义

自定义是让你使 Codex 的工作方式与你的团队工作方式保持一致的方法。

在 Codex 中，自定义源自几个协同工作的层级

• 项目指导 (AGENTS.md)，用于持久的指令
• 记忆 (Memories)，用于从先前工作中获取有用的上下文
• 技能 (Skills)，用于可重用的工作流和领域专业知识
• MCP，用于访问外部工具和共享系统
• 子代理 (Subagents)，用于将工作委派给专业的子代理

这些是互补而非竞争的关系。AGENTS.md 塑造行为，记忆承载本地上下文，技能封装可重复的流程，而 MCP 将 Codex 连接到本地工作区之外的系统。

AGENTS 指导

AGENTS.md 为 Codex 提供持久的项目指导，它会随你的存储库一起移动，并在代理开始工作前生效。请保持其精简。

将其用于你希望 Codex 在该存储库中每次都遵循的规则，例如：

• 构建和测试命令
• 审查期望
• 存储库特定的约定
• 特定目录的指令

当代理对你的代码库做出错误假设时，请在 AGENTS.md 中更正它们，并要求代理更新 AGENTS.md，以便修复能够持久化。将其视为一个反馈闭环。

何时更新 AGENTS.md

• 反复出现的错误：如果代理反复犯同样的错误，请添加一条规则。
• 阅读过多：如果它找到了正确的文件但阅读了过多的文档，请添加路由指导（优先处理哪些目录/文件）。
• 反复出现的 PR 反馈：如果你不止一次给出相同的反馈，请将其编码成规则。
• 在 GitHub 中：在 pull request 的评论中，标记 @codex 并发出请求（例如：@codex add this to AGENTS.md），以将更新委托给云端任务。
• 自动化偏差检查：使用 自动化 (automations) 运行周期性检查（例如每日检查），寻找指导缺口，并建议添加到 AGENTS.md 的内容。

将 AGENTS.md 与强制执行这些规则的基础设施配合使用：预提交钩子 (pre-commit hooks)、代码校验工具 (linters) 和类型检查器会在你看到问题之前捕获它们，从而使系统在防止重复错误方面变得更加智能。

Codex 可以从多个位置加载指导：你 Codex 主目录中的全局文件（针对你个人开发者），以及团队可以签入的存储库特定文件。离工作目录越近的文件优先级越高。使用全局文件来塑造 Codex 与你交流的方式（例如审查风格、详细程度和默认设置），并将存储库文件重点放在团队和代码库规则上。

使用 AGENTS.md 的自定义指令

技能

技能 (Skills) 为 Codex 提供了可重用的能力，用于处理可重复的工作流。技能通常最适合用于可重用的工作流，因为它们支持更丰富的指令、脚本和引用，同时在不同任务间保持可重用性。技能会被加载并对代理可见（至少是它们的元数据），因此 Codex 可以发现并隐式选择它们。这使得丰富的流程无需在前期占用过多上下文空间即可保持可用。

使用技能文件夹在本地编写和迭代工作流。如果工作流已有现有插件，请先安装它以重用经验证的设置。当你希望在团队间分发自己的工作流或将其与应用集成捆绑时，请将其封装为 插件 (plugin)。技能仍然是编写格式；插件是可安装的分发单元。

一个技能通常是一个 SKILL.md 文件，外加可选的脚本、引用和资源。

技能目录可以包含一个 scripts/ 文件夹，其中存放 Codex 作为工作流一部分调用的 CLI 脚本（例如种子数据或运行验证）。当工作流需要外部系统（问题追踪器、设计工具、文档服务器）时，请将技能与 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.

技能适用于

• 可重复的工作流（发布步骤、审查例程、文档更新）
• 团队特定的专业知识
• 需要示例、参考或辅助脚本的流程

技能可以是全局的（在你的用户目录中，针对你个人开发者）或存储库特定的（签入到 .agents/skills 中，针对你的团队）。当工作流适用于特定项目时，请将存储库技能放入 .agents/skills；对于你希望在所有存储库中使用的技能，请使用你的用户目录。

Codex 对技能使用渐进式披露

• 它首先加载元数据（name, description）以供发现
• 它仅在选择某项技能时才加载 SKILL.md
• 它仅在需要时读取引用或运行脚本

技能可以被显式调用，Codex 也可以在任务与技能描述匹配时隐式选择它们。清晰的技能描述可提高触发的可靠性。

代理技能

MCP

MCP (Model Context Protocol，模型上下文协议) 是将 Codex 连接到外部工具和上下文提供程序的标准方式。它特别适用于远程托管的系统，如 Figma、Linear、GitHub 或你的团队所依赖的内部知识服务。

当 Codex 需要本地存储库之外的功能（如问题追踪器、设计工具、浏览器或共享文档系统）时，请使用 MCP。

一种思考方式

• 主机 (Host)：Codex
• 客户端 (Client)：Codex 内部的 MCP 连接
• 服务器 (Server)：外部工具或上下文提供程序

MCP 服务器可以公开

• 工具 (Tools)（操作）
• 资源 (Resources)（可读取的数据）
• 提示词 (Prompts)（可重用的提示词模板）

这种分离有助于你理清信任和能力边界。一些服务器主要提供上下文，而另一些则公开强大的操作。

在实践中，MCP 与技能配合使用时通常最为有用

• 技能定义工作流并指定要使用的 MCP 工具

模型上下文协议 (MCP)

子 Agent

你可以创建具有不同角色和不同任务的代理，并让它们以不同方式使用工具。例如，一个代理可能运行特定的测试命令和配置，而另一个代理则拥有获取生产日志以进行调试的 MCP 服务器。每个子代理都保持专注，并为自己的工作使用正确的工具。

子代理概念

技能 + MCP 协同工作

技能加上 MCP 是这一切融合的地方：技能定义了可重复的工作流，而 MCP 将它们连接到外部工具和系统。如果一个技能依赖于 MCP，请在 agents/openai.yaml 中声明该依赖关系，以便 Codex 可以自动安装和连接它（请参阅 代理技能）。

下一步

按此顺序构建

1. 使用 AGENTS.md 进行自定义指导，以便 Codex 遵循你的存储库约定。添加预提交钩子和代码校验工具来强制执行这些规则。
2. 当可重用的工作流已存在时，安装 插件 (plugin)。否则，创建一个 技能 (skill)，并在想要分享时将其封装为插件。
3. MCP，当工作流需要外部系统（Linear、GitHub、文档服务器、设计工具）时。
4. 子代理 (Subagents)，当你准备将嘈杂或专门的任务委托给子代理时。