Answer · checked 31 August 2026
What is /.well-known/agent.json and should I publish one?
A capability manifest at /.well-known/agent.json is a small JSON file at a predictable address that states, in machine-readable form, who a site belongs to, what it offers, what an agent is permitted to do, and which operations exist — the thing a site has no other way to say. It is not a ratified standard: the path and schema are conventions, and MCP discovery alone has competing proposals at three different paths. Publish one if you want to be readable by what is being built now, write it so it is cheap to change, and do not let anyone tell you the format is settled.
Colour International LLC · 31 August 2026 · colourintl.com/learn/agent-json-manifest
The gap it fills
Everything else a site publishes for machines describes *content*. A sitemap lists pages. Structured data annotates what a page is about. Neither can express "an appointment can be booked here, this is the endpoint, these are the constraints, and this is our policy on automated access." A capability manifest is the only place that currently goes.
This matters most for businesses that transact. In the ten largest salon booking platforms we scanned in August 2026, not one published a capability manifest — so an assistant asked to book an appointment has no way to learn from any of them that booking is even possible, let alone how. The gap is not subtle and it is not contested; it is simply unaddressed.
What to put in it
Keep it to what you can state truthfully and keep true: identity, a description, a canonical URL, where the documentation and sitemap are, a contact address, an explicit policy block (crawl, index, train, act, identification expected, rate limit), and a list of capabilities each with a method, a path and a return type.
The mistake to avoid is declaring capabilities that do not exist or that you will not maintain. A manifest is a promise to a machine that will act on it literally, and a stale one is worse than none: it converts a site that could not be used into a site that fails when used.
Ours is at https://colourintl.com/.well-known/agent.json and is deliberately small. It declares exactly two capabilities, because those are the two we actually serve.
The standards position, stated plainly
We report the action surface in our scan and deliberately do not score it. The relevant specifications are unsettled, and scoring a moving target would manufacture failures that cannot be fixed and would not stay fixed — which is not a defensible thing to sell against a fixed-price guarantee. Anyone presenting the manifest format as finalised is either not following the working groups or is selling certainty they do not have.
Related
llms.txt vs robots.txt — what do AI crawlers actually respect?
robots.txt is respected: it is a thirty-year-old convention that every major crawler including GPTBot, OAI-SearchBot, ClaudeBot, PerplexityBot and Google-Extended reads and obeys, and it is the only file on this list that changes what a machine is permitted to do.
Why do AI assistants never mention my business, and how do I fix it?
Usually for one of two reasons, and they need opposite fixes.
Check your own site
Scan any domain at colourintl.com — sixteen weighted checks, free, no account, and the transcript of all eight requests is printed on the result page. Everything it finds is yours to implement at no cost.
This page is also available as Markdown: curl -H "Accept: text/markdown" https://colourintl.com/learn/agent-json-manifest