Most Ways to Edit agents.md Bolt Permanent 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 you put in that template, because the obvious answer carries a cost most people don't see until later.

The obvious approach, and where it bites

The obvious move is to write your whole agents.md straight into the template. Open the theme editor, paste in your brand description, your featured products, your policies, save. Done.

It works on day one. Then three things happen.

Your catalog changes. You launch a flagship product, retire a collection, rewrite the return policy. The agents.md you hand-wrote still describes the old store, and the only way to fix it is to go back into theme code and edit it again. Every change is a theme edit, and theme edits are exactly the kind of chore that quietly stops happening.

You switch or duplicate your theme. The agents.md.liquid template lives in one theme. Spin up a new one for a redesign or a seasonal campaign and your carefully written file doesn't come with it. You either remember to port it or you silently fall back to the generic default.

You used a tool to draft it. Plenty of merchants generate the content with some helper and paste the output in. That output is now frozen theme code. The tool that wrote it can't update it, can't refresh it as your catalog moves, and can't remove it when you stop using it. It just sits in your theme going stale.

None of these is catastrophic. Together they describe a file that starts good and rots, which is the normal fate of hand-maintained machine-readable data.

The cleaner way: a connector plus a metafield

The fix is to stop putting content in the theme at all. You paste a small generic connector into templates/agents.md.liquid once, and it never changes. Here's the whole thing:

{%- assign agents_md = shop.metafields.agentready.agents_md.value -%}
{%- if agents_md != blank -%}
{{ agents_md }}
{%- else -%}
# Agent Instructions — {{ agents.store_name }}

This store supports the Universal Commerce Protocol (UCP) for AI shopping agents.

- UCP discovery: GET {{ agents.ucp_discovery_url }}
- MCP endpoint: POST {{ agents.mcp_endpoint_url }}
- Sitemap: {{ agents.sitemap_url }}
{%- endif -%}

The template's only job is to read a shop metafield, agentready.agents_md, and serve whatever content is there. The content lives in the metafield, not the theme. AgentReady generates it from your live catalog, collections, policies, and FAQs, writes it to the metafield, and refreshes it when you re-publish. The full walkthrough is in how to customize your agents.md in two minutes.

Look at what this does to the three problems above.

When your catalog changes, you re-publish from the app and the metafield updates. No theme edit. The template never moves.

When you switch themes, you paste the same six-line connector into the new theme once. The content, which is the part that took thought, is already in the metafield waiting. There's nothing to port.

And the content is never frozen, because it was never theme code. It's app-managed data the whole time.

Self-cleaning is the part nobody offers

Here's the difference that matters most, and it's the one most Shopify apps get wrong. When you uninstall AgentReady, its app/uninstalled webhook purges the agentready.agents_md metafield. The connector you pasted sees an empty metafield and falls back to its built-in default, which still advertises your UCP discovery and MCP endpoints so agents can still transact. Your /agents.md keeps working. It just reverts to generic content.

What's left in your theme is six lines of vendor-neutral Liquid that you can delete in ten seconds if you want to. No brand copy, no stale product list, no orphaned snippet.

Compare that to the normal pattern. Most apps that touch your storefront leave something behind: a snippet include, an app block, a chunk of Liquid that persists in your theme long after the app is gone. It's a well-known source of theme cruft, the kind of thing developers find years later and can't safely remove because nobody remembers what installed it. An approach that purges its own data on uninstall and leaves only a connector you control is the opposite of that.

This is honest about the tradeoff. The hand-edited approach gives you full control and zero dependency: it's all yours, forever, including the upkeep. The connector approach trades that for content that stays current on its own and cleans itself up if you leave. For a file that's supposed to track a catalog that never stops moving, the second tradeoff is usually the right one.

If you want to see what your agents.md looks like to an agent right now, before you decide either way, 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 if you want the cleaner path.