Guides · TypeScript
How to write an AGENTS.md for a TypeScript project
Measured across 173 of the most-starred TypeScript repositories on GitHub. The median scores 71 out of 100.
What TypeScript repos get wrong
TypeScript scores best of any language, and it is mostly the ecosystem doing the work: a lockfile comes free, tests have a conventional home, and the scripts block already names commands. What TypeScript repos actually miss is instructions. 43% ship no agent instruction file at all, and among those that do, nearly half never name a command, which is the only part an agent can act on. The other frequent gap is environment config: 45% document no environment, so an agent installs cleanly and then fails at runtime with an error it cannot diagnose.
Most common failures
share of 173 TypeScript 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 pnpm install ## Commands pnpm dev # local server on :3000 pnpm test # full suite, must pass before any commit pnpm typecheck # tsc --noEmit pnpm lint ## Conventions - Tests sit beside the file they cover, as *.test.ts. - Strict mode is on. Do not widen types to make an error go away. ## Gotchas - Copy .env.example before running anything that touches the database.
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.
# installpnpm install# verifypnpm 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