# AGENTS.md Explained: One File to Rule All Agents
When I work with multiple AI coding agents, keeping their instruction files consistent takes extra work. AGENTS.md gives compatible agents a shared place to read project instructions.
Author: Vladislav Guzey
Published: 2025-08-21
Canonical: https://proflead.dev/posts/agents-md-tutorial/
When I [work with multiple AI coding agents](/posts/best-ai-for-coding/), keeping their instruction files consistent takes extra work. AGENTS.md gives compatible agents a shared place to read project instructions.
## 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.
AGENTS.md provides a shared location for project instructions that compatible coding agents can read.
## 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.
For a task you repeat across projects, such as a code review or release checklist, you can also package the workflow as a [Codex skill](/posts/codex-skills-explained-101/).
`AGENTS.md` 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.
### Agents.md example
```md
# Sample AGENTS.md file
## Dev environment tips
- Use `pnpm dlx turbo run where ` to jump to a package instead of scanning with `ls`.
- Run `pnpm install --filter ` to add the package to your workspace so Vite, ESLint, and TypeScript can see it.
- Use `pnpm create vite@latest -- --template react-ts` to spin up a new React + Vite package with TypeScript checks ready.
- Check the name field inside each package's package.json to confirm the right name; skip the top-level one.
## Testing instructions
- Find the CI plan in the .github/workflows folder.
- Run `pnpm turbo run test --filter ` to run every check defined for that package.
- From the package root you can just call `pnpm test`. The commit should pass all tests before you merge.
- To focus on one step, add the Vitest pattern: `pnpm vitest run -t ""`.
- Fix any test or type errors until the whole suite is green.
- After moving files or changing imports, run `pnpm lint --filter ` to be sure ESLint and TypeScript rules still pass.
- Add or update tests for the code you change, even if nobody asked.
## PR instructions
- Title format: []
- Always run `pnpm lint` and `pnpm test` before committing.
```
## 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.
## Agents.md 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_**](https://youtu.be/TC7dK0gwgg0?si=L2b4p_CkoHLMDsI-)
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.