Skip to content

Write AGENTS.md

Codex reads AGENTS.md before it starts work. For an EAP project, the repository-root AGENTS.md is the durable instruction contract reviewed by project owners and the EAP platform team.

AGENTS.md contains Markdown instructions. Runtime model, MCP, and approval settings are managed by the EAP platform and Registry.

File Location And Discovery

Start with one root file:

<your-project-repo>/
└── AGENTS.md

Codex builds an instruction chain from the repository root down to the current working directory. A nested directory may add AGENTS.md or AGENTS.override.md when it needs more specific rules:

<your-project-repo>/
├── AGENTS.md
└── services/
    └── payments/
        └── AGENTS.override.md

Closer instructions take precedence over broader instructions. Keep the root file focused enough that it applies to every EAP conversation workspace.

A useful project AGENTS.md answers four questions:

  1. What outcomes does this project produce?
  2. Which skills and tools should Codex use for each request type?
  3. What evidence and output shape are required?
  4. What must Codex refuse, pause, or escalate?
# Project Agent Instructions

## Role

Investigate operational alerts and return an evidence-backed recommendation.

## Routing

- For EMS alert triage, use the `ems-alert-triage` skill.
- For database capacity alerts, use the `db-capacity` skill.
- For documentation-only questions, answer from project references without calling production MCP tools.

## Output

- State the observed facts and their sources.
- Separate verified evidence from inference.
- End with the recommended next action and its risk.

## Boundaries

- Never expose credentials, access tokens, or raw customer data.
- Do not perform a state-changing action without the required approval.
- Stop and identify the missing dependency when an approved MCP is unavailable.

Reference skills by their declared name or directory name so Codex can match the request to the intended workflow.

Runtime Configuration Ownership

Keep runtime configuration separate from project instructions:

  • the production model and provider come from EAP's generated Codex config
  • production MCP exposure comes from Registry YAML
  • approvals are enforced by Codex plus the EAP protocol adapter
  • the public Codex runtime agent is selected by the route segment codex

Optional Custom Subagents

Codex can load project-scoped custom agents from .codex/agents/*.toml. Use them only for a distinct internal role that benefits from separate instructions or model settings.

name = "docwriter"
description = "Documentation specialist for API and runbook updates."
developer_instructions = """
Write concise operational documentation.
Preserve verified commands and identify assumptions explicitly.
"""

Custom agents are internal Codex collaborators. They do not create separate EAP API endpoints, and Codex only spawns them when the prompt or project instructions explicitly request delegation.

Do not add a custom subagent when a skill is sufficient. Use a skill for a reusable workflow; use a custom agent when the role needs its own persistent instructions or model configuration.

Review Checklist

  • the root AGENTS.md is non-empty and applies to the whole project
  • routing names correspond to real skills under .agents/skills
  • output requirements identify the evidence callers need
  • state-changing and sensitive-data boundaries are explicit
  • no secrets, personal credentials, or environment-specific values are present
  • the file contains project instructions rather than runtime configuration
  • optional custom agents have name, description, and developer_instructions

Common Mistakes

  • treating custom subagents as separate EAP route-level agents; Codex projects expose the runtime agent codex
  • putting model/provider selection in AGENTS.md
  • assuming instructions can grant production MCP access
  • adding custom subagents when a focused skill would be simpler
  • writing vague routing text that does not name the intended skill
  • omitting stop conditions for risky or state-changing work

Next