# AGENTS.md for Teams That Don't Write Code: A Template

> Canonical: https://auxfirst.com/news/agents-md-for-non-engineering-teams.html
> Markdown representation of this article, for agents and LLM crawlers.

AGENTS.md is in 60,000+ repositories and read natively by 20+ agent tools. What the pattern looks like when the team running the agents isn't an engineering team.

By Emil Krzemiński, founder of auxfirst. Published 12 August 2026.

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.

## 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. 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.

## 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. 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.

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

| File | Scope | Read by | Use it when |
|---|---|---|---|
| AGENTS.md | A project or workspace | Broadest support — 20+ tools | Default. Make this the canonical one. |
| CLAUDE.md | A project, Claude-specific | Claude Code | You need behaviour only that tool supports. |
| .cursor/rules | A project, Cursor-specific | Cursor | You want rules scoped by file glob. Cursor also reads AGENTS.md. |
| SKILL.md | A capability, not a project | Tools supporting the skills pattern | Packaging a reusable procedure rather than describing a workspace. |

Cursor's current documentation describes project rules as `.mdc` files in a `.cursor/rules` directory, carrying frontmatter that scopes them by glob; the older single-file `.cursorrules` does not appear in it.

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. Claude Code's own guidance is to reach for a skill "when a section of CLAUDE.md has grown into a procedure rather than a fact". 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.

## The pattern, translated off the engineering team

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.

| In an engineering AGENTS.md | The general form |
|---|---|
| Setup commands, dependencies | Where the material lives |
| Code style, conventions | How work is done here |
| Test suite, lint, build | What must pass before done |
| Protected paths, do-not-edit | What must not be touched |
| PR and review process | Who approves, and when |

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.

## What a marketing team's version looks like

```
# 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)

## How work is done here
- Draft in the campaign doc, never directly in the scheduler
- One variant per channel, not one variant reformatted

## Before anything is finished
- Every claim appears in `/context/claims.md`, word for word
- 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 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.

## What an ops team's version looks like

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

## Where things are
- Field definitions: `/context/crm-schema.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"

## 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. A plausible figure in a revenue report is considerably worse than a gap.

## 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 where most non-engineering attempts stall. Three workable answers:

- **Your agent platform's project settings.** Least friction; no version history, so nobody can see what changed.
- **A shared drive folder the workspace maps to.** Mirrors the original pattern most closely and survives people leaving.
- **A repository, even without code.** History, diffs, review and change alerts. One person sets it up; everyone else edits through a web interface.

Whichever you pick, pick *one*.

## The mistake almost everyone makes

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

In February 2026 researchers at ETH Zurich published the first rigorous evaluation of whether these files help. The finding, from the abstract: providing context files "does not generally improve task success rates, while increasing inference cost by over 20% on average" — holding for both LLM-generated and developer-committed files.

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 cost came from.

| Tool invocations per task | Named in the file | Not mentioned |
|---|---|---|
| `uv` | 1.6× per task | fewer than 0.01 |
| Repository-specific tools | 2.5× per task | fewer than 0.05 |

Mention something and the agent will use it, whether or not the situation calls for it.

> If an instruction can live somewhere else, it must not live here.

**The complication worth knowing.** A study published two weeks earlier reached the opposite conclusion on efficiency: the presence of an AGENTS.md was associated with 28.6% lower median runtime and 16.6% lower output token consumption, with comparable task completion. Both stand — one counted the cost of reading the file, the other the savings from having read it. Anyone citing either paper as settled is citing half of it.

Start with the boundaries and the done-criteria. Add nothing else until an agent has actually got something wrong.

## How it relates to llms.txt and brand.md

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

The order that pays is the reverse of the usual one: the two files read by systems you operate, before the one read by systems you don't.

## Read next

- [brand.md — brand guidelines agents can read](https://auxfirst.com/news/brand-md-context-file.html)
- [Prompt injection in .md context files](https://auxfirst.com/news/markdown-context-file-security.html)
- [llms.txt: what 137,000 sites' server logs actually show](https://auxfirst.com/news/llms-txt-evidence.html)
- [MD files explained — the complete .md file format guide](https://auxfirst.com/news/md-file-markdown-guide.html)
- [The context file checker](https://auxfirst.com/tools/context-file-checker.html)

## Sources

- agents.md — the specification, adoption count and supported-tool list, as of August 2026 — https://agents.md/
- Gloaguen, Mündler, Müller, Raychev and Vechev, "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?", arXiv:2602.11988, February 2026 (revised June 2026) — https://arxiv.org/abs/2602.11988
- Lulla, Mohsenimofidi, Galster, Zhang, Baltes and Treude, "On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents", arXiv:2601.20404, January 2026 — https://arxiv.org/abs/2601.20404
- Cursor — project rules documentation — https://cursor.com/docs/context/rules
- Claude Code — skills documentation — https://code.claude.com/docs/en/skills

Method: every figure and quotation was taken from the primary source, not from secondary coverage. Where two studies disagree we have said so rather than picking the convenient one.

---

Emil Krzemiński is the founder of auxfirst (https://auxfirst.com/), the agentic experience design agency.