What It Does
AGENTS.md is an open specification for a Markdown file placed at the root of a software repository (or a user’s home directory) that gives AI coding agents the project context they need to work effectively. Think of it as a README written specifically for agents rather than humans: it contains build steps, test commands, code conventions, directory structure, and task instructions that agents should know before making any changes.
The file serves as a portable “tribal knowledge” document — capturing the context that a senior engineer carries in their head and making it available to any AI coding agent reading the repository. Unlike tool-specific configuration files (.cursorrules for Cursor, CLAUDE.md for Claude Code), AGENTS.md is designed as a cross-tool standard. It is now stewarded by the Agentic AI Foundation (AAIF) under the Linux Foundation, with backing from Anthropic, OpenAI, Google, AWS, Bloomberg, and Cloudflare.
The specification is hierarchical: agents read the nearest AGENTS.md in the directory tree, allowing monorepos to ship tailored instructions per sub-project. Cisco DevNet’s adoption is a cited early enterprise case study.
Key Features
- Cross-agent portability: Supported by Claude Code, OpenAI Codex CLI, Cursor, GitHub Copilot, Windsurf, Kilo Code, and 20+ other agents.
- Hierarchical precedence: Closest AGENTS.md in directory tree wins; supports monorepo with per-package instructions.
- Plain Markdown: No special tooling or schema required. Human-readable, version-controllable, reviewable in any editor or GitHub.
- Home directory support:
~/.agents.mdprovides global context for all projects on a developer’s machine (user preferences, style guidelines, personal context). - Linux Foundation governance: Under AAIF since December 2025, providing vendor-neutral stewardship alongside MCP and Goose.
- Broad empirical base: GitHub analyzed 2,500+ repos using AGENTS.md and published guidance on effective patterns (January 2026).
- Complementary to SKILL.md: AGENTS.md provides project context; SKILL.md (Agent Skills Specification) provides reusable capability modules. Both are under AAIF governance.
Use Cases
- Repository onboarding: Eliminate agent hallucinations about build commands, test frameworks, and code conventions by encoding them in AGENTS.md at the root.
- Monorepo management: Per-package AGENTS.md files provide targeted context to agents working in specific sub-directories (e.g., backend vs. frontend vs. infra).
- Enterprise developer portals: Cisco DevNet uses AGENTS.md to guide agents navigating internal APIs and documentation — a replicable pattern for large orgs.
- Open-source library maintainers: Ship AGENTS.md so that contributors using AI coding agents get accurate guidance on contribution workflow, test requirements, and release process.
- Multi-agent orchestration: Provides a stable context anchor for orchestrated agents (via tools like Vibe Kanban or Claude Flow) working on the same repository in parallel.
Adoption Level Analysis
Small teams (<20 engineers): High value, near-zero cost. A well-written AGENTS.md can significantly reduce agent errors on project-specific conventions. Should be standard practice for any team using AI coding agents.
Medium orgs (20–200 engineers): Worth establishing an org-wide template and requiring AGENTS.md in all repositories. GitHub’s 2,500-repo analysis shows strong correlation between AGENTS.md quality and reduced agent rework.
Enterprise (200+ engineers): High-value for large codebases with complex build systems, compliance requirements, or monorepo structures. The hierarchical model supports fine-grained control. Governance via AAIF reduces vendor lock-in risk vs. tool-specific formats.
Alternatives
| Alternative | Key Difference | Prefer when… |
|---|---|---|
| CLAUDE.md | Claude Code-specific memory file; hierarchical, rich Claude-specific features | You are a Claude Code-only team and want Claude-specific behaviors (custom slash commands, memory tiers) |
| .cursorrules | Cursor-specific rules file; ignored by other tools | You are a Cursor-only team |
| SKILL.md (Agent Skills) | Defines reusable capability modules, not project context | You are publishing a skill for reuse across many projects/teams |
| README.md | Human-oriented documentation; agents may read it but it lacks agent-specific structure | You want one file serving both human contributors and agents (acceptable but suboptimal) |
Evidence & Sources
- AGENTS.md specification repository — agentsmd/agents.md
- How to write a great agents.md: Lessons from over 2,500 repositories — GitHub Blog
- Custom instructions with AGENTS.md — OpenAI Codex docs
- AGENTS.md vs CLAUDE.md — The Prompt Shelf comparison
Notes & Caveats
- Overlap with CLAUDE.md: Teams using Claude Code exclusively may find little reason to maintain both AGENTS.md and CLAUDE.md. The pragmatic advice from multiple independent sources is: AGENTS.md as universal baseline, CLAUDE.md only for Claude-specific features. Keeping them in sync is a maintenance overhead that can create divergence.
- Quality variance: An AGENTS.md file is only as useful as its content. Empty, stale, or boilerplate files provide no value. The GitHub analysis noted that low-quality AGENTS.md files sometimes cause agents to confidently apply incorrect conventions.
- Not a replacement for documentation: AGENTS.md provides agent-specific operational context; it does not replace project README, architecture docs, or API reference. Conflating the two leads to bloated, hard-to-maintain files.
- Vendor support fragmentation: While AAIF governance provides a spec, individual tool vendors implement it with varying fidelity. Edge cases (home directory precedence, encoding, file size limits) may behave differently across tools.
- Privacy consideration: Home directory
~/.agents.mdcontaining personal preferences or system context may inadvertently expose sensitive information if the agent runtime is cloud-hosted or logs context. - Enterprise-scale auto-generation (Cloudflare, April 2026): Cloudflare reported auto-generating AGENTS.md files across ~3,900 repositories by pulling data from their Backstage service catalog (2,055 services, 228 APIs). This is the first publicly documented large-scale programmatic AGENTS.md generation — relevant for enterprises with large service portfolios where manual authoring is impractical.