What should an agents.md file include?

At minimum: a clear identity (what the store is and who it's for), what you sell (categories), your most popular and featured products, why buy from you, social proof (ratings), policies (shipping and returns), and the UCP/MCP transaction rails so an agent can check out. Stronger files add sizing/fit guidance, locations, markets, and reference pages. Leave out anything private, like contact email or phone, since the file is publicly cached.

How long should agents.md be?

Long enough to cover the sections above, short enough that an agent can read it in one fetch without burning its context budget. Be concise: one line per category and product, summarized policies, and link out to deep pages rather than pasting everything inline. A few KB of focused content beats a sprawling dump.

What makes an agents.md bad?

The most common failure is the generic Shopify default: it exists and is valid, but it describes the platform, not your brand, and routes agents to shop.app instead of you. Other failures: stale content that no longer matches your catalog, private data leaking into a public file, discount codes that go out of date, and missing transaction rails so an agent can't actually buy.

Does the order of sections matter?

Yes. Agents read top-down under a token budget, so front-load identity and the transaction handshake. Put a scannable capabilities summary near the top (currencies, subscriptions, returns window) so an agent can quickly decide if you can serve its shopper before reading the whole file.

How do I know if my agents.md is good?

Run it against the checklist below, or use a tool that scores it. The free AI-readiness checker reports whether yours is Distinctive, Generic-default, or Missing, and AgentReady grades the file section by section so you can see exactly what's covered and what to add.

What Makes a Good agents.md: The Checklist AI Agents Actually Use

Most advice about agents.md stops at "customize it." That's not actionable. A good agents.md is the sum of specific sections, each answering a question an AI shopping agent is actually asking. Here's the checklist, in the order it matters.

The test for every section is the same: can an agent act on this? Not "is it filled in," but "does it help the agent understand, trust, or transact." A generic default technically has content and helps with none of it.

The checklist

Section	What it answers for the agent	Priority
Identity & positioning	What is this store, who is it for, why buy here	Essential
Capabilities summary	Can you serve my shopper (currency, shipping, subscriptions, returns)	Essential
What you sell	Which categories place you in the right consideration set	Essential
Transaction rails (UCP/MCP)	How do I actually check out	Essential
Most popular & featured	What to recommend when the shopper is vague	High
Ratings & reviews	Can I trust this enough to recommend it	High
Policies	Shipping and returns, the pre-purchase blockers	High
Sizing & fit	How do I help pick the right size (or N/A)	Situational
Locations & markets	Local/pickup intent, correct currency	Situational
Freshness	Is this current enough to rely on	Ongoing

Essentials: identity, capabilities, catalog, rails

Identity and positioning. One or two lines on what you are and why buy from you. Not your SEO meta title. An agent uses this to decide whether you belong in a recommendation at all. "Knitwear made to move with you" tells an agent something; "Brand | Premium Apparel Store" tells it nothing.

A capabilities summary up top. Before an agent reads your whole file, it wants to know if you can even serve its shopper: which currencies you take, where you ship, whether you offer subscriptions, your returns window. Put this near the top as a scannable block. Agents read top-down on a budget; front-load the deciding facts.

What you sell. Your real categories, in priority order, the way they appear in your storefront navigation, not an A-to-Z dump of every system collection. This is how an agent places you in the right consideration set ("running shoes," not "products").

The transaction rails. The UCP discovery endpoint and the MCP endpoint, matched to Shopify's, so an agent can go from "this looks right" to a built checkout without scraping. A file that describes your brand beautifully but omits the rails is a brochure, not a storefront. (What these endpoints do is its own topic; the agents.md pillar covers them.)

High-value: popularity, proof, policies

Most popular and featured. When a shopper is vague ("find me a good hoodie"), agents default to popularity. Surfacing your best-sellers hands the agent the answer it would otherwise guess. Featured picks let you steer beyond raw sales.

Ratings and reviews. Social proof is decisive in agent recommendations, and agents cite it. An aggregate rating plus a couple of short testimonials tells an agent it's safe to put you forward.

Policies. Shipping and returns are the pre-purchase blockers an agent has to resolve before it recommends a buy. Summarize them inline and link to the full policy. Don't make the agent crawl for "do they ship to Canada."

Situational: sizing, locations, markets

Sizing and fit is the top return-driver in apparel and footwear, so if it applies, say how to pick the right size. If it genuinely doesn't apply (one-size, digital, consumables), mark it not applicable rather than leaving an awkward gap, and move on. Not every section fits every store, and a good file is honest about that instead of padding.

Locations and markets matter for local/pickup intent and correct per-country pricing. Include them if you have physical stores or sell into multiple markets; skip them cleanly if you don't.

The ongoing one: freshness

A good agents.md is current. Agents weight recently-updated sources, and a file that still lists last season's catalog or an old return policy actively misleads. Stamp it with a last-updated date, and refresh it when your store changes. Staleness is the failure mode that creeps in after launch, which is why the file needs an owner or a tool watching for drift. (More on that in robots.txt vs llms.txt vs agents.md, which covers how the discovery files fit together.)

And the things to leave out

Private data. No contact email or phone. The file is broadly cached; link to your public contact page instead.
Discount codes. They expire and leak; keep promo codes out of a permanent public file.
System collections and non-shoppable components. "Frontpage," ad feeds, and builder-only SKUs are noise an agent shouldn't reason over.

Score yours against the checklist

You can grade your own file by walking this list, or let a tool do it. AgentReady generates a brand-specific agents.md that covers these sections from your live store, free, and scores it so you can see exactly what's covered and what would make it stronger, then hands you the file to paste in. The free AI-readiness checker reports whether your live file is Distinctive, Generic-default, or Missing.

Run the checker to see how your agents.md scores today.