Most Ways to Edit agents.md Bolt Permanent App Code Into Your Theme. There's a Cleaner Way.

There's only one supported way to override Shopify's auto-generated agents.md: a theme template at templates/agents.md.liquid. We walk through why that constraint exists in the pillar. The question this post is about is what goes in that file, because the way a tool fills it decides whether you own the result or inherit a dependency.

The hidden cost isn't the file. It's what the file depends on.

Putting an agents.md in your theme is fine. The trouble starts when the file isn't really yours: when it's proprietary app code, or a template wired to data only an app keeps alive.

You see this pattern across Shopify apps. To "customize" a storefront file, an app drops in an app block, a snippet include, or a template that reads an app-owned metafield and renders nothing without it. It works while the app is installed. Then you uninstall, or switch themes, or the app changes how it stores data, and the dependency snaps. The template now points at something that isn't there. What's left is leftover code you didn't write and can't safely delete, because nobody remembers exactly what it needs. It's a well-known source of theme cruft.

For agents.md specifically, a broken dependency is worse than cruft. If your template renders blank because the data it depended on is gone, the file an AI agent reads to understand your store comes back empty.

The cleaner way: a file you own outright

The fix is to make the file plain content, not app machinery. AgentReady generates your agents.md from your live catalog, collections, policies, FAQs, reviews and best-sellers, and gives you the finished Markdown to paste into templates/agents.md.liquid. The full walkthrough is in how to customize your agents.md in two minutes.

What lands in your theme is just Markdown. No app block, no proprietary snippet, no metafield the app has to keep filled. The file means the same thing whether AgentReady is installed or not, because it doesn't reference the app at all.

Look at what that does to the failure modes above:

• Uninstall the app. Nothing happens to your agents.md. It's your file; it serves exactly as pasted. There's no webhook that needs to fire, no data to purge, nothing to break.
• Switch themes. Paste the file into the new theme. It's self-contained content, so it ports in one step with no dependency to re-wire.
• Revert to Shopify's default. Delete templates/agents.md.liquid. That's the whole cleanup, and you can do it yourself in ten seconds without wondering what else it touched.

The honest tradeoff

Owning the file outright has one cost: because the app doesn't keep a live dependency in your theme, it can't silently update the file for you. When your store changes, you re-paste an updated version.

AgentReady is built around that. It watches your store, regenerates the file when your catalog or policies drift, and flags you with what changed so the only manual step is a copy and a save. You trade the illusion of auto-magic for a file that is genuinely yours, portable, and impossible to break by uninstalling.

It's the same reason the file isn't written into your theme automatically: doing that would require handing an app standing permission to edit your theme, which is exactly the kind of dependency this approach avoids. (For how agents.md sits alongside robots.txt and llms.txt, see what each file does.)

If you want to see what your agents.md looks like to an agent right now, the free AI-readiness checker reports whether your file is Distinctive, Generic-default, or Missing. The complete agentic commerce guide covers where the file fits among the rest of your machine-readable signals.

Run the checker, then read the two-minute walkthrough for the cleaner path.