Guides · JavaScript
How to write an AGENTS.md for a JavaScript project
Measured across 104 of the most-starred JavaScript repositories on GitHub. The median scores 60 out of 100.
What JavaScript repos get wrong
JavaScript scores eleven points below TypeScript, and most of the gap is the absence of a type checker: 76% have none, so an agent gets a runtime surprise where TypeScript would have handed it a compile error. Adding checkJs with JSDoc types recovers much of that without rewriting anything. Otherwise the pattern is familiar: seven in ten ship no agent instructions.
Most common failures
share of 104 JavaScript repositories scoring zero on each
Lower is better here. These are failures, not scores.
A working example
Commands first, conventions second, none of the persuasion a README carries. The test is whether a capable stranger could make a small change and verify it using only this file.
Save it at the root of the repository
as AGENTS.md. Tool-specific files like CLAUDE.md or .cursorrules still work, but
AGENTS.md is the one every tool reads.
# AGENTS.md ## Setup npm ci ## Commands npm test # full suite, must pass before any commit npm run lint npm start ## Conventions - Tests sit beside the file they cover, as *.test.js. - CommonJS in src/, ES modules in scripts/. Do not mix within a directory. ## Gotchas - Copy .env.example before running anything that needs configuration.
The two lines that matter most
If you write nothing else, write these. An agent that cannot install the project cannot start, and one that cannot run the tests cannot tell whether it broke something.
# installnpm ci# verifynpm test
Have it drafted instead
Point the tool at a repository and it writes the file from what is already there, rather than from a template.
For private code, the same rubric runs on your machine and sends nothing anywhere:
$ npx agentreadme --write-agents
Other ecosystems