If you’re like me and work with multiple AI coding agents, you know the frustration of managing different instruction files. It’s a pain to keep everything updated across various formats. But I’ve got some great news for you. A new, simplified standard has emerged, and it’s called AGENTS.md.
The Problem with Competing Standards
For a while now, working with different AI agents meant juggling multiple configuration files. Whether it was claude.md, gemini.md, or .cursor/rules, each agent had its own format. This created a mess of redundant files that all needed to be updated separately. It was inefficient and confusing.
Big companies recognized this problem. They came together to create a unified solution — AGENTS.md. The goal was to establish a single, predictable place for all AI agents to find the instructions they need to work on a project.
What is AGENTS.md?
Think of AGENTS.md as a README file, but for machines. It’s a simple, open-source format that guides AI coding agents on how to interact with your project. It’s already being used by over 20,000 open-source projects.
This file provides all the necessary context for an AI to understand and work on your code, including:
- Setup Commands: Instructions on how to install dependencies and build the project.
- Code Style: Rules on formatting and design patterns to ensure consistency.
- Testing: How to run tests to verify changes.
- Commit Guidelines: Preferred formats for commit messages and linting rules.
- Custom Notes: Any other important information, like security considerations or performance tips.
Look at the example below.
How to Migrate to AGENTS.md
Migrating to AGENTS.md is straightforward. You can consolidate your existing instruction files in just two simple steps using your terminal:
- Rename your file: Use the command mv AGENT.md AGENTS.md to rename your primary instruction file.
- Create a symbolic link: Use ln -s AGENTS.md AGENT.md to create a symbolic link. This ensures backward compatibility with any tools that haven’t been updated to the new standard yet.
How to Use AGENTS.md
Getting started with AGENTS.md is easy:
- Add the file: Create an AGENTS.md file at the root of your repository.
- Cover what matters: Add sections for project overview, build and test commands, code style guidelines, and any other relevant instructions.
- Add extra instructions: Include commit messages, pull request guidelines, and anything else a new teammate would need to know.
Best Practices
To get the most out of AGENTS.md, here are a few best practices to follow:
- Be explicit and concise: Keep your instructions clear and to the point.
- Keep instructions up to date: Make sure the file is always current with your project’s needs.
- Link to existing docs: Instead of duplicating information, link to your existing documentation.
- Use multiple files for monorepos: For large monorepos, you can use nested AGENTS.md files for different subprojects.
Video Overview about Agents.MD
Watch on YouTube: agents.md explained
And that’s it! By adopting the AGENTS.md standard, you can streamline your workflow, ensure consistency, and make it easier for AI agents to work with your projects.