AGENTS.md is a simple Markdown file that tells coding agents how to work in a
project.
Think of it as a README for agents: a predictable place for setup commands, test commands, code style notes, security warnings, and other project-specific instructions that would be awkward to repeat in every chat.
After working through this page, students should be better able to:
AGENTS.md and skills appropriately as reusable instruction layers in a
project workflowCommon things to include are:
README.md?README.md is mainly for humans.
AGENTS.md is mainly for coding agents.
That separation keeps the human README shorter while still giving agents the practical instructions they need.
AGENTS.md has no required schema. It is just Markdown.
# AGENTS.md
## Setup commands
- Install dependencies: `uv sync`
- Run tests: `pytest`
## Code style
- Use small functions.
- Prefer explicit names over clever abbreviations.
## Before finishing
- Run the relevant tests.
- Summarize any limitations or follow-up risks.
For AGENTS.md itself, two rules are especially useful:
AGENTS.md in the directory tree winsThat means a monorepo can have one top-level AGENTS.md plus smaller nested
files for subprojects.
AGENTS.md and Claude CodeAGENTS.md is cross-agent. CLAUDE.md is Claude Code’s own always-loaded
instructions file.
Claude Code reads CLAUDE.md, not AGENTS.md, directly. That means the
nearest-wins rule above is the AGENTS.md convention, not a general rule for
every Claude-specific file.
If a repository already uses AGENTS.md, the usual Claude Code pattern is to
create a CLAUDE.md that imports it:
@AGENTS.md
## Claude Code
- Use plan mode for larger changes.
That way you keep one shared set of project instructions for many tools, while still allowing Claude-specific additions.
Keep one repository and one task fixed:
Explain code in a beginner-friendly way, and run
pytest -qbefore finishing if code changed.
If that guidance should apply across the whole repository and across tools, it
belongs in AGENTS.md.
If the guidance is instead Use plan mode for non-trivial changes, that is not
cross-agent. It belongs in a tool-specific file such as CLAUDE.md.
If the guidance is a reusable explanation procedure such as start with an
analogy, then show the control flow, then mention one misconception, that is a
skill.
If the guidance is temporary, such as Sofia only needs a rough answer before
today's meeting, that is session context, not an AGENTS.md rule.
Some teams go one step further and keep AGENTS.md and CLAUDE.md literally
the same by making one a symlink to the other. That can work well when your
operating system, editor, and Git setup all handle symlinks cleanly, but the
import pattern above is the more portable default.
Create AGENTS.md when: