How To Write an /agents.md for a Services Business

Getting discovered on the web by search and shopping agents is a hot topic of discussion, so we went looking for the right setup and structure to help them find this site:

Rebuilding My Website for the Agentic Web documents the process of the new site
Agentic Websites - Whitespace and Opportunities goes through the search for best practices for agentic optimization across the web

What I found was:

a) Shopify is pioneering the product side of the market with their canonical /agents.md reference
b) The services side of the market was a smorgasbord of different standards, views, and implementations
c) No services firm, consultancy, or publication has created a bespoke web-root agents.md (in the same way Shopify has for their merchants)

Given the experimental nature of the site and Notebook, I decided to publish the ideas and implementation for the services side, so here it is.

The Agents Are Coming!

Why does this matter for a services firm?

ChatGPT, Claude, Gemini, Perplexity and more are sending their agents out to crawl the web on behalf of those users. Those agents parse through the web in search of the products and services their users are after. Just like the old days of SEO but with a twist - agents don't read the web the way humans (and traditional search engines) do.

Agents are particularly sensitive to 'context.' That means that traditional webpages that are javascript or other heavy front-end coding language bloats their context window. When their context window is bloated, they struggle to understand exactly what is being said and where; the gist of the website becomes convoluted.

Why?

Essentially, agents want to see the cleanest and clearest version of the contents of a website, with every important detail relative to the company and site stated clearly and plainly. That minimizes the bloat in the agent's context window and allows them to quickly search through and understand a website for its users.

How Agents Search for Products or Services Information

From an Agent's search to your inbox or phone

Here is the general workflow for agentic search:

A user is having a conversation with their favorite consumer agent (let's say ChatGPT) and signals their intent to find a certain product or service
The agent searches the web with that context, finds the relevant set of companies by parsing their sites, and returns those results to the user in the agentic interface
From there, the user has a set of decisions to make; if they are interested in a given company's product or service, they may make the transaction there in the agentic chat window (agentic commerce) or they may decide to interact with the company itself
That could mean calling or emailing the company, going through the website themselves manually, or whatever set of actions they deem necessary to inform a potential purchase

This ain't the web of the 2000s or the 2010s anymore. Agents are not interested or impressed by glossy images, verbose text blocks on pages, or AI-generated blog posts. They are looking for substance and signal.

The goal of this post is to look at one compelling way to give it to them, borrowing from the Shopify web-root /agents.md (or just /agents.md) idea. Keep in mind that none of this is standardized and we don't know what's going to win; it is purely experimental. As the research documented, there is also a chance that llms.txt or JSON manifests may win.

But the Shopify /agents.md is worth looking at anyways, especially while such standards for websites are developing.

Shopify and the Agents.md Standard

The Coding Agent Analog

Coding agents have taken the AI world by storm. Claude Code, OpenAI Codex, Cursor, and others have created autonomous coding agents that can spin up websites, apps, and agents through text-based interaction. Prompts - written in natural language - have become the gateway to coding (not the code itself) in the agentic web.

The principal repo file that governs that process is /agents.md (or /Claude.md on Claude Code). The /agents.md file sits in the core directory of the code repo, and it is a succinct markdown file (.md = markdown) which is essentially a bulleted text list of all the essential context the agent needs to write the code to the user's specification.

Shopify borrowed the filename for something different. Their version of /agents.md doesn't live in the codebase but at the root of the storefront's website, with specific instructions addressed to shopping agents. What does Shopify's agents.md file contain?

Identify the who and the what of the store
Show the key endpoints, which relates to UCP (Universal Commerce Protocol) and agentic commerce
Establish the flow, almost as a table of contents for crawling
Human approval rules, which applies a governance standard for transacting in the agentic interface

Shopify's guidelines on agents.md clarify how it works and how it relates to llms.txt/other agent content.

Shopify's /agents.md is the same name as the coding format, but a completely different file function; one guides your coding agent, the other guides prospective shopping agents. This post references the second one, the shopping agents - it is being used by Shopify to make all their merchants easily discoverable and indexable for agents. That's great if you are a Shopify merchant, but what if you are selling services?

Well, it's not so simple. Shopify's web-root /agents.md is transaction-shaped, as its customers are merchants selling products. The services version of this has a different purpose, which is to drive inquiries and leads about a service.

The Agents.md Experiment for Services Companies

What We Are Using on This Site and Why

As part of the experiment that is this website, /agents.md was launched (click the link to see it) based on the Shopify research.

Lumos is a services company and blog, rolled into one new website construct that is aimed at the agentic web. /agents.md makes it easy for an agent to navigate through the website and understand the nature of those services.

How an /agents.md looks for a services company

Reference is /agents.md on this site

At a glance - Core facts an agent needs, answerable without further reading
What's offered - The service, its price, and where to start
How to read this site - The index (llms.txt), the key pages, content libraries, structured data
How to act - A numbered flow, step-by-step: Discover - Read - Inquire - Human Reply, as one example
Endpoints & status - Outline major endpoints (MCP if applicable) and their associated status
Usage & policies - Rules, terms of use, etc.

/agents.md for Service Companies - Structure, Template and the Follow Through

Three rules hold the file together

The file itself is not hand-written, it is rendered from the record, the same source the site itself is rendered from. Nothing in it can drift from the site
Anything an agent could try to call carries a status line, live or not.
The structure is for machines, while the 'human voice' is capped at five or so lines throughout the whole file, for the curious human who fetches it

The template can be found here.

It was derived from the same code that renders the site's live file, so there is no drift between the two. Updating one will lead to updating the other, no stale versions. Keep in mind, this is just a skeleton and the only endpoint on this site is a form; those services companies with quoting, booking, or other endpoints would need to adjust it appropriately.

The actual structure and template has already changed once as new research emerges, this is v1.1. Since it's a very fluid concept and implementation, there will always be new research and analysis required to ensure the gist of it is maintained in the current context.

What would change this post?

The agents.md maintainers officially accept or reject its use - both scenarios would be interesting, frankly; a major website builder (where services firms build their sites) starts emitting these files by default, or one of their plugin providers does; the JSON manifests under /.well-known get rolled up and the markdown file(s) become the second-order, human readable companion; similarly, llms.txt could also become the standard on the mainstream web, as many still think is possible.

Until that happens, the thesis stands as shipped. And in the event this post gets it wrong, it still doesn't hurt for the average services company to start investigating the core principles of agentic search. AEO (Answer Engine Optimization) and GEO (Generative Engine Optimization) are hot topics right now, but what we are talking about here are the conventions that underpin them; understanding everything 'agentic' from the root helps navigate away from hype.

Fetch /agents.md, it's rendered from the same record as this post