concepts/customization.md +181 −0 added
1# Customization
2
3Customization is how you make Codex work the way your team works.
4
5In Codex, customization comes from a few layers that work together:
6
7- **Project guidance (`AGENTS.md`)** for persistent instructions
8- **[Memories](https://developers.openai.com/codex/memories)** for useful context learned from prior work
9- **Skills** for reusable workflows and domain expertise
10- **[MCP](https://developers.openai.com/codex/mcp)** for access to external tools and shared systems
11- **[Subagents](https://developers.openai.com/codex/concepts/subagents)** for delegating work to specialized subagents
12
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.
16
17## AGENTS Guidance
18
19`AGENTS.md` gives Codex durable project guidance that travels with your repository and applies before the agent starts work. Keep it small.
20
21Use it for the rules you want Codex to follow every time in a repo, such as:
22
23- Build and test commands
24- Review expectations
25- repo-specific conventions
26- Directory-specific instructions
27
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.
29
30**Updating `AGENTS.md`:** Start with only the instructions that matter. Codify recurring review feedback, put guidance in the closest directory where it applies, and tell the agent to update `AGENTS.md` when you correct something so future sessions inherit the fix.
31
32### When to update `AGENTS.md`
33
34- **Repeated mistakes**: If the agent makes the same mistake repeatedly, add a rule.
35- **Too much reading**: If it finds the right files but reads too many documents, add routing guidance (which directories/files to prioritize).
36- **Recurring PR feedback**: If you leave the same feedback more than once, codify it.
37- **In GitHub**: In a pull request comment, tag `@codex` with a request (for example, `@codex add this to AGENTS.md`) to delegate the update to a cloud task.
38- **Automate drift checks**: Use [automations](https://developers.openai.com/codex/app/automations) to run recurring checks (for example, daily) that look for guidance gaps and suggest what to add to `AGENTS.md`.
39
40Pair `AGENTS.md` with infrastructure that enforces those rules: pre-commit hooks, linters, and type checkers catch issues before you see them, so the system gets smarter about preventing recurring mistakes.
41
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.
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.
44
45<FileTree
46 class="mt-4"
47 tree={[
48 {
49 name: "~/.codex/",
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/>
64
65[Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md)
66
67## Skills
68
69Skills give Codex reusable capabilities for repeatable workflows.
70Skills are often the best fit for reusable workflows because they support richer instructions, scripts, and references while staying reusable across tasks.
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.
72
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.
78
79A skill is typically a `SKILL.md` file plus optional scripts, references, and assets.
80
81<FileTree
82 class="mt-4"
83 tree={[
84 {
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/>
96
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).
98
99Example `SKILL.md`:
100
101```md
102---
103name: commit
104description: Stage and commit changes in semantic groups. Use when the user wants to commit, organize commits, or clean up a branch before pushing.
105---
106
1071. Do not run `git add .`. Stage files in logical groups by purpose.
1082. Group into separate commits: feat → test → docs → refactor → chore.
1093. Write concise commit messages that match the change scope.
1104. Keep each commit focused and reviewable.
111```
112
113Use skills for:
114
115- Repeatable workflows (release steps, review routines, docs updates)
116- Team-specific expertise
117- Procedures that need examples, references, or helper scripts
118
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.
120
121| Layer | Global | Repo |
122| :----- | :--------------------- | :--------------------------------------------- |
123| AGENTS | `~/.codex/AGENTS.md` | `AGENTS.md` in repo root or nested directories |
124| Skills | `$HOME/.agents/skills` | `.agents/skills` in repo |
125
126Codex uses progressive disclosure for skills:
127
128- It starts with metadata (`name`, `description`) for discovery
129- It loads `SKILL.md` only when a skill is chosen
130- It reads references or runs scripts only when needed
131
132Skills can be invoked explicitly, and Codex can also choose them implicitly when the task matches the skill description. Clear skill descriptions improve triggering reliability.
133
134[Agent Skills](https://developers.openai.com/codex/skills)
135
136## MCP
137
138MCP (Model Context Protocol) is the standard way to connect Codex to external tools and context providers.
139It's especially useful for remotely hosted systems such as Figma, Linear, GitHub, or internal knowledge services your team depends on.
140
141Use MCP when Codex needs capabilities that live outside the local repo, such as issue trackers, design tools, browsers, or shared documentation systems.
142
143One way to think about it:
144
145- **Host**: Codex
146- **Client**: the MCP connection inside Codex
147- **Server**: the external tool or context provider
148
149MCP servers can expose:
150
151- **Tools** (actions)
152- **Resources** (readable data)
153- **Prompts** (reusable prompt templates)
154
155This separation helps you reason about trust and capability boundaries. Some servers mainly provide context, while others expose powerful actions.
156
157In practice, MCP is often most useful when paired with skills:
158
159- A skill defines the workflow and names the MCP tools to use
160
161[Model Context Protocol](https://developers.openai.com/codex/mcp)
162
163## Subagents
164
165You 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.
166
167[Subagent concepts](https://developers.openai.com/codex/concepts/subagents)
168
169## Skills + MCP together
170
171Skills plus MCP is where it all comes together: skills define repeatable workflows, and MCP connects them to external tools and systems.
172If a skill depends on MCP, declare that dependency in `agents/openai.yaml` so Codex can install and wire it automatically (see [Agent Skills](https://developers.openai.com/codex/skills)).
173
174## Next step
175
176Build in this order:
177
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.
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.
1803. [MCP](https://developers.openai.com/codex/mcp) when workflows need external systems (Linear, GitHub, docs servers, design tools).
1814. [Subagents](https://developers.openai.com/codex/subagents) when you're ready to delegate noisy or specialized tasks to subagents.