# AGENTS.md: a README-shaped convention for coding agents > The proposal is one markdown file at the root of a repository, written for machines rather than people. It is worth looking at what the repository actually ships, because the format and the website are separate projects. **agentsmd/agents.md** — AGENTS.md — a simple, open format for guiding coding agents - Repository: https://github.com/agentsmd/agents.md - Website: https://agents.md - Stars: 24,828 · Forks: 1,897 - Language: TypeScript - License: MIT - Published: 2026-10-06 · Updated: 2026-10-06 · Language: en - Canonical page: https://hysenlabs.com/projects/agentsmd-agents-md ## What the file is supposed to contain The description of this repository is a single sentence: AGENTS.md is a simple, open format for guiding coding agents. The README expands that with a framing device that explains the idea faster than a specification would. Think of AGENTS.md as a README for agents, a dedicated and predictable place to give an agent the context and instructions it needs to work on the project. Predictable is doing real work in that sentence. A README is written for a human who reads it top to bottom and asks questions along the way. An agent tends not to ask questions. It reads what is in front of it and acts. So the format is not really about content, it is about placement and shape: one file, at a known location, with a known structure, so a tool can find it without being told how. That design leaves open a question this repository does not answer, which is how much prose an agent will actually read before it starts editing. The example in the README runs to about twenty lines, which is a useful calibration point. Long enough to cover build, test and review habits, short enough that a model reads all of it. ## The example file is really CI configuration in prose The README's sample file is the most informative thing in the repository, because it shows the intended density of an AGENTS.md rather than describing it. Three headings: dev environment tips, testing instructions, and PR instructions. The first section is about not wasting an agent's time. It suggests jumping straight to a package rather than scanning directories, adding a package to the workspace so that Vite, ESLint and TypeScript can see it, and confirming the right package name inside each package's own package.json rather than the top-level one. Every one of those lines saves a step an agent would otherwise take and get subtly wrong. The second section is where the format earns its keep: ```markdown ## Testing instructions - Find the CI plan in the .github/workflows folder. - Run `pnpm turbo run test --filter ` to run every check defined for that package. - From the package root you can just call `pnpm test`. - To focus on one step, add the Vitest pattern: `pnpm vitest run -t ""`. ``` The third section covers commit conventions, including a title format and the instruction to run lint and tests before committing. Read together, the three sections are a compressed description of how the repository builds, verifies and reviews itself. An agent with only this file can plausibly open a pull request that passes CI, which is the bar the format sets. ## A format repository that is mostly a website The file tree tells you what kind of project this is. Alongside `AGENTS.md`, `README.md`, `LICENSE` and `Technical_Charter.pdf` there are `components/`, `pages/`, `styles/`, `public/`, `next.config.ts` and `postcss.config.mjs`. The format is two markdown files and a PDF, and the bulk of the repository is the Next.js site that explains the format at agents.md. The site runs a small, current stack. The `package.json` pins `next` at 16.1.0 and `react` and `react-dom` at 19.2.3, with Tailwind 4.1.11 alongside `@tailwindcss/postcss`, TypeScript 5, and `@vercel/analytics` for page analytics. Getting it running locally is three commands, as the README documents: ```bash pnpm install ``` ```bash pnpm run dev ``` Package management is pinned to `pnpm@9.15.1`, and the project itself is private at version 0.1.0, which tells you the website is not distributed as a package. Nothing here is a library you would add to a dependency list. AGENTS.md has no runtime at all, which is exactly why adopting it is a one-file change rather than an integration project. ## What the repository cannot settle There are gaps a reader should notice rather than paper over. The repository records no releases, so there is no version history for the format and no changelog explaining how the example has evolved. If the convention changes, nothing here marks when or how. The same applies to the specification: the README does not define required headings, reserved filenames, or any notion of inheritance from parent directories, so two projects can both have a valid AGENTS.md and behave nothing alike. The `Technical_Charter.pdf` at the root is the most likely place for that missing definition to live, and a PDF is a reasonable choice for a document meant to be read rather than implemented. It also means the substantive text of the proposal is not greppable, diffable or versioned alongside the code, which is a trade rather than an oversight. What the repository does establish is adoption, and adoption is the hard part of a convention. Roughly 24,500 stars, about 1,870 forks, 177 open issues, an MIT license, and a last recorded push on the default branch on 2026-09-10. Those numbers describe a proposal people have looked at seriously. A `.gitignore` is the only other configuration file at the top level, which is consistent with a repository whose entire deliverable is text people copy. ## How this compares with the alternatives people use Most coding agents already read several kinds of instruction file, and the interesting question is why one of them should win. The comparison with per-product instruction files is the obvious one. A file named for a specific tool's product can only be read by that tool, so adopting it means writing the same instructions twice when you switch, and the copies drift. Naming the file after the role rather than the product means an agent has to be told to look for it, which is a small cost paid once. The comparison with skill files is a different axis. A skill is usually a self-contained procedure an agent loads on demand, with its own trigger conditions and possibly scripts to run. AGENTS.md is ambient: it describes the shape of a project so that everything an agent does is grounded in it. They are not really competitors. If anything they compose, since an AGENTS.md can point at the skills a project maintains. Whether this counts as a standard is worth pressing on. A standard usually implies a body, a process, and multiple independent implementations agreeing on a specification. What exists here is a widely used convention with one clear definition and no conformance authority. For most teams that distinction does not change what they do on Monday, and it is the reason a file written today may need revisiting as competing conventions settle. ## Conclusion AGENTS.md is a small idea with a good fit to how agents actually work, and the repository keeps it small on purpose. The format is one markdown file whose example is three headings about environment, testing and pull requests, all of them commands a developer would otherwise dig out of CI configuration. Beside it sits a Next.js site on Next 16.1.0 and React 19.2.3 that argues the case, plus a technical charter as a PDF, which is the shape you would expect from a proposal that wants adoption rather than code. The strongest argument for it is that it reuses the reading habits people already have from READMEs. The weakest is that a file an agent reads is only as reliable as the commands it points at. The repository records no releases and no version history for the format itself, so pinning a convention to a specific commit of someone's AGENTS.md is more honest than expecting the file to change in place. ## FAQ ### What is Agents.md for? It gives a coding agent a predictable place to find out how a project builds, tests and reviews itself. The README frames it as a README for agents: one markdown file with a known location and a known shape, holding the commands and conventions an agent would otherwise have to infer or ask about. ### Is agent md a standard? It is a widely adopted open convention rather than a formal standard. There is no standards body, no conformance process and no requirement about headings or reserved filenames, and the repository records no releases for the format, so nothing pins a version. The project calls it a simple, open format, and that description is accurate. ### Is Agents MD the same as CLAUDE md? They occupy the same slot, instructions about the project kept in a markdown file, but they are named for different things. A file named for one product can only be read by that product, so the same guidance gets duplicated when tooling changes. Naming the file for the role means an agent has to be told to look for it once. ### What is agent md vs skill md? They are ambient context versus on-demand procedure. An AGENTS.md describes the project so any task an agent starts is grounded in it, while a skill is a self-contained procedure loaded when a particular situation calls for it. They tend to compose rather than compete, since an AGENTS.md can point at the skills a project maintains. ## Sources - [agentsmd/agents.md on GitHub](https://github.com/agentsmd/agents.md) - [Issues](https://github.com/agentsmd/agents.md/issues) - [License: MIT](https://github.com/agentsmd/agents.md/blob/main/LICENSE) - [Project website](https://agents.md) - [README](https://github.com/agentsmd/agents.md/blob/main/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/agentsmd-agents-md