AGENTS.md
A simple, open format for guiding AI coding agents in projects.
What is AGENTS.md? Complete Overview
AGENTS.md is a standardized Markdown file format designed to provide AI coding agents with the necessary context and instructions to work effectively on a project. It serves as a complementary file to README.md, focusing on detailed build steps, testing instructions, and coding conventions that are crucial for AI agents but might clutter human-focused documentation. With adoption in over 20,000 open-source projects, AGENTS.md ensures that AI agents can seamlessly integrate into development workflows, reducing friction and improving efficiency. The format is supported by a wide range of AI coding tools and platforms, making it a versatile solution for developers and teams.
What Can AGENTS.md Do? Key Features
Standardized Format
AGENTS.md uses a simple Markdown format, making it easy to create and maintain. It provides a predictable structure that AI agents can reliably parse and utilize.
Agent-Focused Instructions
The file includes detailed instructions tailored for AI agents, such as build commands, test suites, and code style guidelines, ensuring consistent and efficient project contributions.
Compatibility with Multiple Agents
AGENTS.md is compatible with a wide range of AI coding agents and tools, including OpenAI Codex, Google's Gemini CLI, GitHub Copilot, and more, ensuring broad usability.
Nested Configuration
For large monorepos, AGENTS.md can be nested within subdirectories, allowing for project-specific instructions. The closest AGENTS.md file to the edited file takes precedence.
Living Documentation
AGENTS.md is designed to evolve with the project, allowing developers to update instructions as needed. It serves as a dynamic resource for both current and future AI contributors.
Best AGENTS.md Use Cases & Applications
Open-Source Collaboration
Open-source projects can use AGENTS.md to streamline contributions from AI coding agents, ensuring consistent adherence to project standards and reducing manual review overhead.
Monorepo Management
Large monorepos with multiple subprojects can leverage nested AGENTS.md files to provide specific instructions for each subproject, improving agent efficiency and accuracy.
CI/CD Integration
AGENTS.md can include commands for running tests and linting, allowing AI agents to automatically validate changes before submission, reducing CI/CD pipeline failures.
How to Use AGENTS.md: Step-by-Step Guide
Create an AGENTS.md file at the root of your repository. Many AI coding agents can scaffold this file for you upon request.
Populate the file with relevant sections such as project overview, build and test commands, code style guidelines, and testing instructions.
Include any additional instructions that would help an AI agent, such as commit message formats, PR guidelines, or security considerations.
For large projects with multiple subdirectories, create nested AGENTS.md files to provide tailored instructions for each subproject.
Commit the AGENTS.md file to your repository. AI agents will automatically detect and use the instructions provided.
AGENTS.md Pros and Cons: Honest Review
Pros
Considerations
Is AGENTS.md Worth It? FAQ & Reviews
No, AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide.
The closest AGENTS.md to the edited file takes precedence. Explicit user chat prompts override everything.
Yes—if you list them. The agent will attempt to execute relevant programmatic checks and fix failures before finishing the task.
Absolutely. Treat AGENTS.md as living documentation that evolves with your project.
Rename existing files to AGENTS.md and create symbolic links for backward compatibility: `mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md`.