Writing AGENTS.md for Codex

What AGENTS.md is

AGENTS.md is the primary configuration file for OpenAI Codex CLI. It contains project-specific instructions that shape how the Codex agent behaves—coding conventions, test commands, workflow rules, and project context. Codex reads these files automatically before starting any task.

The same AGENTS.md format is also recognized by Cursor and other AI coding tools, making it the most portable instruction file across the ecosystem.

Discovery hierarchy

Codex discovers instruction files in a specific order, with files closer to the working directory taking precedence:

Global scope

~/.codex/AGENTS.md              # Default global instructions
~/.codex/AGENTS.override.md     # Override that replaces global AGENTS.md

Project scope

Starting from the git root to the current working directory, Codex checks each directory for:

AGENTS.override.md    # Checked first—replaces AGENTS.md if present
AGENTS.md             # Standard project instructions

Example directory walk:

/repo/AGENTS.md                   # Loaded first (project root)
/repo/packages/AGENTS.md          # Loaded second (more specific)
/repo/packages/api/AGENTS.md      # Loaded third (most specific, highest priority)

Files are merged, with later files overriding earlier ones on conflicting instructions. Maximum file size is 32 KiB by default (configurable via project_doc_max_bytes).

What to include

Build and test commands

## Commands

- Install: `npm install`
- Dev server: `npm run dev`
- Build: `npm run build`
- Lint: `npm run lint`
- Test: `npm test`
- Test single: `npm test -- --grep "pattern"`

Coding conventions

## Code style

- TypeScript with strict mode enabled
- Use functional components, never class components
- Named exports only (no default exports)
- Import with `@/` alias for project-internal imports
- All public functions must have JSDoc comments

Workflow rules

## Workflow

- Follow the plan-implement-verify loop for all changes
- Run lint and tests before marking any task complete
- One logical change per commit with descriptive message
- Never modify auto-generated files in `src/generated/`

Sandbox and safety notes

## Safety

- Never run destructive commands (rm -rf, DROP DATABASE) without explicit approval
- Never expose secrets or tokens in generated code
- Always use parameterized queries, never string interpolation for SQL

Config.toml settings

Beyond AGENTS.md, Codex has a TOML configuration file for runtime behavior:

Global config: ~/.codex/config.toml

model = "o4-mini"
approval_policy = "on-request"

[sandbox]
sandbox_mode = "workspace-write"

[sandbox.workspace-write]
network_access = false

Project config: .codex/config.toml

[sandbox]
sandbox_mode = "workspace-write"

[sandbox.workspace-write]
network_access = true

Key settings

Setting	Options	Default
model	o4-mini, o3, codex-mini	o4-mini
approval_policy	untrusted, on-request, never	on-request
sandbox_mode	read-only, workspace-write, danger-full-access	workspace-write
network_access	true, false	false

The SKILL.md format

Codex supports portable skills through the SKILL.md format—reusable instruction packages that can be shared across projects and tools.

Skill directory structure

.agents/
└── skills/
    └── my-skill/
        ├── SKILL.md           # Required: skill definition
        └── scripts/           # Optional: automation scripts
            └── validate.sh

Skills can also be installed globally at ~/.agents/skills/.

SKILL.md format

---
name: react-component-scaffold
description: Generate React components with TypeScript, tests, and colocated styles
version: 1.0.0
compatibility:
  - codex
  - cursor
  - claude-code
---

## Instructions

When creating a new React component:

1. Create the component file at `src/components/{Name}/{Name}.tsx`
2. Create the test file at `src/components/{Name}/{Name}.test.tsx`
3. Create the styles file at `src/components/{Name}/{Name}.module.css`
4. Export the component from `src/components/index.ts`

## Template

Component structure:

interface {Name}Props {
  // props here
}

export function {Name}({ ...props }: {Name}Props) {
  return <div className={styles.root}>...</div>;
}

Required frontmatter fields

Field	Type	Description
name	string	Unique identifier (lowercase, hyphens, max 64 chars)
description	string	What the skill does (max 1024 chars)

Optional frontmatter fields

Field	Type	Description
version	string	Semantic version
compatibility	string[]	Which tools support this skill
license	string	License identifier
allowed-tools	string[]	MCP tools the skill can use

Using skills

• Explicit invocation: Type $skill-name in your prompt
• Auto-detection: Codex reads skill descriptions and applies relevant ones automatically
• Listing: Run codex features list to see available skills

Cross-tool compatibility

AGENTS.md is the most portable instruction format:

Tool	Reads AGENTS.md?	Native alternative
Codex CLI	Yes (primary)	config.toml for runtime settings
Cursor	Yes (lowest priority)	.cursor/rules/*.mdc for activation control
Claude Code	No	CLAUDE.md (similar format, different name)
Continue	Partial	.continue/config.yaml for model settings

If your project uses multiple AI tools, consider maintaining both AGENTS.md (for Codex/Cursor) and CLAUDE.md (for Claude Code) with shared content.