AGENTS.md is a plain Markdown file at the root of a repository that tells a coding agent how to work in it. For a support centre, that means tone, what it may do without asking, where facts live, and what always waits for a human. Get those right and the rest is detail.
This page is one part of a larger guide. For the whole subject in one place, see running support with a coding agent.
What is AGENTS.md, actually?
A README written for an agent instead of a person: no build badges, no install steps aimed at a human, just the operating instructions a coding agent needs before it touches anything. It sits at the repository root because that is the first file most agents read, and stays in plain Markdown because any agent, from any vendor, can read it without a special format or plugin. That was deliberate on the format's part:
Rather than introducing another proprietary file, we chose a name and format that could work for anyone.
The AGENTS.md format
For a support centre specifically, that file does a different job than in an ordinary codebase. A normal AGENTS.md tells an agent how to run tests and where the source lives. A support centre's tells it how to speak on behalf of a business to a customer, a narrower and far more consequential set of instructions, deserving to be written that way rather than bolted onto a generic template.
What tone and voice rules actually belong in it?
Concrete examples, not adjectives. "Friendly and professional" tells an agent nothing it can act on. A banned phrase, its replacement, and a worked before-and-after sentence tell it everything.
Say plainly which phrases are banned and why: "we apologise for the inconvenience" reads as filler, "fixed a bug" implies the product was broken, "as per our policy" is corporate rather than direct. Then give the replacements: a good acknowledgment, a good decline, a genuine correction for when the customer could actually see the problem. An agent asked to be friendly generates something generic. Handed five real example sentences, it generates something in your voice.
What is the single most important section?
What the agent may do without asking, set against what it must always leave for a human. This decides whether the file is a safety mechanism or a liability, and deserves more space than every other section combined.
The safe default is narrow: an agent may draft, triage, tag, search past replies for consistency, and flag what it is unsure about. It may not publish anything that reaches a customer, promise a date, offer a refund, or say anything about a different customer's report, under any framing. Publishing is the line, and it should be a hard rule rather than a judgement call, which is exactly what erodes the first time an agent is confident and wrong.
Where do things actually live, and why does it matter that the file says so?
An agent that has to guess a directory structure will guess wrong occasionally, and a wrong guess means a reply drafted from the wrong file or filed in the wrong place. Naming the exact paths removes the guess: which directory holds incoming requests, which holds drafted replies, the naming convention, and where the facts it may cite live. None of this is exciting to write. All of it is the difference between an agent that works reliably and one that is right most of the time.
How should it handle what it does not know?
Say so and stop. That is the entire instruction, worth stating explicitly rather than assumed obvious, because the failure mode without it is not silence, it is a confident guess dressed up as an answer. An agent that cannot find a fact in the sanctioned source should say "I could not confirm this" and hand the gap to a person.
What facts may it actually rely on?
Only what is written down somewhere the agent has been told to trust, nowhere else. A number that is not in that source does not get published, regardless of how confident or reasonable it sounds. This is the rule that stops an agent inventing a shipped date, a version number, or a price it half remembers, and it only works if the file names the exact source rather than gesturing at "the docs".
One payment, no subscription, unlimited products.
What should never appear in a reply, no matter who drafted it?
Three categories, worth listing rather than trusting an agent to infer them from tone rules alone: a promised date for anything not yet shipped, a refund or compensation commitment, and any detail about another customer's report, account, or situation. All three sound like ordinary helpfulness in the moment and become a real problem once they turn out wrong, or were never authorised at all.
A worked example
A starting point, not a template to fill in blindly. The value is in being specific to a real product and voice, so adapt every line rather than keeping the shape and swapping only the name.
# AGENTS.md for Support
This repository holds the support centre for Acme Notes, a
note-taking app. Read this file before touching anything.
## Voice
- Warm, direct, no corporate filler.
- Say "you" and "we", never "the user" or "the team".
- Never "we apologise for the inconvenience". Instead,
name what actually happened.
- Never "fixed a bug where...". Instead, "improved how
X works", or if the customer could see it: "if you
noticed X, this update resolves it."
- Never "as per our policy". State the reason plainly.
## What you may do without asking
- Read and triage new requests in data/requests/.
- Draft a reply as a new file in data/drafts/.
- Tag a request with its category and severity.
- Search past replies for a matching answer already given.
- Flag anything you are unsure about instead of guessing.
## What always needs a human
- Publishing any reply. Drafts wait for approval, always.
- Any date, even a vague one ("soon", "next release").
- Any refund, credit, or compensation of any kind.
- Anything mentioning another customer's request or account.
- Declining a request. Draft the decline, do not send it.
## Where things live
- data/requests/ bug reports and feature asks, one file
per request, named YYYY-MM-DD-slug.md
- data/drafts/ replies waiting for approval
- data/published/ replies that have gone out
- data/facts.md the only source of prices, versions,
and shipped-feature claims
## Facts
Only cite what is written in data/facts.md. If it is not
there, say so in the draft and leave it for a human.
## When you do not know
Say "I could not confirm this" and stop. A wrong guess
costs more than an honest gap.Is that enough to make a reply safe?
No, and the file should say so. An AGENTS.md is instructions, not a guarantee: it narrows what the agent will attempt and how it phrases what it does attempt, but instructions can be followed imperfectly, and review before publishing is what actually catches what the file did not prevent. Letting an agent answer without letting it invent covers the harder half: what happens when a plausible answer is also a wrong one. Treat the file as the first layer of a system that still needs a second.
Frequently asked questions
Where should AGENTS.md live?
At the repository root, where most coding agents look for it first, before any other configuration or documentation file.
Does AGENTS.md replace human review of replies?
No. It shapes what an agent attempts and how it phrases a draft, but review before publishing is what actually catches a bad reply, and the file should say so rather than imply review is optional.
What is the single most important section to get right?
What the agent may do without asking, set clearly against what must always go to a human. Publishing, dates, refunds, and anything about another customer belong on the human side, without exception.
Should the file include example replies, or just rules?
Both. Examples are what actually change the output: "be direct" is an adjective an agent cannot act on, but a real before-and-after sentence in the house voice is something it can copy the shape of.
What happens if a fact the agent needs is not in the sanctioned source?
The instruction should be to say so and stop, not infer a reasonable-sounding answer from context. A gap handed to a human costs far less than a wrong number published with confidence.