Why AGENTS.md Won by Standardizing Almost NothingThe 18-Month End of the AI Coding Rules War

1. The conclusion: AGENTS.md won by shrinking the agreement surface, not by expanding the specification

The configuration-file war among AI coding agents is largely over—at least for the question of where a repository should put shared instructions.

As of August 2026, the official AGENTS.md site reports adoption by more than 60,000 open-source projects. Its compatibility list includes well over twenty tools, among them Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Zed, Jules, and Factory. On August 30, the official GitHub repository had 23,991 stars and 1,815 forks.^[1][2]

Yet the standard has no JSON Schema, required headings, or version field. Its FAQ says there are no required fields at all: it is simply standard Markdown. Almost all it standardizes is a filename and a discovery convention.^[1]

Standardization usually looks like the work of adding fields. Names, types, constraints, errors, and compatibility rules become increasingly precise. AGENTS.md demonstrated the inverse strategy:

Reduce the area on which competitors must agree until it is almost just one filename. Return the contents to each project.

Tool makers can join without abandoning their product philosophy. Developers do not have to learn another configuration language. Implementers need little more than Markdown handling and an existing mechanism for placing instructions into an agent's context. AGENTS.md is not a standard that makes every agent identical. It is a standard that lets every agent find the same front door.

That is both the reason it won and the boundary of what it solves. A common entrance does not eliminate product-specific scoping, permissions, hooks, subagents, or Skills. This article follows the standard's eighteen-month convergence, the conspicuous Claude Code exception, the real use of conversion CLIs, and the security consequences of treating instruction files as commands.

2. From updating seven files to sharing one entrance in eighteen months

When AI coding tools became practical in early 2025, repositories accumulated files with nearly the same purpose:

• Cursor had .cursorrules, followed by .cursor/rules/
• GitHub Copilot used .github/copilot-instructions.md
• Claude Code used CLAUDE.md
• Cline used .clinerules
• Windsurf used .windsurfrules
• Gemini-lineage tools used GEMINI.md
• Each ecosystem added its own commands, MCP configuration, and permissions

Changing one coding convention meant translating the same intent into several destinations. A teammate who adopted another tool added another synchronization target. Version control exists to turn one change into one history, while the surrounding AI tooling had normalized manual duplication.

Distributing one convention across seven entrances was less like writing configuration and more like preventing several configurations from drifting apart.

The waste converged in the following sequence.

May 7, 2025: Amp proposes singular AGENT.md

The prehistory was singular. On May 7, Sourcegraph's AI agent Amp announced that it would read AGENT.md at the repository root. The post explicitly described the name as a way to avoid proliferating tool-specific files and expressed hope that other agents would follow. The same page now retains an update noting the later move to AGENTS.md.^[3]

May 20 to June 18, 2025: conversion CLIs move before the standard

Ruler's GitHub repository was created on May 20, followed by Japanese developer dyoshikawa's rulesync on June 18. Both pursue a common idea: maintain one source of truth and generate configuration for multiple tools. Teams that could not wait for industry consensus built a translation layer around the fragmentation.^[4][5]

August 19–20, 2025: plural AGENTS.md becomes the public vessel

The current agentsmd/agents.md repository was created at 17:22 UTC on August 19, and the site appeared the next day. Amp switched on August 20 as well. Its announcement said, in effect, that OpenAI had chosen the plural form and one standard mattered more than insisting on Amp's original spelling. The party that proposed the singular name first accepted a one-letter compromise. That small concession captures the logic of the standard.^[6][7]

The official site says AGENTS.md emerged through collaboration across the ecosystem, including Codex, Amp, Google's Jules, Cursor, and Factory. It is more accurate to see this as competitors recognizing the value of one entrance than as one vendor defeating everyone else.^[1]

December 9, 2025: stewardship moves under the Linux Foundation

OpenAI, Anthropic, and Block co-founded the Agentic AI Foundation under the Linux Foundation, contributing AGENTS.md, the Model Context Protocol, and goose as founding projects. AGENTS.md moved from a practical convention associated with one company into neutral open-source stewardship. OpenAI's announcement said it had already reached more than 60,000 open-source projects since its August release.^[8][9]

Eighteen months earlier, instruction-file proliferation seemed normal. By August 2026, it felt more natural to ask why a repository did not have AGENTS.md. The speed of convergence came from the low cost of adoption, not from the thickness of the specification.

3. Why a specification that defines almost nothing defeated richer alternatives

AGENTS.md standardizes discoverability rather than content.

There is predictable Markdown at a predictable location. A large monorepo can place additional AGENTS.md files in subdirectories, allowing instructions nearer the working file to take priority. The official site recommends keeping general guidance at the top and placing subproject-specific guidance deeper in the tree.^[1]

Products do not need identical internals if they agree on the shape and location of the socket. AGENTS.md is a shared lobby, not a shared operating system.

That thinness benefits three groups:

1. Tool makers: They can read Markdown and add it to an existing context path while retaining their own richer rules system.
2. Repository maintainers: They can manage instructions as reviewable prose without introducing a new DSL, editor, or validator.
3. Agents: They receive build commands, tests, boundaries, and project structure without asking the user to repeat them in every conversation.

Agreement would have been harder if the first version had attempted to standardize required keys, globs, a permission model, hook formats, and MCP definitions. Vendors already had installed users and compatibility promises. The question of which instruction loads when, and at what priority, is also part of product differentiation.

AGENTS.md declined to settle those questions. By choosing not to decide, it became quick to implement and difficult to oppose.

No schema does not mean every document works equally well. Agents consume the text as context rather than deterministic configuration. Excessive length, contradiction, and vague language reduce compliance. The thinner the central standard, the more responsibility returns to each repository to write concise, concrete, testable instructions.

Successful standardization is not the act of centralizing every decision. It is the act of separating the minimum that belongs in common from the freedom that should remain local.

4. The Claude Code exception: no native reading, but no need for duplicated content

Anthropic's documentation is explicit as of August 2026: Claude Code reads CLAUDE.md, not AGENTS.md. The same page now includes a dedicated AGENTS.md section and officially recommends importing an existing file like this:^[10]

@AGENTS.md

# Claude Code

Add only Claude-specific guidance here when it is actually needed.

Relative paths resolve from the file that contains the import rather than from the working directory. Imports can recurse; the current English documentation sets the maximum depth at four hops. An @ inside inline code or a fenced code block is not evaluated as an import. Imports that resolve outside the project require approval when first encountered.^[10]

A symbolic link works too:

ln -s AGENTS.md CLAUDE.md

On Windows, however, creating that link requires Administrator privileges or Developer Mode. An import is therefore more portable for a mixed team, and it leaves room for a short Claude-specific appendix.

There is one important caveat. An import does not save context. Anthropic states that imported content is expanded and placed in the context window at launch. Splitting files can improve organization and ownership; it does not make the imported text free. Long procedures belong in an on-demand Skill or a path-scoped rule rather than in instructions that every session must carry.^[10]

Claude Code's exception can even be read as evidence of how thin the compatibility layer is. If one import line preserves a single source of truth, teams do not need to duplicate the actual content while waiting for native behavior.

5. Conversion CLIs after the standard: stars and actual execution move in opposite directions

Ruler and rulesync still matter after AGENTS.md because the shared standard covers an entrance, not every native feature.

Cursor's scoped rules, Claude Code's .claude/rules/, Copilot's path-specific instructions, MCP servers, commands, subagents, Skills, hooks, and permissions do not share one format. The current rulesync README publishes a large support matrix for generating or converting not only rules but also MCP configuration, commands, subagents, Skills, hooks, permissions, and more.^[5]

A shared entrance does not erase native product features. Conversion CLIs are workshops for the differences the standard deliberately leaves outside.

GitHub API values captured on August 30, 2026 and npm's thirty-day window from July 31 through August 29 reveal an interesting reversal.^[11][12]

Ruler has more than twice rulesync's stars. Rulesync, however, recorded roughly 5.5 times as many npm downloads and exceeded one million in the same thirty-day period. Downloads include CI jobs, repeated installs by the same users, and environments without a package cache, so they are not a count of organizations. They still show that stars and recurring machine consumption measure different things.

That is why choosing a tool by GitHub stars alone is unsafe. Maintainers should examine update cadence, supported surfaces, generated diffs, responsiveness to breaking product changes, CI reproducibility, and whether a translation layer is necessary at all.

PanisHandsome/ai-rules-sync, for example, advertises a zero-dependency design and synchronization among AGENTS.md, CLAUDE.md, Cursor, Copilot, and other formats. The approach is sensible, but its latest push was June 3. In a rapidly changing ecosystem, the ability to keep tracking upstream formats is part of the product.^[13]

The practical choice is straightforward:

• If a team only needs shared build commands, tests, conventions, and boundaries, begin with one AGENTS.md.
• If it truly needs to distribute product-specific scopes, MCP servers, commands, and Skills from one source, evaluate a conversion CLI.
• Commit generated files and review the changes introduced by every generator update.

Conversion tools are not relics defeated by the standard. They are transitional but useful compatibility layers for the territory the standard intentionally leaves diverse.

6. Instruction files are commands, not harmless documentation: the Rules File Backdoor lesson

Calling AGENTS.md a “README for agents” makes it sound like passive documentation. To an agent, however, an instruction file is not merely data. It enters the context as a command capable of changing behavior.

On March 18, 2025, Pillar Security published its “Rules File Backdoor” research against Cursor and GitHub Copilot. The supply-chain technique used invisible Unicode, bidirectional-text controls, zero-width characters, and related methods to hide instructions from human reviewers. In the demonstration, a request for a simple HTML page caused the generated page to load a script from an attacker-controlled site. The hidden payload also told the assistant not to report the addition.^[14]

The document visible to a reviewer and the command parsed by a model can differ. A trusted entrance remains powerful when it has been poisoned.

Pillar reported that the characters were invisible in GitHub pull-request review at the time and survived forks. Cursor said the issue was not a platform vulnerability; GitHub said users were responsible for reviewing and accepting generated suggestions. GitHub later introduced a hidden-Unicode warning on May 1, 2025. That warning is meaningful progress, but it does not remove the repository's responsibility to inspect its instruction supply chain.^[14][15]

Central management distributes correct rules efficiently. The same mechanism distributes a compromised rule efficiently. Operational convenience and blast radius are two sides of the same design.

A realistic defense has four layers:

1. Review instruction files as code: Put AGENTS.md, CLAUDE.md, Skills, rules, and generated configuration under CODEOWNERS or mandatory review.
2. Commit generated output: Avoid fetching an unreviewed “latest” rule set at runtime. Keep translated changes visible in version control.
3. Scan invisible Unicode in CI: At minimum, detect bidirectional controls, zero-width characters, and the Unicode Tags block.
4. Require trust for external imports: Do not treat an instruction outside the working directory—or across the network—as equivalent to a reviewed local file.

For example, ripgrep can provide a focused auxiliary check for representative invisible control characters in instruction Markdown:

rg -n --pcre2 '[\x{200B}-\x{200F}\x{202A}-\x{202E}\x{2060}-\x{2069}\x{E0000}-\x{E007F}]' \
  AGENTS.md CLAUDE.md .github/skills .claude 2>/dev/null

This is not a complete Unicode-security solution. Banning all non-ASCII text would also be reckless in a multilingual repository. The goal is to detect control characters that normally have no place in an instruction file and require an explicit explanation when they are legitimate.

7. A practical 2026 structure: divide instructions into three roles instead of filling one giant file

Making AGENTS.md the single source of shared policy does not mean putting every procedure in one document. Stable instructions needed for all work should be separated from details that only apply to one location or one task.

The root then acts like a constitution, nested instructions like local law, and a Skill like an operating procedure. Current Visual Studio Code and GitHub Copilot guidance makes a similar distinction: always-on instructions for simple standards, path-based instructions for targeted rules, and Agent Skills for repeatable workflows that may include scripts and resources.^[16]

A minimal repository can look like this:

repository/
├── AGENTS.md
├── CLAUDE.md              # begins with @AGENTS.md
├── frontend/
│   └── AGENTS.md          # frontend-only guidance
└── .github/
    └── skills/
        └── deploy/
            ├── SKILL.md
            └── scripts/

The durable operating order is:

1. Make the root AGENTS.md the one source of shared policy.
2. Import it from CLAUDE.md and add only genuine Claude-specific differences.
3. Put location-specific guidance near the relevant directory or in a path-scoped rule.
4. Move long repeatable workflows into Skills that load when needed.
5. If a conversion CLI is used, version both its source and generated files, and verify in CI that regeneration produces no unexpected diff.
6. Treat instruction-file changes as part of the security review surface.

If the lack of a schema is interpreted as permission to put everything in one place, teams simply rebuild complexity as a multi-thousand-line startup prompt. Users should not bury the minimalism that made the standard successful.

8. Closing: the strongest standard was not the one that decided the most

The history of AGENTS.md compresses several lessons about how technical standards become infrastructure.

Amp proposed the singular spelling first and then yielded to the plural form. Competitors including OpenAI, Google, Cursor, and Factory adopted a shared entrance without discarding their native features. Moving under the Linux Foundation's AAIF strengthened neutral stewardship. Conversion CLIs survived by evolving toward the differences outside the standard.

A successful standard is not automatically a safe one. When the reader changes from a human to an agent, Markdown becomes both documentation and an input capable of changing execution. The more trusted the entrance, the more important diff review, Unicode scanning, and external-import boundaries become.

For a new repository in 2026, the practical answer is modest:

• Put a concise AGENTS.md at the root and make it the single source of shared policy.
• Begin Claude Code's CLAUDE.md with @AGENTS.md, then add only product-specific differences.
• Use nesting for local conventions and Skills for long repeatable procedures.
• Introduce a conversion tool only when the team truly needs to synchronize native features across products.
• Commit instruction files and generated output, then review their diffs as carefully as code.

AGENTS.md did not seize the throne from every richer configuration system. It created a small public space one level above them: a place where every tool could agree to look first.

The configuration war did not end because the strongest language won. It ended because one filename was small enough for competitors to concede and ordinary enough for everyone to use.