OpenAI: Codex customization documentation

Sources:

• Customization overview
• Build skills
• Build plugins
• Hooks
• Advanced configuration
• Rules
• MCP
• Subagents

Evidence type: current product documentation checked on 2026-07-13. This dossier fills implementation details not present in the original OpenAI blog posts.

Customization model

The surfaces answer different questions:

• Put durable rules and commands for every repository task in AGENTS.md.
• Put a repeatable procedure with references or scripts in a skill.
• Put an installable, versioned workflow and integration bundle in a plugin.
• Use a hook for deterministic work at lifecycle boundaries.
• Use a rule or managed policy to allow, prompt for, or forbid command prefixes.
• Use an MCP server or app connector for live data or actions outside the repository.
• Use a subagent for isolated specialised or high-volume work.

Mixed needs should compose surfaces. For example, AGENTS.md can require a release skill, the skill can call a script and MCP tool, a rule can constrain the release command, and a hook can record the result.

OpenAI documents complementary layers: AGENTS.md for persistent repository behavior, skills for reusable workflows, MCP for external systems, and subagents for specialized delegated work. Project .codex/config.toml adds trusted-repository configuration such as MCP servers, hooks, rules context, and agent profiles.

The placement guidance is explicit: keep AGENTS.md small; use repo skills for project workflows and user skills across repositories; pair skills with MCP when a procedure needs external tools or current data.

A complete repository can therefore use this placement reference:

AGENTS.md
.agents/
├── skills/
│   └── release/
│       ├── SKILL.md
│       ├── agents/openai.yaml
│       ├── scripts/
│       ├── references/
│       └── assets/
└── plugins/
    └── marketplace.json
.codex/
├── config.toml
├── hooks.json
└── rules/
    └── default.rules
plugins/
└── release-tools/
    ├── .codex-plugin/plugin.json
    ├── skills/
    ├── hooks/hooks.json
    ├── .mcp.json
    ├── .app.json
    └── assets/

Not every repository needs every layer; this is not a minimum scaffold.

Skills

Codex follows the Agent Skills format: required SKILL.md, optional scripts/, references/, assets/, and agents/openai.yaml. Metadata is disclosed first and the body only after selection. Initial listings have a context budget, so descriptions can be shortened or omitted when too many skills are installed.

Skills can be explicit or implicit. Descriptions should lead with the main use case and boundaries. agents/openai.yaml can set presentation, disable implicit invocation, and declare MCP dependencies. Repository discovery walks .agents/skills directories from the current working directory to the repo root. OpenAI recommends focused skills, instructions before scripts unless determinism requires code, and explicit inputs and outputs.

Plugins

OpenAI’s current product model also allows plugins to bundle apps/connectors, browser capabilities, hooks, and scheduled-task templates. Installation may require connector authentication, and CLI or IDE users must start a new task or chat before newly bundled skills and tools are available. Install, authenticate, new-session, upgrade, and uninstall are therefore separate test cases.

OpenAI recommends starting with a local skill while iterating, then building a plugin for team distribution, bundled connectors or MCP configuration, lifecycle hooks, or a stable published package.

The required entry is .codex-plugin/plugin.json. Components stay at plugin root: skills/, hooks/hooks.json, .mcp.json, .app.json, and assets/. The manifest owns identity, version, discovery/publisher metadata, and relative component paths. Repository marketplaces live at .agents/plugins/marketplace.json.

Hooks

Codex discovers hooks.json next to active config layers or inline [hooks] tables in config.toml; plugin hooks join rather than replace them. If both representations exist in one layer they are merged with a warning, so one representation per layer is clearer.

Codex hooks can live in user or repo hooks.json, inline config, managed requirements, or an enabled plugin. Matching hooks accumulate and command handlers start concurrently. Project layers require project trust; individual non-managed definitions require hash-based review and re-review after changes.

Current events cover session/subagent start, prompt submission, tool use, permission requests, compaction, and stop. Only command handlers currently run; prompt, agent, and asynchronous handlers are parsed but skipped. PreToolUse coverage includes supported Bash, apply_patch, and MCP paths but is incomplete, so it is a guardrail rather than a full enforcement boundary. PostToolUse cannot undo completed work.

Turn-scoped events include PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, UserPromptSubmit, SubagentStop, and Stop; SessionStart and SubagentStart run at thread or subagent start.

Rules and managed policy

Experimental .rules files apply allow, prompt, or forbidden decisions to command argument prefixes outside the sandbox. The most restrictive match wins. Inline match and non-match examples are validated at load time, and codex execpolicy check tests rule behavior. Managed requirements.toml can provide restrictive rules and managed hooks, including a managed-only mode.

MCP and subagents

agents/openai.yaml is the OpenAI-specific extension point around a portable skill. It can supply display metadata, set implicit invocation policy, and declare MCP dependencies without coupling the core SKILL.md procedure to one host.

MCP configuration belongs in user or trusted project config.toml, and is shared by the desktop app, CLI, and IDE extension. ChatGPT web instead uses installed plugins/connectors. Server instructions should put the most important cross-tool constraints in their first 512 characters.

Subagents are appropriate for complex independent work and consume additional tokens and tools. Local Codex delegates on direct request or applicable repository/skill instruction. Custom profiles can vary instructions, model, reasoning effort, and tools; default nesting permits direct child agents.

The recommended adoption order is: establish AGENTS.md plus mechanical linters; install an existing plugin or build a local skill; add MCP when the workflow needs external systems; then add subagents when specialised or noisy work warrants another context. Distribution and orchestration should follow a proven workflow.

Standards implications

• Treat OpenAI skills, plugins, hooks, rules, MCP, and subagents as separate surfaces with explicit composition.
• Standardize repo file placement and verify discovery from root and subtree launch locations.
• Use rules/permissions and per-tool controls for authority; use hooks as auditable defense in depth.
• Package only stabilized local workflows and test install, trust, update, and uninstall behavior in a clean environment.
• Keep OpenAI-specific metadata and trust semantics out of the portable skill core.