Glossary
agents.md: What It Is and How to Use It
Definition
agents.md is a Markdown file in a code repository that tells AI coding agents how to build, test and work with that project. Unlike llms.txt, which points web crawlers at a site’s important pages, agents.md targets tools working inside your codebase. It has no effect on how your brand appears in AI search.
At a glance
- CategoriesTechnical
- Related fieldsTechnical
- DifficultyIntermediate
At a glance
- AGENTS.md lives at the root of a code repository, not at the root of your website.
- The file carries build commands, test commands and project conventions in plain Markdown.
- Coding agents read it. The crawlers that gather pages for AI answers do not.
- There is no schema, no validator and no submission step.
What a coding agent reads out of the file
An agent opens the repository and looks for AGENTS.md before it starts work. The format is plain Markdown with no required structure, so the headings are whatever your team finds useful: how to install dependencies, how to run the test suite, which directories are generated.
The point is to stop the agent guessing. A human contributor reads the README and picks up the rest by asking. An agent has nobody to ask, so anything left unwritten gets invented.
Large repositories can carry more than one file. AGENTS.md describes placing a file inside each subproject, with the file closest to the code being edited taking precedence over the one at the root.
Nothing is submitted anywhere. You commit the file, and the agents that support the convention pick it up.
Why this file keeps getting sold as an AI search play
agents.md turns up in AI visibility checklists next to sitemaps and schema markup. It does not belong there.
The file sits in a source repository. The bots that decide whether ChatGPT names your brand fetch your public website, and an AI crawler working through your marketing pages never opens your GitHub repository.
The confusion is fair enough. Both conventions are Markdown, both sit at a root, both were written for machines rather than people. What differs is the audience, and the audience is the whole point.
If your engineering team runs Claude Code, Cursor or Codex, the file earns its place in the repo on day one. It buys nothing for the marketing site, and anyone pricing it as an AI search deliverable is billing you for someone else’s job.
Write one if you ship software
This belongs to whoever owns the repository, and it takes an afternoon.
- Put AGENTS.md at the repository root. Plain Markdown, committed like any other file.
- Start with the commands. Install, build, test, lint. Exact strings an agent can run without editing them.
- Write down what a new hire would have to ask about. Generated directories to leave alone, branch naming, how database migrations run.
- Update it when the commands change. A stale build command does more damage than no file at all, because the agent trusts it.
Keep this separate from the website work. Crawlability fixes, server-rendered HTML and clean page structure are what move your AI search results, and none of that lives in the repo.
agents.md vs llms.txt
| agents.md | llms.txt | |
|---|---|---|
| Where it lives | Root of a code repository | Root of a website |
| Who reads it | AI coding agents | Web crawlers, adoption unconfirmed |
| What it carries | Build and test commands, conventions | Curated links to key pages |
| What it changes | How an agent edits your code | What a crawler reads first, in theory |
| Who owns it | Engineering | Marketing or content |
Frequently asked questions
-
Is agents.md the same as llms.txt?
No. agents.md instructs AI coding agents working inside a source repository, covering build commands and project conventions. llms.txt is a proposed website file pointing crawlers at the pages a site considers important. Same file format, different root directory, completely different audience. Most teams that want one do not need the other.
-
Will agents.md help my brand show up in ChatGPT?
No, and nobody should tell you otherwise. The file is read by coding agents operating on a repository, not by the crawlers that gather pages for AI answers. If the goal is being named in an assistant’s answer, the work is server-rendered HTML, clear page structure and content worth quoting.
-
What actually goes in AGENTS.md?
Build and test commands first, then the conventions a new contributor would otherwise have to ask about: which directories are generated, how migrations run, what the linter expects. There is no schema and no validator, so the structure is yours. Write it the way you would brief a contractor on their first morning.
-
Is agents.md a standard?
Not a formal one. It is a convention several agent tools have agreed to follow, published openly rather than ratified by a standards body. That is enough to make it useful, and it also means support varies by tool. Check what your team’s agent actually reads before assuming the file is doing anything.