RU
Get in touch
Chapter 20

Codex: Configure AGENTS.md, Skills, config, Hooks, and MCP

Codex separates persistent instructions, repeatable workflows, runtime configuration, lifecycle automation, and external capabilities. Mixing these layers makes behavior hard to explain.

Each mechanism, its purpose, and its project surface are worth seeing together.

Mechanism · Purpose · Project surface

  • AGENTS.md - Persistent commands and repository rules; Root and nested files; more specific guidance wins
  • Skill - A focused workflow with SKILL.md, scripts, and references; .agents/skills/ for the team
  • config.toml - Model, reasoning, sandbox, approvals, MCP, and profiles; .codex/config.toml; project config is honored for a trusted repo
  • Hooks - Commands on lifecycle events; Project or user configuration per the current hook reference
  • MCP - Live external tools and context; Configured stdio or Streamable HTTP servers

It all starts with AGENTS.md. The /init command creates a starter file that must be edited for the real build, tests, and review. Codex gathers instructions from the global level down to project and the current directory; the closer rule wins, and for a temporary exception there's AGENTS.override.md. Credentials and fast-aging data don't go there. A skill describes one repeatable capability with explicit inputs, outputs, and stop criteria; in the companion project verified-change doesn't know the model and doesn't call an API - it standardizes the sequence scope, plan, patch, test, evidence.

Config sets the model, sandbox, approvals, and MCP - and its meaning shows on a safe profile.

# ~/.codex/config.toml
sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
network_access = false

The example shows the meaning of the current documented keys, not a ready corporate policy: managed configuration, the OS, and the Codex version can add restrictions, and project config isn't to be trusted before a repository review.

MCP extends authority. A tool from MCP can have a side effect outside the filesystem sandbox. Check the server origin, tool annotations, authentication, approvals, and downstream authorization. An instruction in AGENTS.md doesn't limit the rights of the MCP server itself.

The persistent mechanisms are configured. What remains is run control: sandbox, exec, review, and worktrees.

Links