How to Write an AGENTS.md File With AI (Generate It From Repo Facts)

What an AGENTS.md File Actually Is

An AGENTS.md file is a plain-markdown config at the root of a repository that tells an AI coding agent how to operate in that codebase. It carries the build and test commands, the folders that matter, the code style, and the hard rules about what the agent must never touch. Cursor, Claude Code, and GitHub Copilot all read it as standing context before they touch a single line.

Knowing how to write an AGENTS.md file is the difference between an agent that runs your real test command and one that invents npm test when your project uses pnpm vitest run. The spec at agents.md defines the format. GitHub's own writeup, lessons from over 2,500 repositories, shows what good ones contain. Neither hands you a filled file. You still write it by hand.

That's the gap. The reference material teaches the shape. It doesn't produce the artifact.

Why Most AGENTS.md Files Drift Out of Date

The first version is usually fine. Someone sits down, writes the commands, lists a few boundaries, and commits it. Then the repo changes and the file doesn't. Six weeks later the agent is reading a build command that was renamed in March.

Hand-written AGENTS.md files share three failure modes. They go stale because nobody re-derives them from the repo. They go vague because "follow the conventions" feels easier to type than the actual conventions. And they go bloated, turning into a 400-line essay the agent half-reads instead of a tight set of facts it can act on.

A good file is short and specific. It says pnpm test runs the suite, the API lives in src/api, and the agent never edits files under generated/. Concrete. Checkable. Boring, in the right way.

What You Can Generate Into the File

A generator prompt that reads your repo facts can fill the sections you'd otherwise type by hand:

• Commands block. The exact install, build, test, and lint commands, pulled from package.json scripts or the Makefile, not guessed.
• Project structure. A short map of the folders that carry meaning, with one line each on what lives there.
• Code style rules. The conventions that actually matter here: formatter, import order, naming, the patterns reviewers reject.
• Boundaries. The Always / Ask-first / Never tiers. What the agent can do freely, what needs a human nod, what's off-limits.
• Testing expectations. When tests are required, how to run a single test, what "green" means before a change is considered done.
• Setup gotchas. The env var nobody remembers, the service that has to be running, the one-time step that breaks new clones.

That last one is where hand-written files fail most often. The setup gotcha lives in someone's head, not in the repo.

How to Write an AGENTS.md File, Step by Step

1. Gather the repo facts

Open package.json, the CI config, and the README. Pull the real commands. Note the directories an agent will touch and the ones it shouldn't. Write down the boundaries you'd say out loud to a new contributor on day one.

2. Fill the variables

A generator prompt takes those facts as inputs. The core variable is {{repo_facts}}: the raw dump of commands, folder list, style notes, and boundaries. A second variable, {{stack}}, names the language and framework so the output matches your ecosystem's idioms.

3. Run the prompt against a locked section contract

This is the part the reference docs skip. The output contract fixes the sections in order — Commands, Structure, Style, Boundaries, Testing — so the file is complete every time. No "Style" heading silently dropped because the model got distracted by the command list.

4. Verify against reality

Read each generated command back against the repo. Does pnpm build exist? Is generated/ actually the right path to fence off? The model fills the shape from your facts, but you confirm the facts are current. Models hallucinate a plausible test command when the real one is missing from the input.

5. Commit and re-run on drift

When the build command changes, re-run the prompt with updated {{repo_facts}} instead of patching by hand. The file stays a derived artifact, not a manual one that rots.

A Generator Prompt You Can Copy

Here's the skeleton. Fill the two variables, lock the contract, and the model emits a complete file.

You generate an AGENTS.md file for an AI coding agent.

Repo facts: {{repo_facts}}
Stack: {{stack}}

Output an AGENTS.md with exactly these H2 sections, in this order:
## Commands   — install, build, test, lint, run a single test
## Structure  — the folders that carry meaning, one line each
## Style      — formatter, import order, naming, rejected patterns
## Boundaries — Always / Ask-first / Never, as three sub-lists
## Testing    — when tests are required, what "green" means

Rules: use only facts provided. If a fact is missing, write
"TBD — confirm" rather than inventing a command. No prose preamble.

Note the refusal clause. Telling the model to write TBD — confirm instead of guessing is what stops it from filling a missing test command with a confident fabrication. That single line earns its place.

How Models Handle the Section Contract Differently

The same prompt behaves differently across models, and that matters when you're standardizing a file format across a team.

The pattern that holds across all three: put the output contract close to where the model finishes reading. On a long {{repo_facts}} paste, a contract stated only at the top gets outweighed by recent tokens. Restate it at the end.

Variables You'll Set

Getting Started

1. Collect your real commands from package.json, CI, and the README.
2. List the folders an agent will read and the ones it must avoid.
3. Write your boundaries as three tiers: Always, Ask-first, Never.
4. Drop all of that into {{repo_facts}} and name your {{stack}}.
5. Run the generator against the locked section contract.
6. Read every command back against the repo before committing.
7. Re-run on drift instead of hand-patching, using the AGENTS.md Generator for Polyglot Monorepos.

The companion job is repo onboarding. Before you can write a good AGENTS.md, you need an accurate map of what's in the repo. The Repo Context Map Pack produces that map from a file tree and a few entry points, which then feeds straight into {{repo_facts}}.

A complete AGENTS.md is one of the highest-value files in an agent-driven repo. Get it right and every agent that touches the code starts from the same facts. For the broader question of which packs are worth keeping, the guide on how to choose a reusable AI prompt pack applies the same test used here: does it ship variables and a locked output contract? And once your agents are configured, Claude Code slash commands that stick covers turning these prompts into one-keystroke commands.