learn/best-practices.md Codex Docs, 2026-03-13 18:15 UTC → 2026-04-16 00:46 UTC

78- Keep repo-specific behavior in `.codex/config.toml`78- Keep repo-specific behavior in `.codex/config.toml`

79- Use command-line overrides only for one-off situations (if you use the CLI)79- Use command-line overrides only for one-off situations (if you use the CLI)

80 80 

81[`config.toml`](https://developers.openai.com/codex/config-basic) is where you define durable preferences such as MCP servers, profiles, multi-agent setup, and experimental features. You can edit it directly or ask Codex to update it for you.81[`config.toml`](https://developers.openai.com/codex/config-basic) is where you define durable preferences such as MCP servers, profiles, multi-agent setup, and feature flags. You can edit it directly or ask Codex to update it for you.

82 82 

83Codex ships with operating level sandboxing and has two key knobs that you can control. Approval mode determines when Codex asks for your permission to run a command and sandbox mode determines if Codex can read or write in the directory and what files the agent can access.83Codex ships with operating level sandboxing and has two key knobs that you can control. Approval mode determines when Codex asks for your permission to run a command and sandbox mode determines if Codex can read or write in the directory and what files the agent can access.

84 84 

161- Telemetry or incident summaries161- Telemetry or incident summaries

162- Standard debugging flows162- Standard debugging flows

163 163 

164The `$skill-creator` skill is the best place to start to scaffold the first version of a skill and to use the `$skill-installer` skill to install it locally. One of the most important parts of a skill is the description. It should say what the skill does and when to use it.164The `$skill-creator` skill is the best place to start to scaffold the first version of a skill. Keep the first version local while you iterate. When it's ready to share broadly, package it as a [plugin](https://developers.openai.com/codex/plugins/build). One of the most important parts of a skill is the description. It should say what the skill does and when to use it.

165 165 

166Personal skills are stored in `$HOME/.agents/skills`, and shared team skills166Personal skills are stored in `$HOME/.agents/skills`, and shared team skills

167 can be checked into `.agents/skills` inside a repository. This is especially167 can be checked into `.agents/skills` inside a repository. This is especially

205 205 

206Keep one thread per coherent unit of work. If the work is still part of the same problem, staying in the same thread is often better because it preserves the reasoning trail. Fork only when the work truly branches.206Keep one thread per coherent unit of work. If the work is still part of the same problem, staying in the same thread is often better because it preserves the reasoning trail. Fork only when the work truly branches.

207 207 

208Use Codex’s [multi-agent](https://developers.openai.com/codex/concepts/multi-agents) workflows to offload208Use Codex’s [subagent](https://developers.openai.com/codex/concepts/subagents) workflows to offload bounded

209bounded work from the main thread. Keep the main agent focused on the core209 work from the main thread. Keep the main agent focused on the core problem,

210problem, and use subagents for tasks like exploration, tests, or triage.210 and use subagents for tasks like exploration, tests, or triage.

211 211 

212## Common mistakes212## Common mistakes

213 213