Codex CLI Best Practices

Skills are reusable, composable instruction packages used to extend Codex CLI. They follow the SKILL.md standard and are designed to be narrow, trigger cleanly, and maintain a small context.

Skills can be invoked in two ways:

1. Explicit invocation: Mention the skill directly in the prompt using /skills or by typing $ to open the mention menu.
2. Implicit invocation: Codex automatically selects a skill when the user's task matches the skill's description field.

Because of implicit invocation, the description field is the most critical part of your skill's metadata.

Experimental support allows trusted MCP servers to advertise the codex/sandbox-state-meta capability during the initialize phase.

When a server provides this metadata, Codex automatically augments every tools/call request with a _meta object containing sandbox details, such as sandboxPolicy, codexLinuxSandboxExe, sandboxCwd, and useLegacyLandmark. This enables the MCP server to spawn child processes within the same sandbox environment as the Codex session. This is controlled entirely by the server's initialization response; there is no client-side configuration switch.

{
  "codex/sandbox-state-meta": {
    "sandboxPolicy": { "...": "..." },
    "codexLinuxSandboxExe": "/path/to/codex-linux-sandbox",
    "sandboxCwd": "/workspace",
    "useLegacyLandlock": false
  }
}

Skills allow you to extend Codex's capabilities.

Implementation Guidelines:

• Structure: Skills should be folders, not single files. Use subdirectories like references/, scripts/, and examples/ for progressive disclosure.
• Discovery: Use clear names and description frontmatter in the skill to enable auto-discovery.
• Triggering: Write the description field as a trigger for the model (e.g., "when should I fire?") rather than a summary.
• Content: Focus on "Gotchas" (failure points) and information that pushes Codex out of its default behavior. Avoid stating the obvious or providing prescriptive step-by-step instructions; instead, provide goals and constraints.
• Scaffolding: Use the built-in skill creator to scaffold new skills and maintain a consistent invocation style.

Codex activates skills using two methods:

1. Explicit invocation: Mention the skill directly in your prompt. In the CLI or IDE, use /skills or type $ to insert a skill mention.
2. Implicit invocation: Codex automatically selects a skill when your task matches the skill's description.

Codex uses progressive disclosure: it initially only loads metadata (name, description, path, and agents/openai.yaml) and only loads the full SKILL.md content once the skill is actually selected.

Subagents are custom agents used for specialized tasks. They are registered using TOML configuration files located in .codex/agents/<name>.toml under the [agents.<name>] header.

Key capabilities include:

• Parallel Orchestration: Running multiple subagents simultaneously.
• Batch Processing: Processing tasks via CSV files.
• Global Configuration: You can control subagent behavior globally in your config using the [agents] section with the following keys:
  • max_threads: Limits concurrent subagent execution.
  • max_depth: Limits the depth of agentic reasoning/recursion.
  • job_max_runtime_seconds: Sets a timeout for jobs.

Built-in subagent types include default, worker, and explorer.

[agents.my_special_agent]
role = "..."
# Other agent-specific config

[agents]
max_threads = 4
max_depth = 3
job_max_runtime_seconds = 300

Codex manages marketplace data and plugin caches within $CODEX_HOME (typically ~/.codex/).

• config.toml: Stores marketplace registration entries (e.g., [marketplaces.<name>]).
• .tmp/marketplaces/<marketplace_name>/: The cloned root of the marketplace manifest.
• plugins/cache/<marketplace_name>/<plugin_name>/<version>/.codex-plugin/plugin.json: The actual cached plugin files and their metadata.

Codex searches for hooks.json configuration files at two distinct levels. Both levels are loaded simultaneously, meaning hooks from both locations will execute. Higher-precedence layers do not replace lower-precedence hooks; they are additive.

Memory Extensions are plugins that provide persistent instructions and transient per-run evidence. They are stored in $CODEX_HOME/memories_extensions/<extension_name>/.

• instructions.md: Always loaded if present.
• resources/: Contains per-run artifacts (e.g., 2026-04-18T14-32-05-notes.md).

Lifecycle & Cleanup:

• Resource files in the resources/ directory are automatically pruned if they are older than 7 days during the Phase 2 consolidation process.
• A full memory reset via the TUI or codex debug clear-memories wipes the entire memories_extensions/ directory tree.

$CODEX_HOME/memories_extensions/
└── <extension_name>/
    ├── instructions.md              # always loaded if present
    └── resources/
        └── 2026-04-18T14-32-05-notes.md   # per-run artifact, auto-pruned