AGENTS.md

What is AGENTS.md?

AGENTS.md is an open standard for providing AI coding agents with project-specific context and instructions. Launched in August 2025, it has rapidly become the de facto way to help AI assistants understand and work effectively within a codebase.

Think of it as a README for robots: a dedicated, predictable place for the detailed instructions that coding agents need but that would clutter human-facing documentation.

The Problem It Solves

README.md files are designed for humans—quick starts, project descriptions, contribution guidelines. But AI coding agents need different information:

• Build commands: How to install dependencies, run the dev server, build for production
• Testing requirements: Which tests to run before committing, how to focus on specific tests
• Code style: Formatting preferences, naming conventions, architectural patterns
• PR conventions: Title formats, commit message styles, review requirements
• Environment details: Package manager preferences, directory structure, CI/CD setup

Putting all this in a README creates noise for human readers. AGENTS.md gives agents a predictable location for this machine-oriented context.

Standard Format

AGENTS.md is intentionally simple—just standard Markdown with no required schema:

# Sample AGENTS.md file

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package
- Run `pnpm install --filter <project_name>` to add the package to your workspace
- Check the name field inside each package's package.json to confirm the right name

## Testing instructions
- Find the CI plan in the .github/workflows folder
- Run `pnpm turbo run test --filter <project_name>` to run tests
- Fix any test or type errors until the whole suite is green
- Add or update tests for the code you change, even if nobody asked

## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing

Common Sections

While there are no required fields, popular sections include:

• Project overview: Architecture, key concepts, important files
• Setup commands: Install, build, dev server
• Code style guidelines: Formatting, naming, patterns to follow/avoid
• Testing instructions: How to run tests, what coverage is expected
• PR/commit conventions: Title formats, review requirements
• Security considerations: Sensitive areas, what not to modify
• Deployment steps: Production builds, release processes

How It Works

Agents automatically discover and parse AGENTS.md files:

1. Root-level AGENTS.md: Applies to the entire repository
2. Nested AGENTS.md: In subdirectories for package-specific instructions
3. Closest wins: Agents read the nearest file in the directory tree
4. User prompts override: Explicit chat instructions take precedence

For large monorepos (like OpenAI's own repositories with 88+ AGENTS.md files), this hierarchy ensures each subproject gets tailored guidance while sharing repository-wide conventions.

Platform Adoption

AGENTS.md has achieved remarkable adoption since August 2025:

Platform	Status
OpenAI Codex	Native support (creator)
GitHub Copilot	Full integration
Cursor	Built-in support
Google Jules	Native support
Gemini CLI	Configurable via settings.json
VS Code	Agent mode support
Aider	Configurable via .aider.conf.yml
Devin	Full support
Factory	Built-in
Amp (Sourcegraph)	Native support

The format's simplicity—plain Markdown with no proprietary extensions—makes it easy for any tool to parse and respect.

Governance: Agentic AI Foundation

In late 2025, OpenAI contributed AGENTS.md to the Agentic AI Foundation (AAIF), a directed fund under the Linux Foundation. The foundation was co-founded by:

• Founding members: OpenAI, Anthropic, Block
• Supporting companies: Google, Microsoft, Amazon, Bloomberg, Cloudflare

This governance structure ensures:

• Vendor neutrality: No single company controls the standard
• Open evolution: Community input drives development
• Long-term sustainability: Linux Foundation's proven stewardship model
• Portability: Standard works across all tools and platforms

Best Practices

Do

• Keep it actionable: Specific commands over vague guidance
• Include verification steps: How to know if changes work
• Document the unusual: Edge cases, gotchas, non-obvious requirements
• Update as you go: Treat it as living documentation
• Use nested files: Package-specific instructions in monorepos

Don't

• Duplicate the README: Complement, don't repeat
• Include secrets: No API keys, credentials, or sensitive data
• Be too verbose: Agents can follow concise instructions
• Forget to test it: Try asking an agent to follow your AGENTS.md

Migration from Other Formats

If you have existing agent instructions (AGENT.md, CLAUDE.md, .cursorrules):

# Rename and create symlinks for backward compatibility
mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

Tool-Specific Configuration

Aider (.aider.conf.yml):

read: AGENTS.md

Gemini CLI (.gemini/settings.json):

{ "contextFileName": "AGENTS.md" }

The Ecosystem Effect

AGENTS.md represents a broader shift in how we think about documentation. Just as README.md became foundational for open source, AGENTS.md is becoming foundational for AI-assisted development.

The comparison to early README adoption is apt: a simple convention that started as a practical solution and evolved into an ecosystem standard. The key difference is velocity—AGENTS.md went from 0 to 60,000+ repositories in six months.

This rapid adoption signals that developers want their codebases to be agent-ready, and that a simple, open standard beats proprietary configuration formats every time.

The Bottom Line

AGENTS.md has won. With backing from every major AI lab, adoption by all significant coding agents, and Linux Foundation stewardship, it's the standard for agent-facing documentation. If you're building software in 2026, you should have an AGENTS.md file.