Description
AGENTS.md is a simple, open format for guiding coding agents, used by over 60k open-source projects. Think of it as a README for agents. Traditional README.md files are tailored for human contributors, offering quick starts, project descriptions, and contribution guidelines. AGENTS.md complements this by providing the extra, sometimes detailed context that coding agents require, such as build steps, tests, and conventions that may clutter a README or are not relevant to human contributors.
The separation of AGENTS.md from README.md serves multiple purposes. It gives agents a clear, predictable place for instructions, keeps READMEs concise and focused on human contributors, and provides precise, agent-focused guidance that complements existing README and documentation. Rather than introducing another proprietary file, AGENTS.md adopts a name and format that can be utilized by anyone. If you are building or using coding agents and find this format helpful, you are encouraged to adopt it.
One AGENTS.md file is compatible across many agents, making it a versatile tool for developers. The agent definitions you create can work seamlessly with a growing ecosystem of AI coding agents and tools, including openai/codex, apache/airflow, temporalio/sdk-java, and PlutoLang/Pluto. To effectively use AGENTS.md, you should add the file to your project and cover what matters by including sections that help an agent work effectively. Popular choices for these sections include project overview, build and test commands, code style guidelines, testing instructions, and security considerations.
AGENTS.md emerged from collaborative efforts across the AI software development ecosystem, including contributions from OpenAI Codex, Amp, Jules from Google, Cursor, and Factory. The format is now stewarded by the Agentic AI Foundation under the Linux Foundation, with a commitment to maintaining and evolving it as an open format that benefits the entire developer community, regardless of the coding agent in use.
AGENTS.md's Core Features
Open Format
Compatible with multiple agents
Detailed context for coding agents
Supports nested AGENTS.md files
Guidance for project-specific instructions
Community-driven development
Stewarded by Agentic AI Foundation
Facilitates collaboration across projects
How to use AGENTS.md?
Add AGENTS.md: Include the AGENTS.md file in your project.
Cover what matters: Add sections that help an agent work effectively with your project.
Add extra instructions: Provide additional guidance as needed.
Use nested files: For large monorepos, implement nested AGENTS.md files for subprojects.
AGENTS.md's Use Cases
- Project Documentation
- Open Source Collaboration
- Agent Configuration
- Testing Instructions
- Build Steps
