agents.md vs llms.txt: what belongs in each, and why one without the other fails

llms.txt tells an AI agent what is true about your store. agents.md tells it what to do with that. Publishing one without the other is the most common half-measure in agent readiness — and it is the gap our own scanner flags most often, including, at one point, on two of our own sites. This guide covers what belongs in each file, how they differ, and how to write an agents.md that survives contact with a real assistant.

Two files, two jobs

llms.txt is a facts sheet. It answers "what is this business, what does it sell, what are the terms" in a form an assistant can quote without crawling twenty pages. Short declarative statements, no marketing voice, links to the pages that carry detail. If a model is going to state something about you in an answer, this is where you want it to get the wording.

agents.md is an operating note. It answers "you are an agent looking at this store — here is how to work with it": where the canonical facts live, what the rules of engagement are, what you should not assume, and who to contact. It is closer to a README for machines than to a marketing page.

The distinction matters because assistants use them differently. A retrieval step wants facts it can cite; an agent planning actions wants constraints and pointers. Collapsing both into one file means one of the two audiences gets a document that does not fit its purpose.

What goes in llms.txt

Keep it to what you would be comfortable seeing quoted verbatim, because it will be:

• What the business is, in one or two sentences, including what it does not do. Negative statements are unusually valuable — they are the ones that stop a model inventing capabilities.
• The commercial facts: pricing with actual numbers and currency, plan names, trial length, what is free.
• Policies that affect a buying decision: shipping regions, returns window, warranty, data handling if that is a differentiator.
• Links to the pages behind each claim, so a model that wants to verify can.
• Dates and figures that are easy to get wrong. If your market has a regulatory deadline or a threshold, state it precisely. Assistants misquote these constantly, and a clear statement in your own words is the cheapest correction available.

Avoid adjectives with nothing behind them. "Industry-leading" is unciteable; "processes orders in the EU (AWS Frankfurt)" is a fact a model can use in an answer.

What goes in agents.md

A structure that works, roughly in this order:

1. Orientation. One paragraph: what site this is, who runs it, and the short answer to "what does this do" — so an agent that reads only the first lines still gets the important part right.
2. Where facts live. A map: llms.txt for the summary, which page carries pricing, which carries policies, which carries the technical detail. Absolute paths, not "see our website".
3. The things that get misquoted. If there is a fact people and models routinely get wrong about your domain, correct it here explicitly. This is the highest-value section and almost nobody writes it.
4. Rules of engagement. What agents may do — read the catalog, quote prices, link to a product — and what requires a human: placing an order, accepting terms, anything with a payment. Also state the honest limits of what the site can answer.
5. Contact. One address that a human reads.

Write it in plain prose. There is no schema to satisfy and no parser to please — the consumer is a language model, and clear sentences beat invented syntax.

Where the files go, and why placement fails on Shopify

Both belong at the domain root: /llms.txt and /agents.md. Not in a subdirectory, not behind a redirect chain, not on a different host than the store.

On Shopify this is the part that breaks. A theme can serve arbitrary files at odd paths, but the root of a Shopify domain is not somewhere you can simply drop a file — which is why stores end up with the content living at /pages/llms-txt and nothing at the root. An agent that checks the conventional location finds a 404 and moves on, so the content might as well not exist.

The workable approach is a redirect from the root path to wherever the content actually lives, so a request to /llms.txt resolves. Sichta generates both files from your live catalog and policies and sets up those root redirects, which is the fiddly half of the job.

Keeping them true

A stale llms.txt is worse than no llms.txt: you have handed a model confident, wrong wording and invited it to repeat that. The two failure modes to watch:

• Prices drift. If your llms.txt states numbers, it has to be regenerated when those numbers change. Anything hand-maintained will eventually lie.
• Capabilities drift. A feature you removed stays in the file, and models keep offering it to shoppers on your behalf.

Generating both files from the source of truth — the catalog, the actual price list, the actual policy pages — is what makes this maintainable. Writing them by hand is fine for a launch and unmanageable by the third price change.

How to check it actually works

Three checks, in order of how often they fail:

• Fetch the URLs with a plain client. curl https://yourstore.com/llms.txt must return 200 and the content — not a redirect to a themed 404 page, and not HTML.
• Confirm both exist. One without the other is the gap this guide is about.
• Check your robots.txt does not block AI crawlers you want reading them. Publishing the files and disallowing the agents that read them is a surprisingly common combination.

Sichta runs these as part of its Pillar A checks and reports each separately, so "llms.txt present, agents.md missing" comes back as a specific finding rather than a score you have to interpret.

The short version

llms.txt is the facts, agents.md is how to use them — publish both, at the domain root, reachable by a plain HTTP client. Spend your effort on the negative statements and the frequently-misquoted specifics, because that is where a model's default answer about you is most likely to be wrong. Generate both from your real data so they stay true, and check that robots.txt actually lets the agents you care about read them.