What is AGENTS.md?

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:

1. Rename your file: Use the command mv AGENT.md AGENTS.md to rename your primary instruction file.
2. 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:

1. Add the file: Create an AGENTS.md file at the root of your repository.
2. Cover what matters: Add sections for project overview, build and test commands, code style guidelines, and any other relevant instructions.
3. 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.