AGENTS.md & CLAUDE.md stable

What it is

Both are plain Markdown files at the root of a repository that tell a coding agent how the project works: build commands, conventions, what not to touch. They differ in who reads them and what extra syntax they support.

AGENTS.md started with OpenAI’s Codex CLI and is now an open format stewarded under the Linux Foundation. Codex, Cursor, Gemini CLI, GitHub Copilot, Jules and many others read it. There is no required schema. Nested files apply to their subtree, and the closest one wins.

CLAUDE.md is specific to Claude Code. It is loaded in a hierarchy: a user-level file, the project root, subdirectories, and an untracked CLAUDE.local.md. It supports @path imports to pull in other files, and /init generates a starting point.

How to use both

Claude Code does not read AGENTS.md on its own. The fix is a one-line CLAUDE.md containing @AGENTS.md. Claude Code’s @ import pulls the file in, so there is one real instruction file and every tool reads it.

Other tools have their own: .cursor/rules, copilot-instructions.md, GEMINI.md. Most of them also honor AGENTS.md now, so start there.

When to use it

Always, for any repo an agent will touch. Keep it short and factual: commands, layout, conventions, gotchas. Anything task-specific belongs in a skill.

Watch out for

• Long instruction files get ignored in practice. Under a page is the goal.
• Static context beats dynamic retrieval for things the agent must always know. Put invariants here, not in a skill.