Skip to main content

GUIDE № 08 · CRAWLABILITY

How to Update Your Shopify Store's agents.md File

5 min read · Guide 8 of 17

Every Shopify Liquid store has an agentic-discovery file at yourstore.com/agents.md. Shopify auto-publishes a baseline. The file is a plain-text Markdown summary that tells AI agents what your store is about, what you sell, and where to find key pages — think of it as a sitemap, but written for AI.

The baseline Shopify ships is generic. The merchant lever is enrichment: replacing the auto-gen baseline with your own category structure, brand voice, and FAQ via templates/agents.md.liquid.

How Shopify serves it today

Liquid theme stores — the vast majority of Shopify merchants — get a centrally-rendered /agents.md at the CDN edge, identical across stores except for brand name and canonical URL. The merchant action that matters is quality: replacing the generic auto-gen baseline with your own enriched content.

Hydrogen and headless storefronts own their own router. They serve /agents.md as a route at the framework level.

StoreAudit's scanner reads /agents.md directly — so on Liquid stores, the +2 score for "agentic-discovery file present" is earned automatically by every store. What changes the audit verdict is whether your /agents.md is the generic Shopify baseline or your own enriched version.

What is agents.md?

agents.md sits at yourstore.com/agents.md. AI agents check for it to quickly understand what your store offers without having to crawl every page.

It uses Markdown format and typically includes:

  • A brief description of your store
  • Your main product categories
  • Links to important pages (collections, policies, about page)
  • Any special information AI agents should know

What to put in your agents.md

Here's what enriched agentic-discovery content looks like for a fictional home goods store. The same content works whether you're authoring templates/agents.md.liquid on a Liquid store or serving /agents.md from a Hydrogen router: 

# Homestead & Co.

> Homestead & Co. is an online store selling handcrafted home goods
> made from natural materials. Based in Portland, Oregon. Ships across
> the United States.

## Product Categories

- [Blankets & Throws](https://homestead.co/collections/blankets)
- [Candles](https://homestead.co/collections/candles)
- [Ceramics](https://homestead.co/collections/ceramics)
- [Kitchen & Dining](https://homestead.co/collections/kitchen)

## Key Pages

- [All Products](https://homestead.co/collections/all)
- [About Us](https://homestead.co/pages/about)
- [Shipping Policy](https://homestead.co/policies/shipping-policy)
- [Return Policy](https://homestead.co/policies/refund-policy)

## Product Information

All products are handcrafted from natural materials. Materials include
organic cotton, beeswax, stoneware clay, and reclaimed wood. Most
products ship within 3-5 business days.

Keep it simple and factual. No marketing language — just the information an AI agent needs to understand your store.

How to edit agents.md on a Liquid theme

This is the path for the vast majority of Shopify merchants.

Step 1: Write your content in markdown

Use the sample above. Replace the store name, categories, and links with your own. Keep it factual — no marketing copy, no slogans, no prices that change.

Step 2: Open the theme code editor

In your Shopify admin, go to Online Store → Themes → Edit code. You'll land in your active theme's file tree.

Step 3: Add a new template

Under Templates, click Add a new template. The dropdown doesn't include agents as a type — type agents.md as the filename directly and Shopify will save it as agents.md.liquid under templates/.

Step 4: Paste your content and save

Paste the markdown content you wrote in Step 1 into the new template editor. Save.

Step 5: Verify

Visit yourstore.com/agents.md in a browser. You should see your content rendered as plain text.

What to include in your agents.md

Focus on the basics:

  • Store name and description — one or two sentences about what you sell
  • Product categories — link to your main collections
  • Key pages — policies, about page, contact page
  • Product details — anything that applies across your catalog (materials, shipping info, target market)

Don't include:

  • Marketing slogans or promotional language
  • Every single product (that's what /products.json is for)
  • Prices (they change too often — let the agent check product pages for current pricing)

Updating your agents.md

When you add new product categories or change your store structure, update the file. The process is the same: open Online Store → Themes → Edit code, edit templates/agents.md.liquid, and save.

How often should you update it? Whenever your product categories or store structure changes meaningfully. For most stores, that's a few times a year at most.

Optional: add a discovery tag

You can also add a <link> tag to your store's <head> to advertise your agentic-discovery file to AI agents. Use the standard rel="alternate" convention with type="text/plain": 

<link rel="alternate" type="text/plain" href="/agents.md" title="Agentic discovery">

Add this to your theme's theme.liquid file in the <head> section. This is optional — most AI agents fetch the file directly — but it doesn't hurt to have it.

If you're on Hydrogen / headless

Hydrogen and headless storefronts own their own router. You can author /agents.md as a route in your Remix app — the same markdown content works. Refer to Shopify's Hydrogen docs for the per-framework specifics.

RELATED