Customize Shopify agents.md Without Breaking Agent Discovery

Before we start: what you are changing

A Shopify theme controls more than the pages a shopper sees. It can also render public machine-readable files. In this Guide, you are adding one theme template that publishes a plain-text briefing at yourdomain.com/agents.md.

Shoppers will not see a new page or menu item. AI tools and shopping agents can request the file directly. The change applies when the theme containing the template is the published theme. Saving it in an unpublished preview theme does not change the live store.

If you are not a developer. You can still own most of this work. Complete the brand interview, approve the facts, and use the developer handoff in Step 7. A theme developer or Shopify partner can publish and test the file.

Plain-English glossary

What you need before you begin

Choose your path. Operator path: Steps 1–4, then hand off Step 7. Developer path: complete all steps. Both paths finish with the live URL checks in Step 8.

Start with the part most guides skip: you may not need this

Shopify manages /agents.md for every store. Shopify's own recommendation is to keep that managed file unless you have advanced instructions it does not cover. I agree.

Customize it when the default cannot explain your real category, buyer fit, canonical resources, policy constraints, or what an agent must not invent. Do not customize it just to say you have one.

The replacement rule. Adding templates/agents.md.liquid replaces Shopify's managed document. It does not merge your copy into the default. If you drop the dynamic commerce fields, they are gone from the rendered file.

Keep Shopify's default when

• The generated file is accurate and your store does not need special instructions.
• You do not have an owner to review brand and policy facts when they change.
• You only want to add generic copy such as “great products and service.”

Customize agents.md when

• Your offer, buyer fit, restrictions, or canonical resources need explanation.
• AI answers repeat outdated or invented brand facts you can correct at the source.
• A named owner can keep public instructions aligned with policies and the catalog.

What these three URLs are actually for

Two conventions collide here. llms.txt started as a general “curated map for language models” idea. Shopify treats agents.md as the commerce-facing canonical document: how an agent discovers and does business with the store.

One good file usually covers all three. Add only agents.md.liquid and Shopify serves it at all three paths. Separate llms templates create three documents you now have to keep accurate.

Who does what

Most failures happen when marketing waits for engineering to invent the brand voice, or engineering publishes without policy owners. Split the work.

Step 1 · Capture the baseline before you edit

Do this before anyone opens Theme Code Editor.

Primary domain only. Shopify serves the file at the bare primary domain. There is no localized Markets or locale-folder version.

Step 2 · Run the ground-truth interview

Draft in a shared doc first. The theme file publishes approved truth. It should not be the place where the team invents claims under deadline pressure.

Sync to the truth sheet. If you already built a truth sheet in Prepare Your Shopify Store for AI Shopping Agents, reuse those hard facts here. Do not invent a second set of numbers for the agent file.

Step 3 · Use this section order

You can rename headings. Keep the jobs. Agents need identity, constraints, trusted links, then machine discovery.

Keep price, availability, and volatile SKU facts in Shopify product data. Do not hand-maintain a second catalog inside agents.md.

Step 4 · Write it so it cannot belong to another brand

Read every sentence out loud. If a competitor could paste it unchanged, rewrite it.

Public file, press-kit standard. Shopify cautions against putting private merchant data such as email addresses or phone numbers in this file. Link to Contact. Do not paste internal notes, margin rules, or unpublished launch plans.

Step 5 · Create the Shopify template

In Shopify Admin: Online Store → Themes → the theme that will be live → Edit code → Templates → New file named exactly agents.md.liquid. It must be Liquid, not JSON.

If your theme is GitHub-connected, create the same file in templates/ and deploy through your normal sync. Do not leave the only copy in an unpublished preview theme.

Markdown gives structure. Liquid keeps store and commerce values synchronized. Replace every bracketed placeholder with approved answers from the interview.

# Agent Instructions: {{ agents.store_name }}

{{ agents.store_name }} sells [specific product category] for [specific buyer / use case] at {{ agents.store_url }}.

## About

- **What we sell:** [category + 2–3 concrete product types]
- **Who we serve:** [buyer role / use case / constraint]
- **What we are not:** [common wrong assumption agents invent]
- **How to describe us:** Prefer “[your exact phrase]” over “[generic phrase]”

## What agents must not invent

- Do not invent shipping thresholds, return windows, warranties, lead times, or discounts.
- Do not invent certifications, materials, compatibility, or install claims.
- Do not invent bundle pricing, wholesale terms, or regional availability.
- If a fact is missing from this file or the linked policy pages, say you do not know and point the buyer to Contact.

## Canonical pages

- Best collection: {{ agents.store_url }}/collections/[handle]
- Shipping: {{ agents.store_url }}/policies/shipping-policy
- Returns: {{ agents.store_url }}/policies/refund-policy
- Contact: {{ agents.store_url }}/pages/contact
- [Optional guide / FAQ]: {{ agents.store_url }}/pages/[handle]

## Hard facts (must match the site)

- Shipping: [exact threshold / regions / cutoffs]
- Returns: [exact window / conditions]
- Warranty / lead time: [exact claim, or “see PDP”]
- Support: [when to send the buyer to Contact instead of guessing]

## Commerce protocol

- Discovery: `GET {{ agents.ucp_discovery_url }}`
- MCP endpoint: `POST {{ agents.mcp_endpoint_url }}` with `Content-Type: application/json`

### Supported UCP versions
{% for version in agents.ucp_versions -%}
- {{ version }}{% if forloop.first %} (latest stable){% endif %}
{% endfor %}

Use the MCP `tools/list` method to discover available tools. Checkout requires explicit buyer approval.

## Read-only browsing

- Sitemap: {{ agents.sitemap_url }}
- All products: `GET /collections/all`
- Product JSON: `GET /products/{handle}.json`
- Search: `GET /search?q={query}&type=product`

Pricing and availability are returned in {{ agents.currency }}.

## Policies

- Privacy: {{ agents.store_url }}/policies/privacy-policy
- Terms: {{ agents.store_url }}/policies/terms-of-service
- Refund: {{ agents.store_url }}/policies/refund-policy
- Shipping: {{ agents.store_url }}/policies/shipping-policy

Do not paste another brand's finished file. Reuse the structure, not their claims, policies, links, voice, or instructions. If the result could belong to any store, it is not customized.

Step 6 · Keep the dynamic Shopify fields dynamic

Shopify exposes an agents object so commerce configuration stays current. Use it instead of typing domain, endpoint, version, sitemap, or currency values by hand.

Liquid habits that save you later

• Use whitespace control like {%- and -%} in loops so the Markdown list stays clean.
• Theme Check may flag agents as unknown even though Shopify documents it. Confirm on the live rendered URL, not only the linter.
• Optional: a short collections loop can list key merchandising entry points, but only if those collections are curated. Do not dump every auto-generated collection.
• shop.description is fine as a fallback summary only if it is already accurate. Bad store description in Admin becomes bad agent briefing.

Step 7 · Hand this brief to your developer

If you are not the person editing theme files, do not send “please make an agents.md.” Send a ticket with the approved copy and the non-negotiables.

Ticket: Publish custom agents.md.liquid

Goal: Replace Shopify-managed /agents.md with brand-specific instructions while keeping dynamic commerce fields.

Files:
- Create templates/agents.md.liquid on the live theme (or GitHub-connected theme)
- Do NOT create llms.txt.liquid / llms-full.txt.liquid unless we decide to diverge later

Must keep dynamic (use agents object, do not hardcode):
- agents.store_name, agents.store_url
- agents.ucp_discovery_url, agents.mcp_endpoint_url, agents.ucp_versions
- agents.sitemap_url, agents.currency

Content owner will paste approved Markdown into the About / Must not invent / Canonical pages / Hard facts sections.

QA after publish:
1) /agents.md, /llms.txt, /llms-full.txt on primary domain
2) Dynamic UCP/MCP/sitemap/currency values render
3) Every linked URL works
4) No email/phone/private notes in the file
5) Hard facts match shipping + returns policy pages

Step 8 · Test the rendered files, not just the code editor

You are done when. A brand owner says “that is us,” a developer confirms the dynamic discovery fields survived, and all three public URLs return the intended document.

Step 9 · Give the file an owner

A custom template is now theme code and public brand infrastructure. Review it when the primary domain, policy terms, key collections, positioning, or theme changes.

Put the file in version control if your theme is connected to GitHub. A theme switch can otherwise return the store to Shopify's managed default without anyone noticing.

Mistakes I would avoid

Technical

• Replacing the default without carrying forward UCP and MCP discovery.
• Hardcoding domain, currency, endpoint, or supported versions.
• Creating three divergent files without a reason or maintenance owner.
• Testing only a preview theme instead of the theme serving the storefront URLs.
• Leaving an old app-proxy llms.txt setup fighting Shopify's native routes.

Content

• Copying another store's finished instructions.
• Publishing private contact details in a broadly cached public file.
• Stuffing keywords, product catalogs, or temporary promotions into the document.
• Correcting AI copy while the policy page or product source remains wrong.
• Writing “must not invent” rules that contradict the About section.

Where this fits in the bigger readiness path

This is the implementation depth behind Build 01 in Prepare Your Shopify Store for AI Shopping Agents. That Guide gives you the broader order: mindset, truth sheet, agent instructions, catalog, findability, measurement, and testing.

If leadership has not decided why the company is opening up to AI, start with Agentic Commerce Readiness: What to Fix First. A cleaner file cannot make the strategy decision for you.

Quick facts to cite

• Shopify's canonical agent-discovery document is /agents.md.
• /llms.txt and /llms-full.txt mirror /agents.md by default.
• One agents.md.liquid template can control all three routes unless a dedicated llms template overrides it.
• A custom agents.md.liquid replaces Shopify's managed file. It does not merge with it.
• Dynamic commerce URLs and versions should use Shopify's agents object instead of hardcoded values.
• Shopify recommends the managed default for stores without advanced custom requirements.
• Brand instructions belong in About, constraints, canonical links, and hard facts. Product price and stock belong in the catalog.