EarlyTerms

AGENTS.md

Established · Emerged 2025-08-20 · 243 days old

AGENTS.md is an open, vendor-neutral markdown file placed at the root of a repository that tells AI coding agents (Claude Code, Codex CLI, Cursor, Copilot, Jules, Amp, Factory, Windsurf) how to work with the codebase. It is to AI agents what README.md is to humans — build commands, conventions, boundaries, in plain markdown with no custom syntax.

The convention crystallized between August 2025 and early 2026 through a multi-vendor collaboration (OpenAI, Google, Sourcegraph, Cursor, Factory) and is now stewarded by the Agentic AI Foundation under the Linux Foundation. The initial Hacker News launch hit 837 points on Aug 20, 2025. By April 2026 the spec site reports adoption by 60,000+ open-source projects and the reference repo carries 20.3k stars.

💡

GitHub's Copilot team studied 2,500+ AGENTS.md files in Nov 2025 and distilled a six-component template: executable build commands early, real code snippets, explicit `never modify` boundaries, exact stack versions, a three-tier permission model, and a concrete agent persona.

README.md for AI agents — same root-of-the-repo slot, same markdown grammar, different reader.

Search Interest

peak ~9.7K/mo
updated 2026-04-19
~9.7K/mo ~4.8K/mo 0
2026-03-21 2026-04-05 2026-04-19
Term Lifecycle
  1. Nascent
    0–7 days
  2. Emergent
    8–30 days
  3. Validating
    31–90 days
  4. Rising
    91–180 days
  5. Established ← now
    180 days +

Why is it emerging now?

TL;DR

By Apr 2026, AGENTS.md has Linux Foundation stewardship, 60k+ adopting repos, and a real research literature — Vercel's 33/33 vs 31/33 eval result and a Feb arXiv paper gave the convention evidence-backed credibility. Anthropic's Claude Code remains the one major holdout, with feature request #6235 among its most-reacted issues.

6 forces driving coverage — scroll →
Y Hacker News
AGENTS.md: Open format for guiding coding agents
Aug 20, 2025 837 points · 382 comments
GitHub Blog
How to write a great agents.md: Lessons from over 2,500 repositories
Six-component template: executable commands, real snippets, boundaries, versions, permissions, persona.
Nov 19, 2025
Vercel
AGENTS.md outperforms skills in our agent evals
33/33 vs 31/33 — always-in-context beats maybe-in-context for facts the agent will need.
Jan 29, 2026
arXiv
Evaluating AGENTS.md: Are They Helpful for Coding Agents?
Feb 16, 2026 232 HN points
anthropics/claude-code
Feature Request: Support AGENTS.md (#6235)
One of the most-reacted Claude Code issues; still open as of Apr 2026.
Aug 21, 2025
Agentic AI Foundation
agents.md — official specification site
Linux Foundation stewardship; 25 compatible tools listed including Claude Code, Copilot, Cursor.

Outlook

6-month signal projection and commercial timeline.

Signal high
Revenue moderate

Vendor convergence, Linux Foundation governance, and a growing research literature (Vercel evals, GitHub 2,500-repo study) lock the standard in.

Risk · Anthropic continuing CLAUDE.md-specific features (@-imports, skill composition) pulls serious users away from AGENTS.md.

Analogs · README.md · .editorconfig · robots.txt · LICENSE file

Monetization timeline
  1. now
    Free spec, platforms market

    Factory, Amp, Codex, Windsurf, Cursor use AGENTS.md compatibility as a marketing claim.

  2. 3-6mo
    Generators + validators paid

    AGENTS.md generators, directory sites, and secret-scanning overlays appear as paid tools.

  3. 6-12mo
    Stack-specific marketplaces

    Template marketplaces by stack and cross-agent compliance tooling capture durable enterprise spend.

Competition & Opportunity for term “AGENTS.md”

Three heuristic signals derived from the tracked queries, the term's monetization cards, and its cluster neighbors. Directional, not audited.

Content Gap
10 queries tracked
Led by General (6), Comparison (2)
10 Suggest-only tails — long-tail opening
Revenue Potential
20% commercial-intent queries
2 monetization angles mapped
Mixed intent — educational + commercial
Build Difficulty
Very High
Stage: established — category is settled
9 / 13 default TLDs taken · oldest incumbent agentsmd.com (2025-05-16)
5 related terms already published
Heuristic · signals: tracked queries, term monetization cards, cluster neighbors

Ideas for term “AGENTS.md”

Buildable pitches — turn this term into an article, site, product, post, newsletter, video, or course. Steal any card and run with it.

Article
AGENTS.md vs CLAUDE.md vs .cursorrules: Which File Does Your Agent Actually Read?

Most common search intent: disambiguation. A precedence-order explainer grounded in Codex docs' concat rule and Claude Code's CLAUDE.md discovery logic ranks on growing long-tail.

Article
Why Your Repo Needs an AGENTS.md in 2026 — and What to Put In It

Tutorial-intent with commercial value. GitHub's 2,500-repo study supplies the data spine; a before/after benchmark on a real repo differentiates.

Article
AGENTS.md Outperformed Skills. What That Actually Means for Your Agent Stack.

Vercel's 33/33 vs 31/33 landed hot but deeper analysis is scarce. Reproduce the eval on a second codebase, quantify context-budget tradeoffs, offer a decision tree.

Article
The Six Components of a Great AGENTS.md (with 10 Real Examples from Top OSS Repos)

Extends GitHub's findings into a listicle with specimens. Top 10 most-starred repos shipping AGENTS.md is a first-mover SEO asset.

Website
Directory of exemplary AGENTS.md files, searchable by stack

gakeez/agents_md_collection is the GitHub attempt; no hosted, stack-filtered catalog exists. First-mover territory on "best agents md examples".

Product
AGENTS.md generator from a repo (hosted, with per-stack templates)

Hosted SaaS reading a GitHub repo, inferring stack, emitting a first-draft AGENTS.md with explicit secret-scanning. Prevents Copilot-leaked-credentials failure mode.

Product
AGENTS.md linter + secret scanner + drift detector

Three checks: six-component template, no API keys/private hostnames, in-sync with codebase (CI fails if the build command no longer works).

Product
Cross-agent prime-file adapter (AGENTS.md ↔ CLAUDE.md ↔ .cursorrules)

Git-hook tool keeping AGENTS.md authoritative and generating shims for the others. Immediately useful in heterogeneous agent teams.

Post Newsletter / LinkedIn
How AGENTS.md Became the robots.txt of the AI Era

In eight months AGENTS.md went from one priming-file convention to a Linux Foundation standard — Anthropic is the only holdout.

Post HN / r/programming
AGENTS.md Outperformed Skills. Here's Why, and When Skills Still Win.

Vercel's 33/33 vs 31/33 made HN. The real lesson: always-in-context beats maybe-in-context for any fact you know the agent will need.

Post YouTube / Tech media
I Audited 50 Top OSS Repos. 17 Ship an AGENTS.md — Here's What They Share.

AGENTS.md is in 60k+ repos, but GitHub's own study of 2,500 found most are too vague to help an agent.

What People Search

Long-tail queries from Google Suggest + Trends. Volume and competition are heuristics — directional, not audited. Content Type comes from query shape.

Keyword
Competition
Content Type
agents.md
Low
General
agents.md file
Low
General
agents.md vs claude.md
Low
Comparison
agents.md codex
Low
General
agents.md example
Low
Showcase
agents.md vs skills.md
Low
Comparison
agents.md claude code
Low
General
agents.md claude
Low
General
1–8 of 10
1 / 2
Updated 2026-04-19 · sources: Google Trends, Google Suggest · Competition is heuristic

SERP of term “AGENTS.md”

What searchers see today — organic results on top, paid ads if anyone's bidding. Ad density is a real-time commercial signal.

Related Terms

Other terms in the same space — aliases, subtypes, competitors, and neighbors to explore next.

Explore next
Also mentioned
  • Also known as CLAUDE.md·.cursorrules·.github/copilot-instructions.md
  • Competitor Agent Skills
  • Related README.md·Cursor·GitHub Copilot·Agentic AI Foundation

Sources

Primary URLs this report cites — open any to verify the claim yourself.

  1. 01 agents.md — official specification site agents.md ↗
  2. 02 agentsmd/agents.md on GitHub (20.3k stars) github.com ↗
  3. 03 Hacker News — AGENTS.md: Open format for guiding coding agents (837 pts, Aug 20, 2025) news.ycombinator.com ↗
  4. 04 InfoQ — AGENTS.md Emerges as Open Standard for AI Coding Agents infoq.com ↗
  5. 05 GitHub Blog — How to write a great agents.md (Nov 2025, 2,500-repo study) github.blog ↗
  6. 06 Vercel — AGENTS.md outperforms skills in our agent evals (524 HN pts, Jan 29, 2026) vercel.com ↗
  7. 07 OpenAI Codex — Custom instructions with AGENTS.md developers.openai.com ↗
  8. 08 Anthropic Claude Code — Feature Request: Support AGENTS.md (#6235) github.com ↗
  9. 09 The Prompt Shelf — AGENTS.md vs CLAUDE.md: What's the Difference thepromptshelf.dev ↗
  10. 10 arXiv — Evaluating AGENTS.md: Are They Helpful for Coding Agents? (232 HN pts) arxiv.org ↗