You open an AI coding tool, point it at your project, and ask for a change. It does something close to what you wanted, but it ran the wrong test command, used a style you abandoned months ago, and touched a folder you keep off-limits. So you explain. The next day, with a fresh chat, you explain all of it again. There is a faster way, and it takes about fifteen minutes. You write the explanation down once, in a file the tool reads on its own. That small act is the start of context engineering, one of the skills inside The 7 Levels of AI Proficiency: instead of re-typing the same background, you design the standing context a tool inherits before it does any work.
What AGENTS.md actually is
AGENTS.md is a simple, open format for guiding coding agents. The standard describes it as a dedicated, predictable place to give the context and instructions that help AI coding agents work on your project.
It is just standard Markdown. There are no required fields and no required sections. As the standard puts it, you can use any headings you like, and the agent simply parses the text you provide. That is the whole format. If you can write a README, you can write this.
It also pairs with your README rather than replacing it. README files are for humans: quick starts, descriptions, contribution guidelines. AGENTS.md complements that by holding the extra, sometimes detailed context a coding agent needs to do the job well.
One more thing worth setting straight up front. Think of this file as standing project guidance, the context many coding tools read before they start work in the repo. It is a different layer from a skill. In tools that support skills, a skill loads on demand for a specific task, while AGENTS.md is the background a tool carries the whole time it works in your project.
When it is worth doing
Here is a quick test. If you catch yourself re-explaining the same project context to an AI tool more than once, that context belongs in the file. Anything you would tell a new teammate on their first day is a good candidate.
Some easy first entries:
- The build and test commands you run most
- The code style and naming conventions you want followed
- The folders or files an agent should leave alone
- The one or two gotchas that trip up everyone new
You do not need to fill in everything at once. Start with the parts you already re-type, and add more as you notice the next repeated explanation.
A short, honest file beats a long, aspirational one.
The four parts that carry most of the value
The AGENTS.md site lists a handful of popular sections. You can name them however you like, but these four cover most projects.
Project overview.
Two or three sentences on what the project is and what it does. Give the tool the same orientation you would give a new teammate before handing them a task.
Build and test commands.
The exact commands, written out. This is the section that pays off fastest, because a tool guessing at your test runner is the most common way a good change goes sideways.
Code style and conventions.
Naming, formatting, the patterns you want matched, and the ones you have moved away from. Be specific. A note telling the tool to match the style of the surrounding file fits here too.
Security and testing notes.
Anything sensitive an agent should avoid, plus how you expect changes to be verified. The standard lists testing instructions and security considerations as suggested sections for exactly this reason.
Put the file at the root of your repository so tools can find it. If you run a monorepo, you can place another AGENTS.md inside each package. Agents read the nearest file in the directory tree, so the closest one takes precedence.
Do it now
You do not have to write this from a blank page. Paste the prompt below into a tool like Claude or ChatGPT. It interviews you about your project, then drafts a first AGENTS.md from your answers.
You are helping me write my first AGENTS.md, a plain-markdown file that gives AI coding tools the standing context they need to work on my project. Interview me first. Ask me one short batch of questions covering: - What this project is and what it does - How to build it and run its tests (the exact commands) - The code style and conventions I want followed - Any gotchas or rules a new teammate would need to know - Anything sensitive an agent should avoid touching Wait for my answers. Then draft a complete AGENTS.md in standard markdown using clear headings (Project overview, Build and test commands, Code style, Testing instructions, Security considerations). Keep it to a tight length, roughly under 200 lines. Use only what I told you. Where I left something blank, leave a short placeholder note instead of guessing. Write it as guidance for the tool to follow as closely as it can, not as a promise it will follow it every time.
When the draft comes back, read it like an editor. Fix any command it got wrong, cut anything you would not actually tell a teammate, and save it as AGENTS.md at the root of your repo. Fifteen minutes, and the next session starts with the context already in place.
A starter file to download
If you would rather fill in a skeleton, grab the companion file below. It is a commented AGENTS.md template with the suggested sections as headers, a one-line note under each telling you what to put there, and one short worked example. Rename it to AGENTS.md, drop it at the root of your repo, and fill in the blanks.
First AGENTS.md Starter Template
A commented AGENTS.md skeleton with section headers and a worked example. Plain markdown, no signup.
Common mistakes you can step around
A few snags come up often, and each one is easy to avoid.
Treating it as a contract. The file guides the tool. It does not force it. The Claude Code docs are clear that these instructions are context, not enforced configuration, and that they shape behavior without being a hard enforcement layer. Write it as guidance, and check the tool's work as you would a teammate's. For hard enforcement, tools point to features like hooks, which is a step beyond a first file.
Making it too long. A bloated file works against you. Claude Code's guidance is to target under 200 lines, because longer files consume more context and reduce how well the instructions are followed. That is a useful rule of thumb for any instructions file. Keep it lean.
Writing wishes instead of facts. A line praising the test coverage you wish you had helps no one. Naming the exact command you run before a commit does. Put down the commands and conventions you actually use, not the ones you hope to.
The Claude Code bridge, so you do not duplicate the file
Worth knowing if you use Claude Code: it reads CLAUDE.md, not AGENTS.md. The good news is you do not have to keep two copies in sync.
The cleanest path is an import. Create a CLAUDE.md that pulls in your AGENTS.md, then add any Claude-specific notes below it. Straight from the docs:
@AGENTS.md ## Claude Code Use plan mode for changes under src/billing/.
If you do not need any Claude-specific content, a symlink works too: ln -s AGENTS.md CLAUDE.md. On Windows a symlink needs Administrator privileges or Developer Mode, so the @AGENTS.md import is the safer default there. Imported files can recursively import others, up to a maximum depth of four hops, so you have room to organize. And if you run /init in a repo that already has an AGENTS.md, Claude Code reads it and folds the relevant parts into the CLAUDE.md it generates. It reads other tool configs the same way, including .cursorrules and .windsurfrules.
Where it fits in the bigger picture
AGENTS.md is an open, shared format supported by many coding tools, including OpenAI Codex, Google Jules, Aider, Zed, VS Code, Cursor, Gemini CLI, and GitHub Copilot's coding agent, among a growing list. The honest read: it is one file that travels across tools, but each tool has its own setup, and Claude Code in particular reads CLAUDE.md, which is why you bridge to it with an import or a symlink.
Step back and look at what you just did. You stopped re-explaining your project to a tool and started designing the context it works inside. That is the move from using a tool to building a system the tool runs within, and it is the through-line of The 7 Levels of AI Proficiency. The first file is small. The skill it builds, deciding what standing context an AI needs before it acts, is the durable one, and it compounds across every project you touch next.
Curious where your own skills sit right now? The free 7 Levels of AI Proficiency assessment gives you a read in about ten minutes.
Related reading: Level 4: The Commander, the context-engineering rung this first file starts you toward.
Sources
- AGENTS.md open standard, agents.md. Accessed June 3, 2026.
- Claude Code documentation, "How Claude remembers your project," code.claude.com/docs/en/memory. Accessed June 3, 2026.
- The 7 Levels of AI Proficiency assessment, assess.launchready.ai. Accessed June 3, 2026.
Frequently Asked Questions
What is AGENTS.md?
It is a simple, open format for guiding coding agents: a predictable place to put the context and instructions an AI coding tool needs to work on your project. It is just standard Markdown, with no required fields or sections.
Do I need to know how to code to write one?
No. If you can write a README, you can write this. You are describing your project in plain language: what it is, how to build and test it, the conventions you follow, and anything to avoid.
What is the difference between AGENTS.md and a skill or SKILL.md?
They are different layers. AGENTS.md is standing project guidance, the background a tool carries while it works. In tools that support skills, a skill loads on demand for a specific task. This guide covers the standing instructions file.
Does AGENTS.md only work with one tool?
No. It is a shared, open format supported by many tools, including Codex, Cursor, Gemini CLI, and Copilot's coding agent. Each tool has its own setup, though. Claude Code reads CLAUDE.md rather than AGENTS.md, so you bridge to it with an @AGENTS.md import or a symlink.
Will the AI follow everything in the file exactly?
Treat it as guidance, not a guarantee. The instructions shape how a tool behaves, but they are context, not an enforcement layer, so review the work as you would a teammate's. Tools point to features like hooks when you need hard enforcement.
How long should AGENTS.md be?
Keep it lean. Claude Code's guidance is to target under 200 lines, because longer files use more context and the instructions get followed less reliably. Start with what you re-explain most, and grow it as you go.
Find your AI Proficiency level
The free 7 Levels assessment places you across seven stages of AI capability. Under ten minutes. Research-backed scoring.