AGENTS.md

What is AGENTS.md

AGENTS.md is a simple, open format for guiding coding agents. Think of it as a README for agents: a dedicated, predictable place to provide context and instructions to help AI coding agents work on your project. It is used by over 60k open-source projects.

How to use AGENTS.md

1. Add AGENTS.md: Create an AGENTS.md file at the root of your repository. Most coding agents can even scaffold one for you if you ask nicely.
2. Cover what matters: Add sections that help an agent work effectively with your project. Popular choices include project overview, build and test commands, code style guidelines, testing instructions, and security considerations.
3. Add extra instructions: Commit messages or pull request guidelines, security gotchas, large datasets, deployment steps—anything you’d tell a new teammate belongs here too.
4. Large monorepo? Use nested AGENTS.md files for subprojects: Place another AGENTS.md inside each package. Agents automatically read the nearest file in the directory tree, so the closest one takes precedence and every subproject can ship tailored instructions.

Features of AGENTS.md

• Open format: AGENTS.md is just standard Markdown. No required fields—use any headings you like.
• Agent-focused: Complements README.md by containing extra, sometimes detailed context coding agents need, such as build steps, tests, and conventions.
• Predictable location: Gives agents a clear, predictable place for instructions.
• Keeps READMEs concise: Allows READMEs to remain focused on human contributors.
• Compatible across many agents: Works with a growing ecosystem of AI coding agents and tools, including OpenAI Codex, Jules from Google, Factory, Aider, goose, opencode, Zed, Warp, VS Code, Devin, UiPath Autopilot & Coded Agents, Junie from JetBrains, Amp, Cursor, RooCode, Gemini CLI, Kilo Code, Phoenix, Semgrep, GitHub Copilot Coding agent, Ona, Windsurf, and Augment Code.
• Nested support: Supports multiple AGENTS.md files in monorepos for subproject-specific instructions.
• Living documentation: Can be updated at any time.

Use Cases of AGENTS.md

• Providing build and test commands: List commands like pnpm install, pnpm dev, pnpm test so agents can set up and verify the project.
• Defining code style: Specify conventions such as TypeScript strict mode, single quotes, no semicolons, and functional patterns.
• Guiding PR creation: Include title formats and pre-commit checks like linting and testing.
• Monorepo management: Use nested AGENTS.md files to give tailored instructions for each package.
• Migration from existing docs: Rename existing agent instruction files to AGENTS.md and create symbolic links for backward compatibility.

FAQ

Are there required fields? No. AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide.

What if instructions conflict? The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything.

Will the agent run testing commands found in AGENTS.md automatically? Yes—if you list them. The agent will attempt to execute relevant programmatic checks and fix failures before finishing the task.

Can I update it later? Absolutely. Treat AGENTS.md as living documentation.

How do I migrate existing docs to AGENTS.md? Rename existing files to AGENTS.md and create symbolic links for backward compatibility: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md.