If you have spent any time pairing with a coding agent — Codex, Copilot, Claude Code, Kilo, Gemini — you have probably noticed the same friction over and over. The agent guesses the wrong build command. It edits a generated file by hand. It commits before you wanted it to. It tries to install a package you have already banned. It rediscovers the same project conventions you taught it last week.
AGENTS.md is the emerging convention for fixing this. It is a small, version-controlled Markdown file that lives in your repository and tells coding agents how this codebase actually works. Think of it as a README for machines: the predictable place to put build commands, testing instructions, conventions, architectural boundaries, and behavioral guardrails that would clutter your human-facing README.md or be too implicit for an autonomous tool run.
This guide walks through what AGENTS.md is, how the major tools read it, what to put inside, what to leave out, how to validate it in CI, and how the early empirical research suggests you should think about its real-world impact. It draws on the official AGENTS.md site, the OpenAI Codex documentation, GitHub Copilot’s instruction docs, Anthropic’s Claude Code memory docs, Kilo’s documentation, and recent 2026 research on the impact of context files on agent behavior.
For a broader perspective on how the agentic ecosystem is evolving, see our companion writing on AI coding agents at kingy.ai and our notes on practical AI tooling.
What AGENTS.md actually is
The safest way to define AGENTS.md is this: a version-controlled, repository-local instruction file for coding agents. The canonical filename in the emerging open convention is uppercase, plural, and Markdown — AGENTS.md. Kilo’s documentation explicitly recommends uppercase AGENTS.md and treats singular AGENT.md only as a fallback alias. The draft AGENTS specification names uppercase AGENTS.md as canonical and frames aliases as compatibility measures rather than the norm. The lowercase phrase “agents.md” is fine in prose, but the repository convention is uppercase.
The core purpose is stable across sources. Both agents.md and the OpenAI Codex docs describe it as a “README for agents” — the predictable home for build commands, testing instructions, code conventions, architectural notes, and behavioral guardrails. GitHub Copilot documents AGENTS.md specifically under agent instructions, distinguishing it from repository-wide and path-scoped Copilot instruction files.
OpenAI states that since its August 2025 release, AGENTS.md has been adopted by more than 60,000 open-source projects and agent frameworks, and the specification was donated to the Agentic AI Foundation under the Linux Foundation in December 2025. That puts it in an unusual position: it is the closest thing today to a vendor-neutral baseline, while the surrounding landscape still includes tool-specific neighbors such as CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, custom-agent .agent.md profiles, and SKILL.md manifests.
The most important practical fact, though, is that AGENTS.md is not a rigid schema today. The convention is an uppercase Markdown file at the repository root, with nested files allowed in some tools for subtree-specific guidance. The body is intentionally freeform. That simplicity is an advantage — it keeps authoring friction low and preserves portability — but it also means teams must distinguish carefully between what belongs in AGENTS.md and what belongs in more structured neighbors.
Why repository context files exist in the first place
Without a context file, a coding agent has to infer everything from your code: the package manager, the test runner, the lint rules, the architectural boundaries, the things you would never let a human reviewer merge. Some of that inference is accurate; much of it is expensive guesswork. The agent runs commands that fail, edits files it should not touch, and burns tokens exploring directories that have nothing to do with the task.
A repository-local context file pins that knowledge in version control. Unlike a prompt you paste into a chat window, an AGENTS.md file:
- Travels with the repository and applies to every contributor — human or otherwise.
- Lives under the same review process as the code it describes.
- Can be linted, validated in CI, and updated alongside the code it references.
- Can be inherited by multiple tools through adapters, imports, or symlinks.
That last point is what makes AGENTS.md interesting strategically. The same file can be read directly by Codex, picked up by Copilot, imported into CLAUDE.md, and referenced by Kilo, without you maintaining four parallel sets of instructions. The empirical research on cross-file references in real repositories (Configuring Agentic AI Coding Tools: An Exploratory Study, arXiv 2602.14690) makes the case bluntly: context files now dominate the configuration surface of coding-agent repositories, and the cost of maintaining several independent ones grows quickly with each tool you adopt.
The ecosystem map
To use AGENTS.md well, you need a clear picture of what it is not. Several adjacent file formats exist, each optimized for a slightly different job. A practical, tool-agnostic split looks like this:
| Artifact | Best job | Typical structure | Ecosystem status |
|---|---|---|---|
README.md | Human onboarding and project overview | Freeform Markdown | Universal |
AGENTS.md | Agent-facing repository conventions and guardrails | Freeform Markdown | Emerging cross-tool baseline |
CLAUDE.md / GEMINI.md | Tool-specific context file for particular ecosystems | Freeform Markdown | Common sibling formats |
SKILL.md | Reusable workflow/package of instructions, resources, scripts | Markdown + YAML frontmatter | Structured, cross-tool-adjacent |
.agent.md | Specialized custom-agent persona with tools and MCP | Markdown + YAML frontmatter | Structured GitHub custom-agent format |
.instructions.md | Path-specific or file-glob-scoped instructions | Markdown + YAML frontmatter | GitHub-specific path rule format |
The recommendation that follows from this table is concise: put durable repository truth in AGENTS.md; put reusable workflows in GitHub Copilot skills; put explicit tool access and MCP configuration in custom-agent profiles; keep README.md human-first. That division aligns with the draft AGENTS proposal’s distinction between behavior and capabilities, with the GitHub and OpenAI skill models, and with empirical work showing that context files are widely adopted but advanced mechanisms remain shallowly used.
For more background on the broader landscape of agent tooling, see our overview material on kingy.ai.
Where the file lives and how tools find it
The root of the repository is the default location in almost every implementation. From there, tool behavior diverges in interesting ways.
| Tool or ecosystem | Primary file | Discovery behavior |
|---|---|---|
| OpenAI Codex | AGENTS.md | Global ~/.codex/AGENTS.md, then project root down to the current directory; local files later in the chain override earlier guidance; supports AGENTS.override.md; default 32 KiB limit. |
| GitHub Copilot | AGENTS.md | Multiple files supported anywhere in the repo; the nearest file in the directory tree takes precedence. |
| Anthropic Claude Code | CLAUDE.md | Does not read AGENTS.md natively; can import via @AGENTS.md or /init, and can incorporate relevant parts of an existing AGENTS.md. |
| Kilo Code | AGENTS.md | Loads root and subdirectory files; subdirectory files override; AGENT.md accepted as fallback; file is write-protected by default. |
Google agents-cli projects | GEMINI.md | Scaffolded as a guidance file read automatically in generated projects. |
Codex’s documentation is the most explicit about layering: it reads global guidance from ~/.codex, then the repository root, then walks down toward the current working directory, layering each file on top of the last and preferring AGENTS.override.md when present. It stops once a configured byte limit is reached.
Copilot takes a “nearest file wins” approach: you can put AGENTS.md anywhere in the repository, and the file closest to the file being worked on takes precedence. Kilo loads both root and subdirectory files, with lower directories overriding higher-level guidance, and write-protects the files by default to prevent the agent from silently rewriting its own instructions. Claude Code does not read AGENTS.md natively, but Anthropic explicitly recommends importing it into CLAUDE.md or symlinking CLAUDE.md to it. Google’s agents-cli scaffolds a GEMINI.md for generated projects, demonstrating that adjacent context-file conventions remain common.
A good mental model is baseline → subtree override → structured extension. Root AGENTS.md should encode rules that apply almost everywhere. Nested AGENTS.md files should appear only where a subtree genuinely differs. Skills, agent profiles, MCP configuration, and tool-specific rules should handle workflows or capabilities that would otherwise bloat the core file.
Writing your first AGENTS.md
The single most important structural fact is that plain AGENTS.md currently has no mandatory body schema. Both Kilo’s documentation and the draft AGENTS proposal state that the file is standard Markdown and that authors should use whatever headings and organization best communicate their guidance. That is a feature, not a bug. It keeps the entry cost low, and it preserves tool portability.
It also means the “common schema” of AGENTS.md is best understood as a de facto content model rather than a strict formal specification. In practice, the durable sections repeat across official examples, real repositories, and research taxonomies: project overview, setup/build/test commands, code style, architecture or boundaries, security constraints, repository workflow, and local developer idioms.
A minimal, portable root file is closer to a checklist than a document:
markdownCopy# AGENTS.md ## Overview This repository contains a TypeScript service and a Python worker. ## Commands - Install: `pnpm install`- Lint: `pnpm lint`- Unit tests: `pnpm test`- Full check: `pnpm check`## Conventions - Prefer exact script names from `package.json`. - Do not change generated files by hand. - Ask before adding production dependencies. ## Boundaries - API routes stay thin. - Business logic belongs in services. - Secrets must come from environment variables, never source files. ## Workflow - Run relevant checks after edits. - Update docs if behavior changes. - Do not commit unless explicitly asked.
That structure is synthetic, but it is consistent with the official “README for agents” framing and with the recurring patterns in real repositories. None of those sections are required by any standard. They are simply what agents most often need to know that they cannot easily infer from code.
A few authoring habits make these files dramatically more useful in practice.
Use exact, copy-pasteable commands. “Run the tests” is weaker than “Run pnpm test,” which is weaker still than Run pnpm test –filter web to test only the web app. The empirical work on Codex efficiency (arXiv 2601.20404) suggests that one of the most measurable effects of a good AGENTS.md is reducing tool thrash — the agent stops trying three commands before finding the right one.
State hard constraints explicitly. Vague style adjectives (“clean,” “idiomatic”) rarely translate into agent behavior. Concrete prohibitions (“Do not import from internal/legacy/“) do.
Separate “always,” “ask first,” and “never.” The Sanity agent-toolkit example demonstrates this pattern well. Autonomous agents do better when non-negotiable risks are written as direct commands rather than implied socially.
Stay short. A 200-line AGENTS.md that an agent will trust is more useful than a 2,000-line one it half-loads and partially obeys. Codex enforces a 32 KiB default limit; the practical limit for usefulness is much smaller than that.
What belongs in AGENTS.md — and what does not
A simple rule of thumb: anything an autonomous contributor genuinely needs in order to work safely and efficiently in this repository belongs in AGENTS.md. Anything tool-specific, executable, or structured belongs elsewhere.
| Content type | Fits in plain AGENTS.md | Recommendation |
|---|---|---|
| Project overview | Yes | One short section; link out for deep docs. |
| Exact setup/build/test commands | Yes | Copy-pasteable; note the source of truth when one exists (e.g., a CI matrix). |
| Code style and conventions | Yes | State hard constraints explicitly; avoid vague adjectives. |
| Architecture and boundaries | Yes | Use for ownership boundaries, not long architecture essays. |
| Safety and security constraints | Yes | Include “never,” “ask first,” and “source of truth” rules. |
| Capabilities and tools | Usually no | Better expressed in custom-agent or skill manifests with structured fields. |
| Examples | Yes | Prefer short examples to long pasted docs. |
| Contact and license info | Yes, but uncommon | Useful for reusable templates or published agent artifacts. |
| Versioning and changelogs | Yes, but not standardized | Prefer Git history plus a short “release process” section. |
| Optional metadata (frontmatter) | Emerging, tool-dependent | Safe as an extension if your tools tolerate it; do not depend on it for portability. |
The recurring theme is that AGENTS.md is for behavior and norms, not for capabilities and machinery. If you find yourself reaching for YAML, lists of tool IDs, MCP server addresses, or model configuration, that is a sign you have outgrown plain AGENTS.md and should reach for a structured neighbor.
Structured extensions and hybrid patterns
A major source of confusion in 2026 is that frontmatter, machine-readable fields, capability declarations, and MCP wiring are real and useful — but mostly in neighboring formats, not in core AGENTS.md today.
GitHub custom-agent profiles are Markdown with YAML frontmatter, including name, description, tools, optional mcp-servers, optional model, optional target, and additional metadata. GitHub and OpenAI skills use SKILL.md as Markdown with YAML frontmatter, at minimum name and description, with GitHub also documenting an optional license field. GitHub path-specific instruction files use frontmatter such as applyTo.
By contrast, optional frontmatter for AGENTS.md itself is still proposal-stage rather than a settled universal convention.
The strong interoperability recommendation: if you need structure, use structured neighbors or link to structured documents rather than overloading AGENTS.md. The OpenAPI Specification already standardizes contact, license, version, servers, examples, and reusable schemas for APIs. Schema.org’s SoftwareSourceCode type already standardizes software metadata like codeRepository, programmingLanguage, and runtimePlatform. A practical hybrid is to keep AGENTS.md mostly prose and commands, then link it to openapi.yaml, JSON-LD software metadata, or custom-agent and skill manifests.
A safe hybrid example might look like this:
markdownCopy--- description: Payments subtree guidance tags: [payments, api, pci] --- # AGENTS.md ## Scope Rules for files under `services/payments/`. ## Linked contracts - API contract: `openapi/payments.yaml`- Software metadata: `docs/software-sourcecode.jsonld`## Additional rules - Use the shared validation middleware. - Do not store tokens in code or tests. - Run `make test-payments` before proposing changes.
The important caveat is that the frontmatter above is a tool-dependent extension, not something every AGENTS.md implementation will parse. If you adopt it, make sure the file still reads sensibly when the YAML block is ignored.
Real-world examples worth studying
AGENTS.md is already being used in several distinct styles in the wild: minimal repository guidance, full operational playbooks, domain-specific SDK guidance, multi-agent coordination documents, CI/CD-aware test manifests, and legacy or compatibility specifications. Together they show both the flexibility and the risks of the current ecosystem.
The minimal template. The clearest reference is the official AGENTS project’s own example — setup commands, tests, and style rules, nothing more. This is the design center of the format: short, deterministic, agent-useful guidance rather than encyclopedic documentation.
A full operational playbook. earendil-works/pi includes conversational style rules, type rules, dependency-install safety, parallel-session Git rules, issue and PR behavior, tmux-based testing instructions, changelog conventions, and release policy. It shows that some teams treat AGENTS.md as a full policy surface for autonomous contribution, including release and attribution rules.
A domain-specific SDK guide. firebase/firebase-admin-python frames itself as an SDK-specific guide and includes “critical developer journeys” such as how to add a new API method and how to deprecate a field. This demonstrates a particularly strong use case: AGENTS.md content that captures framework- or SDK-specific contribution idioms too subtle to infer reliably from code alone.
Multi-agent orchestration. leestott/On-Call-Copilot-Multi-Agent documents four specialist agents running concurrently and the orchestrator that merges their outputs. amd/gaia adds a repository-wide coordination file whose job is specifically to mediate multi-agent contribution rules and priority order relative to CLAUDE.md. These examples show some teams using AGENTS.md not merely as repo guidance, but as an agent-team operating model.
CI/CD-integrated. vercel/workflow encodes strict branch rules, extensive build/test/E2E instructions, local-to-CI variable mapping, and explicit references to GitHub Actions test matrices as the source of truth. This is a strong model for repos where agent success is inseparable from passing automation.
Structured internal-agent rosters. pinecone-io/examples defines multiple named specialist agents inline with ad hoc fields like Name, Model, Tools, Description, and Instructions. This is not a canonical AGENTS.md schema, but it is a real-world example of teams using AGENTS.md as a compact registry of specialized agent roles when they have not yet adopted separate .agent.md profile files.
Legacy and compatibility. The 2025 AGENT.md predecessor RFC from Sourcegraph/Amp proposed a singular AGENT.md, hierarchical merging, file references, and migration commands from tool-specific files. In today’s ecosystem, that document is best treated as a historically important precursor — useful for migration strategy and single-source-of-truth thinking, but no longer the canonical filename. The ecosystem has converged on AGENTS.md.
Two more examples deserve mention. The sanity-io/agent-toolkit shows a strong “ask first / never / always” pattern and explicitly routes content operations through MCP tools where possible. Stirling-PDF shows a strong architectural-boundary style — keeping API thin, agents domain-focused, and delegated agents authoritative in their own domain. Those two are particularly useful for writing sections on safety, separation of concerns, and capability routing.
If you maintain a curated set of agent patterns, we keep a running list of these and other references on kingy.ai.
Discovery, precedence, and the lifecycle of an AGENTS.md
The lifecycle of an AGENTS.md is best understood as a loop: an author writes the file, an agent loads it on session start, that file shapes the agent’s behavior across many runs, drift accumulates as the codebase changes, and validation tooling or human review brings it back into alignment. The lifecycle is not a formal standard, but it aligns with Codex’s layered discovery, GitHub’s nearest-file precedence, and CI-oriented validation patterns used by community tooling such as agents-lint.
A few important consequences follow.
Layering is real and matters. With Codex, a global ~/.codex/AGENTS.md provides defaults; the repo root adds project rules; subdirectory files refine those rules for specific subtrees; and AGENTS.override.md wins where it exists. The instinct to put everything in the root file is therefore wrong in repositories with genuinely heterogeneous subtrees — a monorepo with a Python data pipeline and a TypeScript front end is exactly the kind of case where a small root file and two subtree files outperform one giant root file.
Nearest file wins. Copilot’s precedence model means that placing AGENTS.md next to the code it concerns is often more effective than placing it far away with conditional rules.
Adapters are first-class. Claude Code’s import mechanism, Kilo’s AGENT.md fallback, and community symlink patterns all assume the same thing: there will be a single source of truth somewhere, and other tools will adapt.
Best practices for structure, automation, migration, and governance
The emerging research and tooling ecosystem point to one general rule: treat AGENTS.md as a living software artifact, not a one-time prompt dump. Context files dominate the configuration landscape in real repositories (arXiv 2602.14690), but their usefulness depends on signal density, freshness, and the absence of conflicting instructions across neighboring files. Context drift is a real operational problem, and the more tools your repository serves, the more valuable a clean single-source-of-truth strategy becomes.
Structure and naming
Use one canonical root AGENTS.md unless you genuinely need subtree-specific rules. Prefer uppercase AGENTS.md, not lowercase variants. Add nested files only where a subtree has materially different conventions or commands. Keep the root file focused on universal repository behavior and let nested files add only local deltas. Codex’s layered merge model, GitHub’s nearest-file precedence, Kilo’s subdirectory loading, and the draft AGENTS guidance all support this progressive-disclosure approach.
A strong authoring outline is:
textCopy# AGENTS.md ## Overview ## Commands ## Conventions ## Boundaries ## Quality gates ## Ask first ## Never ## References
That outline is not mandated by the standard, but it maps cleanly to what agents actually need and to the recurring structure found in real repositories.
Security, safety, and privacy
Do not put secrets, tokens, customer data, or hidden operational assumptions into AGENTS.md. Several real-world examples explicitly forbid printing secrets or hardcoding API tokens, and GitHub’s structured custom-agent configuration expects secrets to be supplied through repository or organization secret mechanisms rather than embedded in Markdown. Because tools like Codex, Copilot, Kilo, and Claude-adapter workflows load these context files into agent runs, anything sensitive in the file is effectively agent-visible context.
For safety, explicitly separate “always,” “ask first,” and “never” categories. The Sanity example does this well. pi and gaia add another important lesson for multi-agent or parallel-session workflows: document Git-safety rules, branch safety, force-push prohibitions, and staging discipline explicitly. Autonomous agents do better when non-negotiable risks are written as direct commands rather than implied socially.
Maintainability and validation
The empirical literature is now giving a clear warning: longer and more detailed is not automatically better. One 2026 study (arXiv 2601.20404) found efficiency gains from AGENTS.md — lower median runtime and lower output-token consumption with comparable task-completion behavior. A separate 2026 study (arXiv 2602.11988) found that context files often increase exploration, testing, and cost by more than 20%, that LLM-generated context files can reduce performance, and that developer-written files offer only small or inconsistent gains unless they provide concise, genuinely novel repository knowledge.
The synthesis is straightforward: human-curated, minimal, high-signal files are helpful. Bloated or auto-generated files are often counterproductive. The right response is not “never use AGENTS.md” but rather keep it sparse, exact, and obviously useful. Commands should be copy-pasteable. Paths should exist. Referenced files should still be present. Avoid repeating what a README or tool can already infer unless the extra context materially changes behavior.
This is where validation tooling matters. There is no canonical validator in the official AGENTS project yet — there is an open issue requesting one — but community tools already exist. agents-lint checks for stale paths, missing scripts, stale dependencies, framework staleness, cross-file inconsistency, and memory-file issues, and includes a GitHub Actions example plus an init command for generating a starter AGENTS.md. dotagent goes further on interoperability by importing rules from many tool-specific formats and exporting them from a unified .agent/ directory. cclint demonstrates another strategy in practice by symlinking several tool-specific files back to one shared AGENTS.md source.
A good CI pattern is therefore:
yamlCopyname:agents-linton:push:paths:-AGENTS.md-package.jsonschedule:-cron:"0 9 * * 1"jobs:lint:runs-on:ubuntu-lateststeps:-uses:actions/checkout@v4-run:npxagents-lint--max-warnings0
The key idea is the weekly run: context files can rot even when they themselves do not change. A script renamed in package.json, a directory deleted, a framework upgraded, a deprecation completed — all of these silently invalidate parts of an otherwise untouched AGENTS.md.
Migration, interoperability, and versioning
The best migration strategy is baseline plus adapters. Make root AGENTS.md your authoritative shared core. For Claude Code, create a CLAUDE.md that imports @AGENTS.md, or symlink CLAUDE.md to AGENTS.md if you do not need Claude-specific additions. The cclint repository demonstrates this philosophy more broadly by symlinking multiple tool-specific config files to AGENTS.md. Kilo’s documentation also provides a concrete migration path from its deprecated memory-bank feature to AGENTS.md. The older AGENT.md RFC is useful as a historical precedent for consolidation and symlink-based compatibility, but it should now be treated as a legacy precursor rather than the naming target for new repositories.
For versioning, avoid inventing a fake semantic-version requirement for AGENTS.md unless your tooling depends on it. The core convention does not standardize version fields. A better practice is to let Git history be authoritative and add a short “compatibility” or “last reviewed” note if needed. If a repository genuinely needs release-process instructions or changelog semantics, keep them narrow and operational, as pi does. For reusable structured artifacts, use formats that already define metadata: GitHub custom agents and skills support frontmatter; OpenAPI standardizes version, contact, and license.
A practical adapter stack looks like this:
- Root
AGENTS.md→ authoritative source of behavior, conventions, and commands. CLAUDE.md→ imports or symlinks toAGENTS.md, plus Claude-specific overrides if needed.GEMINI.md→ adapter for Gemini-based workflows where required.- Copilot instructions → reference or align with root
AGENTS.md. - Skills → reusable workflows the team or agents invoke repeatedly.
.agent.mdprofiles → specialized agents with tools and MCP wiring.- CI validation → drift and freshness checks running on every push and weekly.
That arrangement reflects a broad pattern observed in the ecosystem and in empirical studies of cross-file references: teams increasingly use multiple agent-facing artifacts, and the highest-leverage design is to make one core file authoritative while letting other artifacts adapt to it.
What the early research actually says
The evidence on AGENTS.md effectiveness is mixed but useful, and pretending otherwise would be dishonest.
One controlled 2026 study (On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents, arXiv 2601.20404) examined Codex on 124 pull requests and found that the presence of an AGENTS.md file was associated with lower median runtime and lower output-token consumption, while preserving comparable task-completion behavior. In other words, the file did not make Codex meaningfully better at finishing tasks, but it did make Codex more efficient at completing tasks it was going to complete anyway. For teams paying per-token or constrained by latency, that is a real and measurable win.
A second 2026 study (Evaluating AGENTS.md, arXiv 2602.11988), across multiple agents and models, was more cautionary. It found that context files often increase exploration, testing, and cost by more than 20%; that LLM-generated context files can reduce performance; and that developer-written files offer only small or inconsistent gains unless they provide concise, genuinely novel repository knowledge.
The honest synthesis is not “use AGENTS.md” or “don’t.” It is:
- A short, human-written
AGENTS.mdthat captures genuinely non-obvious repository knowledge tends to help. - A long, autogenerated, or redundant
AGENTS.mdtends to hurt — it expands exploration, multiplies token cost, and sometimes degrades task completion. - Measurement is local. What works in one repository may not work in another. The right operating posture is to add a minimal file, instrument your agent runs, and iterate.
That nuance is genuinely new information for most teams adopting AGENTS.md for the first time. If you have ever copy-pasted an entire onboarding wiki into your AGENTS.md, this is your reason to stop.
For more context on how to measure and improve agent behavior in your own workflows, see our notes at kingy.ai.
Common pitfalls and anti-patterns
A handful of failure modes show up repeatedly in real repositories.
The dumping ground. Treating AGENTS.md as a place to paste everything you have ever told an agent. The mixed research findings strongly suggest verbose, redundant, or autogenerated context can worsen cost and sometimes hurt task success. The fix is editorial: every sentence in AGENTS.md should pay rent.
Cross-file duplication and drift. Duplicating similar instructions independently across AGENTS.md, CLAUDE.md, Copilot instructions, and skills, where each copy slowly diverges from the others. The literature found hundreds of cross-file references in real repositories and a clear need for hierarchy. The fix is the adapter pattern: one source of truth, with imports or symlinks elsewhere.
Structured capabilities in prose. Trying to encode tool access, MCP configuration, model selection, or capability declarations in prose paragraphs of AGENTS.md. A skill manifest or .agent.md profile is the right home for those. The fix is to graduate structured content to structured neighbors.
Stale references. Renamed scripts, deleted directories, deprecated framework patterns, dead links. These are exactly the problems validator tools like agents-lint now target. The fix is automation: CI on every push, scheduled weekly checks, owners assigned to each section.
Treating frontmatter as standard. Optional AGENTS.md frontmatter is still proposal-stage. Files that depend on it for portability will break in tools that ignore it. The fix is to make sure your AGENTS.md still reads sensibly if the YAML block is stripped.
Assuming one tool’s behavior is universal. Codex layering, Copilot nearest-file precedence, Kilo’s write protection, and Claude’s import model are all real, and they are not the same behavior expressed four different ways. The fix is to label features as “core convention,” “widely supported,” or “tool-specific” in your own internal documentation, and to write portable files that do not depend on any single tool’s idiosyncrasies.
A recommended outline for a comprehensive internal guide
If you are writing a long-form internal guide for your own organization — perhaps because you are rolling out AGENTS.md across many repositories — a defensible chapter order looks like this:
| Chapter | What to cover |
|---|---|
| Introduction | Define AGENTS.md, scope to coding-agent repositories, explain why a vendor-neutral baseline matters. |
| Why repository context files exist | Contrast ephemeral prompts with version-controlled context. |
| The ecosystem map | Compare AGENTS.md, CLAUDE.md, GEMINI.md, Copilot instructions, .agent.md, SKILL.md. |
| Discovery and precedence | Root vs nested files, load order, nearest-file precedence, adapters and imports. |
Writing the first AGENTS.md | Minimal template, section semantics, exact commands, examples of “ask first” and “never.” |
| Advanced authoring patterns | Nested subtree files, references to companion docs, compatibility notes. |
| Structured extensions | When to use skills, custom agents, path-scoped rules, MCP configuration, frontmatter. |
| Interoperability | Single-source-of-truth patterns, symlinks/imports, linking to OpenAPI and JSON-LD metadata. |
| Security and privacy | Secret handling, sensitive data, risky Git operations, delegated-agent safety. |
| Validation and CI | Drift detection, stale path checks, script validation, scheduled linting. |
| Empirical evidence | What the research says about efficiency, cost, and task success; interpretation and caveats. |
| Case studies | Minimal, full-featured, SDK-specific, multi-agent, CI/CD-centered, legacy migration. |
| Migration and governance | Moving from legacy files, ownership, review cadence, changelog policy, org-level rollout. |
| Appendix | Field catalog, snippets, anti-pattern checklist, evaluation rubric. |
A helpful editorial principle is to separate normative advice from ecosystem description. Readers need to know both what tools currently do and what you recommend they should do. That separation will make the guide age better as tool-specific behaviors continue to shift.
Open questions and limitations
Honest as the convention is settling, several pieces of the picture are still moving.
The strongest limitation is that core AGENTS.md remains intentionally lightweight, while structured extensions are still in flux. Optional frontmatter for AGENTS.md is still proposal-stage. The agents/rules/ idea is active rather than settled. Broader .agent/ directory proposals remain emergent. Treat these as forward-looking extensions, not stable universal rules.
Tool behavior is implementation-specific. Codex’s merge chain, Copilot’s nearest-file precedence, Kilo’s write protection and AGENT.md fallback, and Claude’s import model are all real, but they are not the same behavior expressed four ways. Any definitive guide — including this one — should label features carefully.
The empirical evidence base is early and partially contradictory. Current studies already show both upside and downside: better efficiency in one controlled setup, higher cost and weak or negative performance gains in another. The safest conclusion is not to universalize either outcome. Recommend measurement within each repository: small files, explicit review ownership, and CI validation first; then evaluate whether the file is reducing search thrash, token usage, and failed runs in your actual workflow.
If the convention continues to mature the way 2025 and 2026 suggest, the practical center of gravity will probably stay close to where it is today: a short, freeform Markdown file at the repository root, supported by structured neighbors for capabilities, and validated in CI to keep it honest. For ongoing analysis of how this space evolves, we maintain a running set of notes on kingy.ai.
A short closing summary
If you remember nothing else from this guide, remember this:
AGENTS.mdis a version-controlled, repository-local Markdown file that tells coding agents how your codebase actually works. The canonical name is uppercase, and the canonical location is the repository root.- The format is intentionally freeform. The durable sections are project overview, exact commands, conventions, boundaries, safety rules, and workflow guidance.
- Codex layers files top-down with
AGENTS.override.mdtaking precedence. Copilot uses nearest-file precedence. Claude does not readAGENTS.mddirectly but can import it intoCLAUDE.md. Kilo loads root and subdirectory files with subdirectories overriding. Use one root file plus subtree files only where necessary. - Structured content — tool access, MCP servers, model selection — belongs in
SKILL.md,.agent.md, or.instructions.md, not in plainAGENTS.md. - Use the adapter pattern: one authoritative
AGENTS.md, withCLAUDE.md,GEMINI.md, and Copilot instructions importing or symlinking back to it. - Never put secrets, tokens, or customer data in
AGENTS.md. Anything in the file is agent-visible context. - Validate the file in CI. Stale paths and renamed scripts are the most common failure mode.
- The research is mixed. Short, human-written, high-signal files tend to help efficiency. Long, autogenerated, or redundant files often hurt. Measure in your own repository.
Used well, AGENTS.md is one of the lowest-effort, highest-leverage improvements you can make to working with coding agents. Used poorly, it is a quiet tax on every agent run. The difference is editorial discipline, not tooling — which is good news, because editorial discipline is something every team can practice without waiting for a vendor to ship a feature.
For more on this theme — agent workflows, tooling patterns, and the practical realities of working with AI coding tools day to day — see kingy.ai.
Want your AI product explained to a large AI-native audience?
Kingy AI helps AI companies turn complex products into clear, useful YouTube videos that drive awareness, product understanding, demos, clicks, and search visibility.
