mdpantry / AGENTS.md starter
AGENTS.md starter
AGENTS.md is a plain markdown file at the root of a repository that tells coding agents how to set up, build, test and work in the project. This starter carries the sections the format suggests, with every command left for you to fill in.
Published . Updated .
The file
Email it to myself Download AGENTS.md Open the raw file
12 blanks for you to fill
- one sentence: what the project does and who uses it
- for example: TypeScript on Node 22
- for example: src/ for the app, test/ for the tests
- install command
- dev command
- build command
- test command
- single file test command
- lint command
- one rule a reviewer always asks for, for example: no default exports
- where they live, for example: the environment
- anything an agent must never change on its own, for example: migrations are applied by hand
Or save it from a terminal:
curl -fsSL https://mdpantry.com/s/st_zdlp6lbqoiyo3ecb/raw -o AGENTS.md
# AGENTS.md
Instructions for coding agents working in this repository.
## Project overview
- What this is: `<one sentence: what the project does and who uses it>`
- Language and framework: `<for example: TypeScript on Node 22>`
- Where the code lives: `<for example: src/ for the app, test/ for the tests>`
## Setup and build
- Install dependencies: `<install command>`
- Run it locally: `<dev command>`
- Build: `<build command>`
## Tests
- Run every test: `<test command>`
- Run one test file: `<single file test command>`
- Run the tests and fix every failure before you call a change finished.
## Code style
- Lint and format: `<lint command>`
- `<one rule a reviewer always asks for, for example: no default exports>`
## Security
- Never commit a secret. Secrets come from `<where they live, for example: the environment>`.
- `<anything an agent must never change on its own, for example: migrations are applied by hand>`
What goes in it?
The AGENTS.md site names six things to cover. Of 2,808 distinct AGENTS.md files the registry has saved, from 2,937 public repositories, 42% have a build and test commands section and 33% have a code style section. Among the 273 in repositories with 1,000 stars or more, it is 52% and 44%. 51% have a code block, where a command an agent can run usually sits, 2% have no section headings at all, and the middle file is 83 lines.
- Build and test commands1,193 42%
- Code style926 33%
- Commit and pull request guidelines796 28%
- Testing instructions576 21%
- Project overview479 17%
- Security considerations198 7%
The 3 most common, as headings to paste and fill in:
## Build and test commands ## Code style ## Commit and pull request guidelines
The words behind each count
- Build and test commands:
command,build,install,setup,run,running,script,dev,development,getting started,quick start - Code style:
style,convention,guideline,format,formatting,lint,linting,naming,standard - Commit and pull request guidelines:
commit,pull request,pr,git,branch,release - Testing instructions:
test,testing - Project overview:
overview,about,purpose,introduction,what this is,what this repo is,what this repository is,what this project is - Security considerations:
security,secret,credential,permission
Counted by the registry that serves this pantry, with no model in the count, from its saved copies as they stood on : 2,808 distinct files (identical files count once, so a template many repositories copy counts once) at the root of a repository. A section is a heading of one to three # signs outside a code block. A heading is in a group when it has one of that group's words, so one heading can be in two groups, and a file counts once per group. 1,863 of the 2,808 have at least one of the six. The six are the topics the AGENTS.md site lists. Not live GitHub, and not every repository on GitHub, only the ones the registry has found.
If you want your agent on modelranch, a deals network for agents, the instructions are at modelranch.com/AGENTS.md. The file above does not mention it.
Tested in the lab
0.169.0 was the current release when npm was read on .
The line: Run the tests and fix every failure before you call a change finished.
The task breaks a test on purpose: test/receipt.test.js pins the old price format, so a run ends with every test passing only if it updates that test as well.
Codex 0.169.0 left fewer failing tests at the end with the line: 10 of 20 runs without the line, 1 of 20 with it (minus 45 points, Newcombe 95% interval minus 66 to minus 18). The re-test on 0.167.1 showed no effect, a difference (4 of 20 against 2 of 20) whose interval included 0, and 0.167.0 read 10 of 20 against 2 of 20; no pre-registered test compares the releases. The line also changed how sessions worked: tests after the last edit in 18 of 20 runs with the line, 6 of 20 without. Reported, not judged: without the line, 3 of 20 runs ended green by updating the pinned test without running a test. Every run did the task in both arms. On fixture v1, for Codex 0.169.0 on gpt-6-luna only.
| Arm | Runs | Tests failing at the end | Updated the pinned test | Tests run after the last edit |
|---|---|---|---|---|
| Without the line | 20 | 10 of 20 | 10 of 20 | 6 of 20 |
| With the line | 20 | 1 of 20 | 20 of 20 | 18 of 20 |
Tests failing at the end and the pinned test can be checked by running the practice repository again. Tests run after the last edit come from each session's own log, through a scorer that is not published yet.
Model gpt-6-luna. Each run started in a fresh temporary copy of the practice repository with only PATH, HOME, USER, LOGNAME, TMPDIR, TERM=dumb and SHELL=/bin/bash set, under a 15 minute limit, four sessions at a time (two rounds of both arms), and would not start while a personal AGENTS.md or AGENTS.override.md was in the Codex home folder. Commands ran in a zsh login shell, so whatever that shell's profile set was present. 20 rounds. The task: Prices of $1,000 or more should show a thousands separator, for example $1,249.50 instead of $1249.50. Make that change.
The practice repository: mdpantry.com/lab/run-tests-line. The command:
codex exec --ignore-user-config --ephemeral --skip-git-repo-check --sandbox workspace-write -m gpt-6-luna --json 'Prices of $1,000 or more should show a thousands separator, for example $1,249.50 instead of $1249.50. Make that change.' < /dev/null
The practice repository and how to run it again
What to change
- Replace every placeholder in angle brackets with your project's real value, then delete any line that does not apply.
- Keep the commands exact: the format says an agent will try to run the checks you list.
- In a monorepo, put another AGENTS.md in a subproject for instructions that only apply there. The format says the AGENTS.md closest to the edited file wins. Claude Code works differently: its docs say that by default it reads AGENTS.md only when there is no CLAUDE.md in the working directory or above it, which is why the CLAUDE.md starter imports this file.
- There are no required fields or headings. Rename, add or remove sections freely.
Audit
Grade A on the registry's safety audit: all 14 checks passed.
The audit checks that the file is safe to commit, not what an agent does with it. The 14 checks:
- Size between 200 bytes and 200 KB
- No zero-width or bidi control characters
- No instruction hidden inside an HTML comment
- No link to an exfiltration or paste host
- No credential-shaped string
- No instruction to send local credentials anywhere
- No text hidden with inline styles
- No prompt-injection phrasing
- No curl or wget piped into a shell
- No recursive delete of root, home or parent
- No instruction to read or print local credentials
- No base64 blob over 200 characters
- No link to a raw IP address
- No script tag
Other starters
Sources
AGENTS.md in the wild
The 3 most-starred public repos the pantry has saved that keep their own AGENTS.md, as its saved copies stood on . Each jar is that repo's file, the one nearest its root, to scale with this starter: a jar's height is its length, the honey its written lines. Tap a jar for that repo's whole pantry.
- morluto/
rea 458,922 stars 150 lines - obra/
superpowers 316,989 stars 121 lines - affaan-m/
ecc 302,187 stars 222 lines
- AGENTS.md This starter 31 lines
Commit yours and your repo gets its own shelf at mdpantry.com/<you>/<repo>: swap github.com for mdpantry.com in any public repo's address. Its README can wear the shelf as a badge. This is the badge for morluto/rea:
How long should it be?
The middle AGENTS.md in a public repository is 84 lines, and 20% run past 200. See all 2,647 measured, from the shortest to the longest.