concepts/customization.md Codex Docs, 2026-03-05 06:22 UTC → 2026-03-17 00:33 UTC

7- **Project guidance (`AGENTS.md`)** for persistent instructions7- **Project guidance (`AGENTS.md`)** for persistent instructions

8- **Skills** for reusable workflows and domain expertise8- **Skills** for reusable workflows and domain expertise

9- **[MCP](https://developers.openai.com/codex/mcp)** for access to external tools and shared systems9- **[MCP](https://developers.openai.com/codex/mcp)** for access to external tools and shared systems

10- **[Multi-agents](https://developers.openai.com/codex/concepts/multi-agents)** for delegating work to specialized sub-agents10- **[Subagents](https://developers.openai.com/codex/concepts/subagents)** for delegating work to specialized subagents

11 11 

12These are complementary, not competing. `AGENTS.md` shapes behavior, skills package repeatable processes, and [MCP](https://developers.openai.com/codex/mcp) connects Codex to systems outside the local workspace.12These are complementary, not competing. `AGENTS.md` shapes behavior, skills package repeatable processes, and [MCP](https://developers.openai.com/codex/mcp) connects Codex to systems outside the local workspace.

13 13 

19 19 

20- Build and test commands20- Build and test commands

21- Review expectations21- Review expectations

22- Repo-specific conventions22- repo-specific conventions

23- Directory-specific instructions23- Directory-specific instructions

24 24 

25When the agent makes incorrect assumptions about your codebase, correct them in `AGENTS.md` and ask the agent to update `AGENTS.md` so the fix persists. Treat it as a feedback loop.25When the agent makes incorrect assumptions about your codebase, correct them in `AGENTS.md` and ask the agent to update `AGENTS.md` so the fix persists. Treat it as a feedback loop.

44 - AGENTS.md Global (for you as a developer)44 - AGENTS.md Global (for you as a developer)

45- repo-root/45- repo-root/

46 46 

47 - AGENTS.md Repo-specific (for your team)47 - AGENTS.md repo-specific (for your team)

48 48 

49[Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md)49[Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md)

50 50 

87 87 

88Skills can be global (in your user directory, for you as a developer) or repo-specific (checked into `.agents/skills`, for your team). Put repo skills in `.agents/skills` when the workflow applies to that project; use your user directory for skills you want across all repos.88Skills can be global (in your user directory, for you as a developer) or repo-specific (checked into `.agents/skills`, for your team). Put repo skills in `.agents/skills` when the workflow applies to that project; use your user directory for skills you want across all repos.

89 89 

90| Layer | Global | Repo |90| Layer | Global | repo |

91| :----- | :--------------------- | :--------------------------------------------- |91| :----- | :--------------------- | :--------------------------------------------- |

92| AGENTS | `~/.codex/AGENTS.md` | `AGENTS.md` in repo root or nested dirs |92| AGENTS | `~/.codex/AGENTS.md` | `AGENTS.md` in repo root or nested directories |

93| Skills | `$HOME/.agents/skills` | `.agents/skills` in repo |93| Skills | `$HOME/.agents/skills` | `.agents/skills` in repo |

94 94 

95Codex uses progressive disclosure for skills:95Codex uses progressive disclosure for skills:

105## MCP105## MCP

106 106 

107MCP (Model Context Protocol) is the standard way to connect Codex to external tools and context providers.107MCP (Model Context Protocol) is the standard way to connect Codex to external tools and context providers.

108It’s especially useful for remotely hosted systems such as Figma, Linear, Jira, GitHub, or internal knowledge services your team depends on.108It's especially useful for remotely hosted systems such as Figma, Linear, GitHub, or internal knowledge services your team depends on.

109 109 

110Use MCP when Codex needs capabilities that live outside the local repo, such as issue trackers, design tools, browsers, or shared documentation systems.110Use MCP when Codex needs capabilities that live outside the local repo, such as issue trackers, design tools, browsers, or shared documentation systems.

111 111 

112A useful mental model:112One way to think about it:

113 113 

114- **Host**: Codex114- **Host**: Codex

115- **Client**: the MCP connection inside Codex115- **Client**: the MCP connection inside Codex

129 129 

130[Model Context Protocol](https://developers.openai.com/codex/mcp)130[Model Context Protocol](https://developers.openai.com/codex/mcp)

131 131 

132## Multi-agents132## Subagents

133 133 

134You can create different agents with different roles and prompt them to use tools differently. For example, one agent might run specific testing commands and configurations, while another has MCP servers that fetch production logs for debugging. Each sub-agent stays focused and uses the right tools for its job.134You can create different agents with different roles and prompt them to use tools differently. For example, one agent might run specific testing commands and configurations, while another has MCP servers that fetch production logs for debugging. Each subagent stays focused and uses the right tools for its job.

135 135 

136[Multi-agents concepts](https://developers.openai.com/codex/concepts/multi-agents)136[Subagent concepts](https://developers.openai.com/codex/concepts/subagents)

137 137 

138## Skills + MCP together138## Skills + MCP together

139 139 

146 146 

1471. [Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md) so Codex follows your repo conventions. Add pre-commit hooks and linters to enforce those rules.1471. [Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md) so Codex follows your repo conventions. Add pre-commit hooks and linters to enforce those rules.

1482. [Skills](https://developers.openai.com/codex/skills) so you never have the same conversation twice. Skills can include a `scripts/` directory with CLI scripts or pair with [MCP](https://developers.openai.com/codex/mcp) for external systems.1482. [Skills](https://developers.openai.com/codex/skills) so you never have the same conversation twice. Skills can include a `scripts/` directory with CLI scripts or pair with [MCP](https://developers.openai.com/codex/mcp) for external systems.

1493. [MCP](https://developers.openai.com/codex/mcp) when workflows need external systems (Linear, JIRA, docs servers, design tools).1493. [MCP](https://developers.openai.com/codex/mcp) when workflows need external systems (Linear, GitHub, docs servers, design tools).

1504. [Multi-agents](https://developers.openai.com/codex/multi-agent) when you’re ready to delegate noisy or specialized tasks to sub-agents.1504. [Subagents](https://developers.openai.com/codex/subagents) when you're ready to delegate noisy or specialized tasks to subagents.