AGENTS.md — Summary

One-liner

AGENTS.md is a simple, open format specification — a standard for a per-repo markdown file (AGENTS.md) that guides AI coding agents, analogous to what README.md is for humans.

What it is

This repo is primarily a format specification and marketing website (Next.js + Tailwind, deployed at https://agents.md/). The specification itself is minimal: place a file named AGENTS.md in any directory of your project. Agents read it for context — build commands, testing instructions, coding conventions, PR rules. The format is intentionally unstructured: plain markdown with no required fields, no schema, no enforced sections.

The repository serves two purposes:

1. Defining and promoting the AGENTS.md convention
2. Hosting the agents.md website showing compatible tools and examples

Notable stats

21,710 GitHub stars makes this the highest-starred framework in the entire Phase D batch by a wide margin. Stars largely reflect format adoption across the ecosystem — Codex CLI, Amp, Cursor, RooCode, Aider, Gemini CLI, Windsurf, Copilot, and 20+ other tools recognize AGENTS.md natively.

Quality

quality: tier-b — comprehensive format specification, active ecosystem, but the "framework" is minimal markdown convention (no code primitives to analyze deeply).

AGENTS.md — Overview

Problem Solved

AI coding agents need project-specific guidance — how to set up the dev environment, what commands to run for testing, how to format PRs, what coding conventions to follow. Before AGENTS.md existed, teams either embedded these instructions in CLAUDE.md, .cursorrules, README.md, or scattered them across tool-specific config files with no portability.

AGENTS.md proposes a single, tool-agnostic location: a AGENTS.md file at the repo root (or in any subdirectory). When a compatible agent starts working in that directory, it reads the file automatically.

Core Proposition

"Think of AGENTS.md as a README for agents."

The specification is deliberately minimal:

• Any valid markdown is a valid AGENTS.md
• No required fields, no enforced sections
• Place it anywhere in the directory tree — closest AGENTS.md to the edited file takes precedence
• Agents execute programmatic instructions they find (e.g., listed test commands)

Format Description

AGENTS.md is plain markdown. The website shows a canonical example with three sections:

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package...

## Testing instructions
- Run `pnpm turbo run test --filter <project_name>` to run checks...
- 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.

These sections are not required; they are idiomatic.

Website

The repository doubles as the agents.md website (Next.js, hosted on Vercel):

• Hero: format intro
• WhySection: rationale
• CompatibilitySection: scrolling ticker of 20+ compatible tools
• ExamplesSection: real AGENTS.md files from openai/codex, apache/airflow, temporalio/sdk-java, PlutoLang/Pluto
• HowToUseSection: setup guide
• FAQSection: 7 common questions

Ecosystem Adoption

Compatible tools listed at the time of analysis: Codex, Amp, Jules, Cursor, Factory, RooCode, Aider, Gemini CLI, goose, Kilo Code, opencode, Phoenix, Zed, Semgrep, Warp, GitHub Copilot, VS Code, Ona, Devin, Windsurf, Autopilot, Augment Code, Junie.

Migration Path

The FAQ explicitly addresses migration from competing naming conventions:

mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

This symlink strategy maintains backward compatibility for tools that read AGENT.md.

AGENTS.md — Install & Setup

Installation

There is no installer. Adoption requires one action:

1. Create a file named AGENTS.md in any project directory.
2. Write markdown instructions for the AI agent.
3. Tools that support the convention will discover and read it automatically.

For Tool Developers

Tools integrate by reading AGENTS.md from the working directory (and traversing up the tree for parent-directory context). The specification prescribes no API, no config key, no hook — just file discovery.

For tools that need explicit configuration (e.g., Aider, Gemini CLI):

Aider (.aider.conf.yml):

read: AGENTS.md

Gemini CLI (.gemini/settings.json):

{
  "context": {
    "fileName": "AGENTS.md"
  }
}

Directory Scoping

AGENTS.md can appear at multiple levels. The closest file to the edited file wins. This enables monorepo scenarios where each package has its own AGENTS.md with package-specific instructions, while the root AGENTS.md provides global defaults.

The Repository Itself

The agentsmd/agents.md repo demonstrates the convention by shipping its own AGENTS.md — which contains Next.js development guidelines for contributors working on the website. This is metadata-complete: the format's reference repo eats its own dog food.

Runtime Requirements

None — the format requires no tooling, runtime, or dependency to author. Consumption tooling lives in the AI agent products themselves.

Versioning

The specification has no version number. The format is intentionally stable by virtue of being unstructured markdown.

AGENTS.md — Commands & Skills

Commands

None. AGENTS.md defines no commands, slash-commands, or CLI primitives. It is a passive format specification.

Skills

None. The format has no skill definition mechanism.

Subagents

None. Single-agent convention with no spawning mechanism.

Hooks

None. The format specifies no hook events.

Scripts

The repository includes package.json scripts for the Next.js website:

• dev — start Next.js dev server
• build — production build
• lint — ESLint
• test — test suite (if present)

These are website maintenance scripts, not framework primitives.

What "Instructions" Look Like

An AGENTS.md file is composed of human-written markdown sections that agents parse as natural language. The canonical sections are:

• Dev environment tips — project-specific setup commands, package manager conventions
• Testing instructions — how to run tests, what passes before merge
• PR instructions — title format, required pre-commit checks

Agents that support the format are expected to execute commands they find listed (e.g., testing commands) as part of their normal task completion.

Programmatic Behavior

Per the FAQ: "Yes — if you list [testing commands], the agent will attempt to execute relevant programmatic checks and fix failures before finishing the task."

This means the "instructions" in AGENTS.md are not static documentation — compatible agents treat them as behavioral contracts to enforce during task execution.

AGENTS.md — Uniqueness & Positioning

The AGENTS.md vs AGENT.md Schism

This is the central positioning question for this batch. Two competing format specifications use nearly identical names:

The AGENTS.md FAQ instructs migrating FROM AGENT.md — the symlink command in the FAQ is a direct competitive response. The agent-md specification explicitly acknowledges the tension: "we're willing to compromise."

By star count and ecosystem adoption, AGENTS.md has won this naming competition decisively. The 270x star ratio (21,710 vs 80) and the breadth of tool support (23 tools vs 2) make AGENTS.md the de facto standard.

Comparison to CLAUDE.md and .cursorrules

AGENTS.md is the cross-tool answer to tool-specific context files:

• CLAUDE.md — Claude Code only
• .cursorrules — Cursor only
• .windsurfrules — Windsurf only
• AGENTS.md — all of the above + 20 more

The migration story from CLAUDE.md to AGENTS.md is not explicitly documented (the FAQ only covers AGENT.md migration), but the philosophy implies AGENTS.md as the canonical source and CLAUDE.md as a tool-specific fallback.

Differs From Seeds

No direct seed match. AGENTS.md is a format standard, not a framework. The closest seed is agent-os (Archetype 4 — markdown scaffold, zero primitives), but agent-os generates a CLAUDE.md file through its command system and is Claude Code-specific. AGENTS.md is the tool-agnostic alternative that requires no commands to create.

More precisely:

• vs agent-os: agent-os is complex installation + command-driven; AGENTS.md is "create a file"
• vs openspec: openspec defines a workflow; AGENTS.md defines a location
• vs superpowers: superpowers adds 87 behavioral skills on top of Claude Code; AGENTS.md adds nothing except a standard filename

What Makes it Distinctive

1. Scale of adoption: 21,710 stars is the highest of any framework in the Phase D batch corpus and rivals major developer tools. The format won by simplicity, not features.
2. Zero primitives by design: No schema. No required fields. No tooling. The specification's greatest strength is its refusal to add structure.
3. The FAQ as competitive document: The Gemini CLI and Aider configuration instructions, and the AGENT.md migration command, make the FAQ a living record of the format wars.
4. Self-demonstrating repo: The agentsmd/agents.md repo ships its own AGENTS.md — making the repo itself the canonical example of the format in use.

Observable Failure Mode

The format's weakness is inversely proportional to its strength: with no schema, no required fields, and no validation, agents receive whatever the author wrote. A poorly authored AGENTS.md (contradictory instructions, outdated commands, wrong package manager) will confuse agents with no mechanism to detect the problem. This is precisely what ai-context-linter (another batch framework) tries to address.