One AGENTS.md for Claude Code, Codex and Cursor

Why bother

Most people don't stick to one agent anymore. Theo shared that over 60% of T3 Code users who used Codex in the last 2 weeks also used Claude Code (source). If your rules live in three different files, they drift apart, and one agent ends up following last month's rules.

Who reads AGENTS.md

• Codex (OpenAI): listed as a supported agent on agents.md, the format's home page, along with Jules, Gemini CLI, GitHub Copilot's coding agent, Windsurf, Zed, Aider and others.
• Cursor: reads AGENTS.md in the project root and in subdirectories. A nested file applies when the agent works on files in that folder (Cursor docs).
• Claude Code: from v2.1.277 it reads AGENTS.md on its own, but by default only when there's no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or above it (Claude Code docs).

Setup in 3 steps

1. Put your rules in AGENTS.md at the repo root: setup commands, the one command that checks your work, code style, and what the agent must never do.
2. Delete or merge any old project CLAUDE.md into it, so Claude Code doesn't skip AGENTS.md.
3. If you need a CLAUDE.md too, open /config in Claude Code and set Project instructions to claude-md-and-agents-md so it reads both.

# check what Claude Code loaded: start a session and look for
# "no CLAUDE.md found; AGENTS.md loaded: /path/to/repo/AGENTS.md"
claude

Gotchas

• Adding a personal CLAUDE.local.md makes Claude Code stop reading AGENTS.md by default. Use the claude-md-and-agents-md setting if you want both.
• Claude Code doesn't read AGENTS.local.md, AGENTS.override.md or anything in a .agents/ folder.
• On Claude Code versions before v2.1.277, it reads CLAUDE.md only. Update, or import AGENTS.md from a CLAUDE.md. The old ln -s AGENTS.md CLAUDE.md trick also still works.

AGENTS.md or Agent Skills?

Use both. They do different jobs, and since Oct 22, 2026 both live at the Linux Foundation's Agentic AI Foundation, next to MCP (AAIF announcement).

• AGENTS.md holds the rules for one repo that every session should follow: setup, the check command, style, and what never to touch.
• Agent Skills are folders with a SKILL.md plus any scripts or reference files, for a task the agent only needs sometimes, like a release checklist or a PDF workflow. Anthropic says 70+ agent platforms, including ChatGPT, Cursor, GitHub Copilot and VS Code, support the format, with 1 million skills published and nearly 280 million installs (Anthropic, Oct 22).

Rule of thumb: if it applies to every task in the repo, put it in AGENTS.md. If it's a repeatable procedure you'd hand to a specialist, make it a skill. Skills can ship scripts, so read any skill you didn't write before you install it.

A starter AGENTS.md that keeps builds green

Our free Checkpoint Loop is an AGENTS.md plus a one-command check script. The agent works on a branch in small steps and only commits when the check passes. Making a game? Pack #001 ($19) adds an AGENTS.md for game projects, a playtest agent and a fun review.

Next: make your coding agent prove it's done, a verification checklist based on how the Claude Code team reviews code.

Get the free Checkpoint Loop