AGENTS.md — Project Context for AI Agents
AGENTS.md is a markdown file placed at the root of a repository that gives AI coding agents essential context about the project — how to build it, test it, and follow its conventions. Originally created by the community, it is now a Linux Foundation standard with adoption across 60,000+ repositories.
What problem does it solve?
When an AI agent opens your project for the first time, it doesn’t know your build system, testing framework, or code style. Without guidance, it guesses — and often gets things wrong. AGENTS.md provides that missing context in a format every agent can read. It answers “how does this project work?” so the agent can start contributing immediately.
How it works
Place an AGENTS.md file at your repository root. AI agents read it on every interaction, treating it as always-on project context.
What to include
- Build commands — how to install dependencies and start the project
- Testing — how to run tests, what framework you use
- Code style — naming conventions, patterns to follow or avoid
- Architecture — key frameworks, folder structure, important decisions
- Deployment — how and where the project deploys
AGENTS.md vs SKILL.md vs CLAUDE.md
These three formats serve different purposes:
| Format | Scope | Loaded |
|---|---|---|
| AGENTS.md | Project context — build, test, conventions | Every prompt |
| SKILL.md | Specific task capabilities | On demand |
| CLAUDE.md | Claude-specific project rules | Every prompt (Claude only) |
Who supports it
AGENTS.md is recognized by Claude Code, Codex, Gemini CLI, Cursor, GitHub Copilot, and most modern AI coding agents. Because it uses standard markdown with no special syntax, any agent that reads project files can benefit from it.
Related specs
- SKILL.md — for modular, on-demand capabilities
- CLAUDE.md — Claude-specific project instructions
- .cursorrules — Cursor-specific project rules
Official Specification
The AGENTS.md standard is maintained by the Linux Foundation.
Read the specification at agents.md