AGENTS.md for teams that don't write code

Strip a well-written AGENTS.md down to its structure and there is nothing engineering-specific left in it. Which is awkward, because every guide to the format is written for engineers — and the teams now running agents without any equivalent of this file are mostly not engineering teams.

The format

What AGENTS.md is, in one minute

A Markdown file at the root of a project that tells agents what they need in order to work on it: how to set up, what the conventions are, what has to pass, and what not to touch.

The format's own framing is the clearest available — think of AGENTS.md as a README for agents. The README explains the project to humans and is full of things an agent doesn't need: badges, contribution etiquette, a history section. AGENTS.md is the operational half, addressed to the machine.

There is no schema and no required fields. The specification is explicit that it is just standard Markdown and that you can use any headings you like. Where several exist in a tree, agents read the nearest one, so the closest file takes precedence — a detail that matters more than it sounds, and one that comes back in the security piece.

Adoption

Why it caught on

It solved a fragmentation problem rather than a capability one. Cursor read its own rules format. Claude Code read CLAUDE.md. Everything else read whatever its vendor had decided on. Teams using more than one tool maintained more than one file saying the same thing, and the copies drifted.

One predictable filename in one predictable place fixed that, and adoption followed: the format is now in over 60,000 open-source projects, and read natively by more than twenty agent tools — including OpenAI Codex, Cursor, GitHub Copilot's coding agent, Gemini CLI, Google Jules, Devin, Zed, Warp, VS Code, Windsurf, JetBrains Junie and Aider. It is stewarded by the Agentic AI Foundation under the Linux Foundation, which is what moved it from convention to something closer to infrastructure.

All of which is context for the argument that follows, rather than the argument itself.

The comparison

AGENTS.md vs CLAUDE.md vs Cursor rules vs SKILL.md

Four things, routinely confused, doing different jobs.

The distinction people get wrong most often is SKILL.md, because it looks like a sibling and isn't. A skill describes a procedure, not a workspace, and its body loads only when the skill is actually used — which is why long reference material can live in one cheaply. Claude Code's own guidance is that you should reach for a skill precisely when a section of CLAUDE.md has grown into a procedure rather than a fact. That is a useful test in either direction: facts about the workspace belong in AGENTS.md, procedures belong in a skill.

The rule the ecosystem has settled on: maintain AGENTS.md as the single source, and add a tool-specific file only for behaviour that tool alone supports. Duplicating content across two files reintroduces the exact drift the format was created to end.

The argument

The pattern, translated off the engineering team

Here is the observation this whole piece rests on. Take a well-written AGENTS.md and remove the specific commands. What remains is four questions:

1. What is this thing, and where does the material live?
2. How is work done here, in practice?
3. What has to pass before it's finished?
4. What must not be touched?

None of those are engineering questions. They are what you would answer for a new contractor on day one, and every function has answers to them.

The reason this matters now: marketing teams, revenue operations teams and support teams are all running agents, mostly without any equivalent of this file. The instructions live in a system prompt someone configured in March, or in a shared doc, or nowhere. The engineering discipline of writing down how work is done in a place the machine reads has not crossed over — and the functions that skipped it are the ones with the least ability to spot when an agent has quietly gone wrong.

Worked example

What a marketing team's version looks like

A campaign workspace, complete and realistic. Note how much of it is boundaries and checks rather than description.

# Campaign workspace — Q4 retail
Owner: Ana K., brand lead · Last reviewed: 2026-08-12

## Where things are
- Brand rules: `/context/brand.md` — read before writing anything
- Approved claims: `/context/claims.md`
- Asset library: `/assets/` (final only — `/assets/wip/` is not approved)
- Channel specs: `/context/channel-specs.md`

## How work is done here
- Draft in the campaign doc, never directly in the scheduler
- One variant per channel, not one variant reformatted
- Every asset filename: `q4-[channel]-[asset]-v[n]`

## Before anything is finished
- Every claim appears in `/context/claims.md`, word for word
- Word choices checked against the brand.md list
- A named human approver is on the ticket

## Do not
- Do not write pricing. Pricing comes from commercial.
- Do not edit anything in `/legal/` or `/assets/final/`
- Do not publish or schedule. Drafts only.
- Do not invent statistics, even as placeholders

## Escalate
- Anything a journalist or analyst asks → comms
- Anything about an active incident → comms
- Anything naming a competitor → legal

The section doing the most work is Do not. It is also the section that never appears in a first draft, because writing down what an agent shouldn't do requires imagining it doing the thing, and that is an uncomfortable exercise most teams skip.

What an ops team's version looks like

Shorter, because the pattern is familiar now. A revenue operations workspace:

# RevOps workspace
Owner: Piotr W., revenue ops · Last reviewed: 2026-08-12

## Where things are
- Field definitions: `/context/crm-schema.md`
- Segment definitions: `/context/segments.md`
- Reporting definitions: `/context/metrics.md` — one definition per metric

## How work is done here
- Every number cites the report it came from
- Date ranges stated explicitly, never "last quarter"
- Segment names exactly as they appear in `/context/segments.md`

## Before anything is finished
- Totals reconcile against the source report
- Any metric used appears in `/context/metrics.md`

## Do not
- Do not write to the CRM. Read-only.
- Do not blend data across two reporting periods in one figure
- Do not estimate a number that is unavailable. Say it is unavailable.

That last line is the most valuable one in either file. An agent with no instruction about missing data will produce a plausible figure, and a plausible figure in a revenue report is considerably worse than a gap.

The tool

Build yours

Seven inputs, producing a file in the structure above — which you should then cut down. The next section explains why cutting matters more than filling in.

The practical blocker

Where the file goes when you don't have a repo

The specification assumes a project root. Marketing teams don't have one, and this is the point at which most non-engineering attempts stall.

Three workable answers, depending on how your agents are actually invoked:

• Your agent platform's project or workspace settings. Most tools now have somewhere to attach persistent context to a project. Paste the file there. Least friction, and the drawback is real: no version history, so nobody can see what changed.
• A shared drive folder that the workspace maps to. Put AGENTS.md at the top of the folder your agents work in, alongside the material. This mirrors the original pattern most closely and it survives people leaving.
• A repository, even without code. A repo containing four Markdown files and nothing else is a perfectly reasonable thing to own. You get history, diffs, review and change alerts — which are, per the security piece, most of the controls that matter. The objection is always that the team isn't technical; in practice one person sets it up and everyone else edits through a web interface.

Whichever you pick, pick one. The costliest failure is the file that exists in three places with three edit dates — precisely the fragmentation AGENTS.md was invented to end, reintroduced at the organisational layer instead of the tooling layer.

The evidence

The mistake almost everyone makes

They fill it in. All of it, thoroughly, as though completeness were the goal.

In February 2026 researchers at ETH Zurich published the first rigorous evaluation of whether these files help. They tested several coding agents and models across established benchmarks plus a new set of issues drawn from repositories where developers had written and committed their own context files, comparing no file, a machine-generated file, and a developer-written one. The finding, from the abstract: providing context files does not generally improve task success rates, while increasing inference cost by over 20% on average — and that held for both LLM-generated and developer-committed files.

The interesting part is why, because it is not what people assume. The paper is explicit that the absence of improvements when using context files is not due to a lack of instruction-following capabilities. The agents read the file and did what it said. They ran more tests and explored more broadly — which is where the extra cost came from.

Mention something and the agent will go and use it, whether or not the situation calls for it. Which inverts the drafting instinct completely. Every line in the file is not a helpful hint; it is a lever the agent will pull.

So start with the boundaries and the done-criteria, which are the two sections where being explicit is unambiguously worth the tokens. Add nothing else until an agent has actually got something wrong — which is also what the specification's own guidance recommends. A short file that is entirely load-bearing beats a complete one every time.

Run whatever you write through the context file checker before you deploy it. The check that catches most first drafts is the vague-directive one: "be careful", "use your best judgement", "where appropriate". Unenforceable by a human, and resolved by an agent in whatever direction the rest of the prompt happens to push.

The cluster

How it relates to llms.txt and brand.md

Three files, one sentence each, and they are not interchangeable.

• AGENTS.md governs how work gets done inside a workspace you control. Read by agents you operate. Verifiable.
• brand.md governs what the output is allowed to sound like and claim. Also read by agents you operate.
• llms.txt points outside agents at your public content — and, per the log data, is read by far fewer of them than anyone selling it suggests.

Most teams start with the third because it is the one with a marketing story attached. The order that actually pays is the reverse: the two files read by systems you operate, where you can check whether the thing worked, before the one read by systems you don't.