Live session Oct 22: AI Search for Clients
Promptwatch Logo

AGENTS.md

AGENTS.md is an open Markdown file in a code repository that tells AI coding agents how to build, test and change the project. Over 60,000 projects use it.
Updated October 15, 2026
AI

Definition

AGENTS.md is an open, plain-Markdown file placed in a software repository to give AI coding agents the instructions a new developer would need: how to install dependencies, run tests, follow the code style and avoid known pitfalls. The project describes it as a README for agents. Humans read the README; AI agents read AGENTS.md.

The format came out of collaboration between OpenAI Codex, Amp, Google's Jules, Cursor and Factory in 2025. On December 9, 2025, OpenAI contributed it to the Agentic AI Foundation, a Linux Foundation directed fund launched with Anthropic's Model Context Protocol and Block's goose as the other founding projects. The AGENTS.md site says the format is used by more than 60,000 open-source projects. Tools that read it include Codex, Cursor, GitHub Copilot, Gemini CLI, Jules, Devin, Zed, Warp and Windsurf. Claude Code, which has its own CLAUDE.md file, added AGENTS.md support in version 2.1.277 in September 2026: it reads AGENTS.md when a project has no CLAUDE.md, and a CLAUDE.md can import it with a single @AGENTS.md line.

The format has no required fields. Agents read the nearest AGENTS.md in the directory tree, so a monorepo can ship one file per package and the closest one wins; an explicit instruction from the user in chat overrides the file. Typical sections cover the project overview, build and test commands, code conventions, security rules and pull request guidelines. The agents.md documentation notes that agents will try to run the test commands you list and fix failures before finishing, so the commands need to be correct. Writing these files well is part of context engineering: giving the model exactly the context it needs, in a predictable place.

AGENTS.md is a repository convention, not a web standard. No major AI search engine or browsing agent has said it reads an AGENTS.md file at the root of a website, and it should not be confused with llms.txt, a proposed content map for websites, or with robots.txt, which controls crawler access. Treat advice to publish AGENTS.md on a marketing site as speculative.

The visibility angle is real for developer-facing companies, but it runs through code rather than search. Coding agents now pick libraries, call APIs and copy integration patterns on behalf of developers, and they do it inside repositories that carry AGENTS.md files. An SDK whose example repositories include an accurate AGENTS.md, current install commands and a single recommended auth pattern is easier for an agent to use correctly and less likely to be swapped for a competitor mid-task. That is part of agent experience optimization for developer tools; our research on how AI coding agents choose SDKs covers the selection side.

Examples of AGENTS.md

  • A TypeScript monorepo keeps a root AGENTS.md with its pnpm and Turborepo commands, plus a nested AGENTS.md in the database package that forbids agents from applying migrations.
  • An API company adds an AGENTS.md to its official example apps that names the current SDK version, the required environment variables and the one auth flow it supports.
  • A team that uses both Claude Code and Codex keeps AGENTS.md as the single source of instructions and adds a CLAUDE.md containing only the line @AGENTS.md.
  • An open-source maintainer adds a security section telling agents never to commit secrets and to run the linter and tests before proposing a change.

Terms related to AGENTS.md

AI Agents

AI agents are AI systems that pursue a goal over many steps: they plan, use tools such as search, a browser or code, act on results and ask humans when needed.

AI

Model Context Protocol (MCP)

Model Context Protocol (MCP) is an open standard for connecting AI apps to tools and data. Anthropic created it; the Linux Foundation's AAIF now hosts it.

AI

Context Engineering

Context engineering is the practice of choosing what goes into an LLM's context window (instructions, retrieved content, tools, memory) to get reliable outputs.

AI

Agent Experience Optimization (AX)

Agent experience optimization (AX) makes a product, website or API easy for AI agents to discover, understand, access and use on a person's behalf.

GEO

LLMs.txt

llms.txt is a proposed Markdown file that gives AI agents a curated map of a website. Google Search ignores it, and no AI search engine says it ranks on it.

GEO

Agentic Workflows

Agentic workflows are multi-step processes where an AI model plans, calls tools, checks its own results and loops until a goal is met, with human checkpoints.

AI

Robots.txt

Robots.txt is a root-level file that tells crawlers which URLs they may fetch. It now decides whether AI search and training bots can reach your content.

SEO

LLMs-full.txt

llms-full.txt is a single Markdown file holding the full text of a site's docs for AI tools. It is a Mintlify convention, not part of the llms.txt v2 spec.

GEO

Frequently Asked Questions about AGENTS.md

Learn about AI visibility monitoring and how Promptwatch helps your brand succeed in AI search.

AGENTS.md gives AI coding agents project-specific instructions: setup and build commands, how to run tests, code style, directory layout, security rules and pull request conventions. It keeps that detail out of the human-facing README while making sure tools like Codex, Cursor, Copilot or Claude Code follow the same rules every time they work in the repository.

Be the brand AI recommends

Monitor your brand's visibility across ChatGPT, Claude, Perplexity, and Gemini. Get actionable insights and create content that gets cited by AI search engines.

Promptwatch Dashboard