Why Your agents.md Goes Stale (and How to Keep It Current)

You did the work. You customized your agents.md so it describes your brand instead of Shopify's generic default, pasted it into your theme, and moved on. Six weeks later it's quietly wrong. This is the failure mode nobody warns you about, and it's worth understanding because it's structural, not a mistake you made.

A custom agents.md is a snapshot, not a feed

The moment you write or paste a custom agents.md, you freeze your store as it was that day: those products, those collections, that return policy, those prices. The file is a photograph, not a live mirror.

Your store, meanwhile, never stops moving. You launch a flagship product, retire a seasonal collection, rewrite shipping, run out of a best-seller. None of that touches the file. There's no mechanism in a hand-written or pasted file that notices your catalog changed and updates itself. So the gap between "what the file says" and "what your store is" widens a little every week.

This is the normal fate of any hand-maintained machine-readable data, and we wrote about the same drift for structured data and llms.txt. agents.md is no different, except the stakes are higher because agents transact on it.

Why a stale file is worse than a missing one

A missing agents.md falls back to Shopify's generic default: bland, but not wrong. A stale custom file is worse, because agents quote it confidently. They have no way to know your "current" file is three months old. So when it lists a product you discontinued, an agent recommends it. When it shows a 14-day return window you've since extended to 30, the agent tells a shopper the wrong policy. When it features last winter's collection in June, you look asleep.

The whole value of a custom file is that it's accurate and specific. Stale, it's specific and wrong, which is the one combination you don't want when a machine is repeating it to buyers.

Caching hides the problem

There's a second, sneakier reason your file can look out of date: Shopify caches the rendered agents.md. The file is served at your domain root and cached aggressively, so even after you update the template, the old version can keep serving for a while. Editing your catalog won't bust that cache; re-saving the agents.md.liquid template will. If you've updated the file and still see the old content, give it a minute, and confirm you actually changed the template, not just your store.

This is why "I updated my store but /agents.md didn't change" is almost always one of two things: you changed the store but not the file, or you changed the file but you're seeing a cached copy. Knowing which saves a lot of confusion.

How to actually keep it current

Three options, in increasing order of "set and forget":

1. Manual discipline. Refresh the file whenever you'd update your homepage. Works if you're rigorous; most stores aren't, which is exactly how files go stale.
2. Regenerate on demand. Use a tool that rebuilds the file from your live store whenever you ask, so a refresh is a copy and a paste, not a rewrite. Removes the "rewrite it by hand" friction but you still have to remember.
3. Drift detection. A tool watches your store, notices when your catalog, policies, or collections have moved away from what's live in the file, and flags you with exactly what changed plus the updated file to paste. This removes the remembering, which is the part that actually fails.

True automatic writing to your theme would be option four, but on Shopify an app can't write to your theme without a special access grant the platform gates carefully, so it isn't generally available. Drift detection is the closest practical thing, and it's the difference between a file that stays current and one that rots.

Where AgentReady fits

AgentReady does options two and three. It regenerates your agents.md from your live catalog, collections, policies, reviews and best-sellers, and it watches for drift, when your store moves away from what you last pasted, it flags you with what changed and hands you the updated file. You paste it over the old one. The file stays a current snapshot instead of an aging one. (For how the file itself is structured, see the agents.md pillar; for what a good one contains, the checklist.)

The free AI-readiness checker fetches your live file and tells you whether it's Distinctive, Generic-default, or Missing, the quickest way to catch a file that's drifted back toward useless.

Run the checker to see how current your agents.md is today.