Black Friday sale: 30% off Flywrite

AGENTS.md is a Markdown file of instructions for AI agents, kept in a project folder, that Codex and many other agents read before they start work; it is an open format rather than one company's file.

Who reads it

AGENTS.md calls itself a README for agents: one predictable place for the instructions an agent needs. Codex reads it, and so do Cursor, Gemini CLI, OpenCode and other agents listed on agents.md. The format is now stewarded by the Agentic AI Foundation, part of the Linux Foundation. Claude Code reads a project's AGENTS.md when there's no CLAUDE.md.

How Codex finds it

Codex builds its instructions when it starts:

  1. Your global file, ~/.codex/AGENTS.md.
  2. Then one file per folder, from the project root down to the folder you started in. An AGENTS.override.md in a folder takes the place of that folder's AGENTS.md.

Files closer to where you started come later, so they win where instructions disagree. Empty files are skipped, and Codex stops adding files at 32 KiB in total by default.

What to put in it

For a course written as Markdown lessons:

# Course: Writing with agents

- One file per lesson in lessons/, named 01-intro.md and so on.
- Each lesson: a two-sentence intro, numbered steps, a short recap.
- Second person, plain words, no jargon.
- Don't edit files in archive/.

Keep a procedure you only run now and then, such as a lesson review checklist, in a skill instead: the agent loads it only when the task calls for it.

In Flywrite

AGENTS.md is a Markdown file, so it opens in Flywrite like any draft. A Flywrite project with checkpoints on is a Git repository, so Codex started in Flywrite's terminal treats the project folder as its root and reads the AGENTS.md there. The guide to course lessons with the Codex CLI sets one up step by step.

Questions

Should I use AGENTS.md or CLAUDE.md?

If you only use Claude Code, CLAUDE.md. If you use Codex or more than one agent, AGENTS.md. Claude Code reads it when the project has no CLAUDE.md, or you can include it from a CLAUDE.md with an @AGENTS.md line.

Does AGENTS.md need special fields?

No. It's ordinary Markdown with any headings you like; the agent reads the text.

Sources
  1. AGENTS.md. Checked .
  2. OpenAI Codex docs: Custom instructions with AGENTS.md. Checked .
  3. Claude Code: How Claude remembers your project. Checked .
  4. Flywrite docs: Writing with Codex. Checked .

Write with your agent in a writing app.

Buy now