Skip to content
Search

AGENTS.md

lastmod 2026-04-27created 2025-08-222 edits

An open format for AI coding agents

About

  • AGENTS.md complements README: a dedicated file holding the context and instructions AI coding agents need when working on a project
  • Used in more than 20,000 open-source projects; collects information such as build/test/code style that humans don't need but agents find important
  • Provides agent-specific instructions in a clear, predictable location, keeping README concise while improving collaboration efficiency
  • A single AGENTS.md works with many agents and tools; large monorepos can use a separate AGENTS.md for each subproject
  • An open standard created through collaboration across multiple ecosystems, including OpenAI Codex, Cursor, and Google Jules

Why AGENTS.md?

  • README.md is documentation for humans: quick start, project description, contribution guidelines
  • AGENTS.md is supplementary documentation for agents, holding detailed context such as build/test/code rules without cluttering README
  • Why a separate file
    • Gives agents a predictable place to find instructions
    • Keeps README concise and focused on human contributors
    • Provides precise agent-specific instructions that complement existing documentation
  • Adopts an open, standard name anyone can use rather than a proprietary format
  • One AGENTS.md is compatible with multiple AI coding agents and tools

How to use AGENTS.md?

  • 1. Create an AGENTS.md file
    • Place it at the repository root (many agents support generating it automatically)
  • 2. Write the main sections
    • Project overview
    • Build and test commands
    • Code style guidelines
    • Testing instructions
    • Security considerations
  • 3. Include additional instructions
    • Anything you'd tell a teammate: commit/PR rules, security caveats, large datasets, deployment steps, etc.
  • 4. Handling monorepos
    • An AGENTS.md can be placed in each package
    • Agents read the nearest file and follow the instructions for that subproject
    • Example: the OpenAI repository contains 88 AGENTS.md files

FAQ

  • Required fields: none; use plain Markdown freely
  • On conflicts: the nearest AGENTS.md takes precedence; explicit user prompts apply last
  • Automatic execution: agents run the test commands listed in the file and try to fix failures
  • Can it be updated: can be changed at any time; maintain it as a living document
  • Migrating existing docs: rename the file and keep compatibility with a symbolic link
    • mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

See also

Favorite site

author Zer0 sitemap