concepts/customization.md Codex Docs, 2026-03-04 06:20 UTC → 2026-04-30 18:36 UTC

5In Codex, customization comes from a few layers that work together:5In Codex, customization comes from a few layers that work together:

6 6 

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

8- **[Memories](https://developers.openai.com/codex/memories)** for useful context learned from prior work

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

9- **[MCP](https://developers.openai.com/codex/mcp)** for access to external tools and shared systems10- **[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-agents11- **[Subagents](https://developers.openai.com/codex/concepts/subagents)** for delegating work to specialized subagents

11 12 

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.13These are complementary, not competing. `AGENTS.md` shapes behavior, memories

14carry local context forward, skills package repeatable processes, and

15[MCP](https://developers.openai.com/codex/mcp) connects Codex to systems outside the local workspace.

13 16 

14## AGENTS Guidance17## AGENTS Guidance

15 18 

19 22 

20- Build and test commands23- Build and test commands

21- Review expectations24- Review expectations

22- Repo-specific conventions25- repo-specific conventions

23- Directory-specific instructions26- Directory-specific instructions

24 27 

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.28When 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)47 - AGENTS.md Global (for you as a developer)

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

46 49 

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

48 51 

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

50 53 

54Skills are often the best fit for reusable workflows because they support richer instructions, scripts, and references while staying reusable across tasks.57Skills are often the best fit for reusable workflows because they support richer instructions, scripts, and references while staying reusable across tasks.

55Skills are loaded and visible to the agent (at least their metadata), so Codex can discover and choose them implicitly. This keeps rich workflows available without bloating context up front.58Skills are loaded and visible to the agent (at least their metadata), so Codex can discover and choose them implicitly. This keeps rich workflows available without bloating context up front.

56 59 

60Use skill folders to author and iterate on workflows locally. If a plugin

61already exists for the workflow, install it first to reuse a proven setup. When

62you want to distribute your own workflow across teams or bundle it with app

63integrations, package it as a [plugin](https://developers.openai.com/codex/plugins/build). Skills remain the

64authoring format; plugins are the installable distribution unit.

65 

57A skill is typically a `SKILL.md` file plus optional scripts, references, and assets.66A skill is typically a `SKILL.md` file plus optional scripts, references, and assets.

58 67 

59- my-skill/68- my-skill/

89 98 

90| Layer | Global | Repo |99| Layer | Global | Repo |

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

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

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

94 103 

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

105## MCP114## MCP

106 115 

107MCP (Model Context Protocol) is the standard way to connect Codex to external tools and context providers.116MCP (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.117It's especially useful for remotely hosted systems such as Figma, Linear, GitHub, or internal knowledge services your team depends on.

109 118 

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

111 120 

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

113 122 

114- **Host**: Codex123- **Host**: Codex

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

129 138 

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

131 140 

132## Multi-agents141## Subagents

133 142 

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.143You 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 144 

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

137 146 

138## Skills + MCP together147## Skills + MCP together

139 148 

145Build in this order:154Build in this order:

146 155 

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.1561. [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.1572. Install a [plugin](https://developers.openai.com/codex/plugins) when a reusable workflow already exists. Otherwise, create a [skill](https://developers.openai.com/codex/skills) and package it as a plugin when you want to share it.

1493. [MCP](https://developers.openai.com/codex/mcp) when workflows need external systems (Linear, JIRA, docs servers, design tools).1583. [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.1594. [Subagents](https://developers.openai.com/codex/subagents) when you're ready to delegate noisy or specialized tasks to subagents.