concepts/customization.md Codex Docs, 2026-03-18 12:23 UTC → 2026-05-05 23:00 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- **[Subagents](https://developers.openai.com/codex/concepts/subagents)** for delegating work to specialized subagents11- **[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 

39Codex can load guidance from multiple locations: a global file in your Codex home directory (for you as a developer) and repo-specific files that teams can check in. Files closer to the working directory take precedence.42Codex can load guidance from multiple locations: a global file in your Codex home directory (for you as a developer) and repo-specific files that teams can check in. Files closer to the working directory take precedence.

40Use the global file to shape how Codex communicates with you (for example, review style, verbosity, and defaults), and keep repo files focused on team and codebase rules.43Use the global file to shape how Codex communicates with you (for example, review style, verbosity, and defaults), and keep repo files focused on team and codebase rules.

41 44 

42- ~/.codex/45<FileTree

43 46 class="mt-4"

44 - AGENTS.md Global (for you as a developer)47 tree={[

45- repo-root/48 {

46 49 name: "~/.codex/",

47 - AGENTS.md repo-specific (for your team)50 open: true,

51 children: [

52 { name: "AGENTS.md", comment: "Global (for you as a developer)" },

53 ],

54 },

55 {

56 name: "repo-root/",

57 open: true,

58 children: [

59 { name: "AGENTS.md", comment: "repo-specific (for your team)" },

60 ],

61 },

62 ]}

63/>

48 64 

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

50 66 

54Skills are often the best fit for reusable workflows because they support richer instructions, scripts, and references while staying reusable across tasks.70Skills 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.71Skills 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 72 

57A skill is typically a `SKILL.md` file plus optional scripts, references, and assets.73Use skill folders to author and iterate on workflows locally. If a plugin

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

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

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

77authoring format; plugins are the installable distribution unit.

58 78 

59- my-skill/79A skill is typically a `SKILL.md` file plus optional scripts, references, and assets.

60 80 

61 - SKILL.md Required: instructions + metadata81<FileTree

62 - scripts/ Optional: executable code82 class="mt-4"

63 - references/ Optional: documentation83 tree={[

64 - assets/ Optional: templates, resources84 {

85 name: "my-skill/",

86 open: true,

87 children: [

88 { name: "SKILL.md", comment: "Required: instructions + metadata" },

89 { name: "scripts/", comment: "Optional: executable code" },

90 { name: "references/", comment: "Optional: documentation" },

91 { name: "assets/", comment: "Optional: templates, resources" },

92 ],

93 },

94 ]}

95/>

65 96 

66The skill directory can include a `scripts/` folder with CLI scripts that Codex invokes as part of the workflow (for example, seed data or run validations). When the workflow needs external systems (issue trackers, design tools, docs servers), pair the skill with [MCP](https://developers.openai.com/codex/mcp).97The skill directory can include a `scripts/` folder with CLI scripts that Codex invokes as part of the workflow (for example, seed data or run validations). When the workflow needs external systems (issue trackers, design tools, docs servers), pair the skill with [MCP](https://developers.openai.com/codex/mcp).

67 98 

87 118 

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.119Skills 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 120 

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

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

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

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

145Build in this order:176Build in this order:

146 177 

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.1781. [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.1792. 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, GitHub, docs servers, design tools).1803. [MCP](https://developers.openai.com/codex/mcp) when workflows need external systems (Linear, GitHub, docs servers, design tools).

1504. [Subagents](https://developers.openai.com/codex/subagents) when you're ready to delegate noisy or specialized tasks to subagents.1814. [Subagents](https://developers.openai.com/codex/subagents) when you're ready to delegate noisy or specialized tasks to subagents.