What are you putting in the file? When I’ve looked at them they just looked like a second readme file without the promotional material in a typical GitHub readme.

The useful stuff is different from a README. A README tells humans how to use the project. An AGENTS.md tells the AI how to work on it.

Mine typically includes:

- Build/test commands that aren't obvious from package.json (e.g. "run migrations before tests") - Architecture decisions that would take the agent 10 minutes to reverse-engineer ("auth goes through middleware X, not controller Y") - Known gotchas ("don't touch the legacy billing module, it's being replaced next sprint") - Deploy process specifics ("push to main auto-deploys staging, prod needs a manual tag") - Coding conventions that aren't in the linter ("we use Result types for errors, never throw")

The ones that look like READMEs are indeed useless. The good ones read more like the notes you'd give a new senior engineer on their first day. Stuff that's obvious to the team but invisible to an outsider.

That's basically all it is. It's a readme file that is guaranteed to be read. So the agent doesn't spend 10 minutes trying to re-configure the toolchain because the first command it guessed didn't work.