AGENTS.md
What is AGENTS.md?
AGENTS.md is an open Markdown standard for engineering teams that gives coding agents a predictable place to read repo instructions before acting. Teams use it for setup commands, code style, testing instructions, and PR guidance, and it works across tools like Cursor, Windsurf, Aider, and Jules. The format is stewarded by the Agentic AI Foundation under the Linux Foundation and is already used by over 60k open-source projects.
Last verifiedHow we evaluate
At a glance
- AGENTS.md is best for engineering teams who want coding agents to follow repo-specific instructions consistently.
What does AGENTS.md do?
AGENTS.md gives coding agents a predictable place to read project instructions before they act. Teams add setup commands, code style rules, testing instructions, and PR guidance in plain Markdown, so the agent can follow the same conventions every time instead of guessing from scattered docs. The format is intentionally simple and open, with examples showing TypeScript strict mode, pnpm-based setup, and repository-specific notes that can live alongside existing README files. At scale, the format is already used by over 60k open-source projects, with 60k+ examples on GitHub and 88 AGENTS.md files in the main OpenAI repo. It works across a broad ecosystem that includes Cursor, Windsurf, Aider, Jules, Junie, opencode, goose, Factory, Zed, Gemini CLI, Semgrep, VS Code, Augment Code, Devin, RooCode, Codex, Warp, UiPath, and Kilo Code. The project is stewarded by the Agentic AI Foundation under the Linux Foundation, and the site says the file is just standard Markdown with no required fields.
Why use AGENTS.md?
- It keeps agent instructions separate from README content, so human-facing docs stay concise.
- Nearest-file precedence lets large repositories override instructions at the subproject level.
- One file can guide many agents, reducing the need to maintain tool-specific instruction formats.
- The ecosystem already spans dozens of coding tools, so teams can standardize once and reuse the same guidance.
Who is AGENTS.md for?
- Engineering teams who want agents to follow the same setup and testing steps every time.
- Open-source maintainers who need a predictable place for contributor and agent instructions.
- Monorepo owners who want nested guidance for different packages or subprojects.
- Tool builders who want one open format that works across multiple coding agents.
What are AGENTS.md's key features?
Setup commands
Defines setup commands in AGENTS.md so coding agents can prepare the repo the same way across over 60k open-source projects.
Code style
Captures code style rules in a simple open format, helping agents match existing conventions instead of guessing from examples on GitHub.
Dev environment tips
Stores environment notes for tools like VS Code and Cursor, so agents know local commands, paths, and repo-specific quirks before editing.
Testing instructions
Lists testing steps in AGENTS.md, giving agents clear checks to run and reducing broken changes across 88 AGENTS.md files.
PR instructions
Adds pull request guidance for agents working in GitHub-based workflows, so changes follow the repo's review and submission process.
What does AGENTS.md integrate with?
- Amp
- Ona
- Windsurf
- Aider
- Jules
- Junie
- opencode
- Phoenix
- goose
- Factory
- Zed
- Cursor
- Gemini CLI
- Semgrep
- VS Code
- Augment Code
- Devin
- RooCode
- Codex
- GitHub Copilot
- Warp
- UiPath
- Kilo Code
What are AGENTS.md's use cases?
Engineering teams standardize agents
Engineering teams who want agents to follow the same setup and testing steps every time use AGENTS.md to keep instructions consistent across repos. They rely on Setup commands and Testing instructions so coding agents start correctly, run the right checks, and produce changes that are easier to review.
Maintainers document contributor flow
Open-source maintainers who need a predictable place for contributor and agent instructions use AGENTS.md to spell out Code style and PR instructions in one open format. That helps contributors and agents make cleaner pull requests with fewer back-and-forth comments.
Monorepo guidance by package
Monorepo owners who want nested guidance for different packages or subprojects use AGENTS.md to place Dev environment tips and Testing instructions where each subproject needs them. Agents can follow the right local context, reducing setup mistakes and broken test runs.
Multi-agent format for builders
Tool builders who want one open format that works across multiple coding agents use AGENTS.md to publish the same Setup commands and Code style guidance for tools like Cursor, Windsurf, and Aider. That creates a shared instruction layer instead of maintaining separate agent docs.
How does AGENTS.md work?
- Add an AGENTS.md file at the repo root or in a subdirectory, then write the first Setup commands agents should run before touching code.
- Fill in Code style guidance so agents match naming, formatting, and repository conventions before they generate or edit files.
- Add Dev environment tips for local dependencies, required tools, and any project-specific quirks that affect how agents work in the repo.
- Document Testing instructions with the exact checks to run, when to run them, and what a passing result should look like.
- Finish with PR instructions so agents know how to summarize changes, link related work, and prepare a review-ready pull request.
Frequently asked questions
What is AGENTS.md?
AGENTS.md is an open Markdown standard for engineering teams that gives coding agents a predictable place to read repo instructions before acting. Teams use it for setup commands, code style, testing instructions, and PR guidance, and it works across tools like Cursor, Windsurf, Aider, and Jules. The format is stewarded by the Agentic AI Foundation under the Linux Foundation and is already used by over 60k open-source projects.
What is AGENTS.md used for? Who is it for?
AGENTS.md is used for Setup commands, Code style, and Dev environment tips. It's built for Engineering teams, Open-source maintainers, and Monorepo owners.
Does AGENTS.md have an API and what does it integrate with?
AGENTS.md doesn't publish a public API.
Editor's read
Check whether your repo needs nested AGENTS.md files for subprojects, since nearest-file precedence lets lower-level instructions override parent guidance. In large monorepos, that can change setup, testing, and PR steps by directory.
Explore other Coding Agents
