A simple, open convention for a website to publish the capabilities an agent can discover and invoke — at a well-known location.
The web taught machines to read in layers. robots.txt says what a crawler may access. sitemap.xml says what exists. llms.txt says what's worth reading. Each answers one narrow question for an automated reader.
None of them answers the question agents now ask: what can this host actually do?
Agents have stopped only reading the web and started acting on it. An agent that lands on your site can summarize your docs — but it has no standard way to discover that you expose a "create support ticket" capability, "check inventory," or "start a return," and how to call them. Today that happens through bespoke, one-vendor-at-a-time integrations.
capabilities.txt is the missing layer: a public, well-known file where a host declares the capabilities it offers, so any agent can discover what it can do. A host publishes one or both:
/capabilities.txtHuman- and agent-readable markdown: capabilities grouped by category, each with an id, version, and one-line description.
/.well-known/capabilities.jsonThe structured form: an array of capability references, each resolvable to a full descriptor.
It's deliberately small. llms.txt worked because you could adopt it in an afternoon. capabilities.txt follows the same rule.
# capabilities.txt
> One sentence: what this host is and the capabilities it offers.
> Structured form: https://example.com/.well-known/capabilities.json
## Support
### Tickets (support.tickets)
- support.create_ticket (v1.2.0) — Open a support ticket
- support.get_status (v1.0.0) — Check a ticket's status
## Commerce
### Inventory (commerce.inventory)
- commerce.check_stock (v2.0.0) — Check availability for a SKULine 1 is # capabilities.txt. A > blockquote summarizes the host. ## groups by category; ### names a group; each capability is a list item with a stable id, optional (v…), and a short description. It's just markdown — if a human can read it and an agent can parse it, it's valid.
| File | Answers | For |
|---|---|---|
robots.txt | What may a crawler access? | Crawlers |
sitemap.xml | What pages exist? | Search engines |
llms.txt | What's worth reading? | LLMs reading |
capabilities.txt | What can this host do? | Agents acting |
It's not a replacement for MCP or an API spec. MCP is a stateful connection-and-invocation protocol; OpenAPI describes an HTTP API. capabilities.txt is the layer before invocation — a static, public, crawlable advertisement an agent can read with no live connection, that points to your MCP server or API for the actual call. Discovery and invocation are different jobs; capabilities.txt does discovery and hands off invocation.
Full comparison: capabilities.txt vs llms.txt, mcp.json & OpenAPI → · How AI agents discover what a site can do →
A real, live capabilities.txt — the governed capability surface of the CHP adapter ecosystem:
capabilityhostprotocol.com/capabilities.txt — live
And how it looks across markets (illustrative templates you can lift):
| Market | Example | Capabilities like… |
|---|---|---|
| E-commerce | shop.example | check stock, place order, start a return |
| Customer support | support.example | create ticket, search KB, escalate to a human |
| Banking / fintech | bank.example | balance, initiate transfer (step-up), open dispute |
| Healthcare | clinic.example | book appointment, request records (consent), refill (clinician-gated) |
| Developer platform | cloud.example | deploy, fetch logs, scale (entitlement-gated) |
Notice the pattern: read-only capabilities are simple; the consequential ones (a transfer, a refill, a deploy) note who must approve and that the action is recorded. That hand-off — from "what you can do" to "may I, and can I prove it" — is where CHP picks up.
Two near-zero-effort paths: generate it from your OpenAPI in ten seconds, or copy a prompt and hand it to your AI coding agent — it writes your /capabilities.txt from your real API. Then check it for a grade and a badge, and it’s discoverable in the directory + map.
Prefer to do it by hand? 1. List the capabilities your site exposes. 2. Write them into /capabilities.txt using the format above. 3. Optionally publish /.well-known/capabilities.json. 4. check + list it.
From the command line instead:
# generate from an OpenAPI description
python tools/from_openapi.py https://api.yoursite.com/openapi.json > capabilities.txt
# validate any capabilities.txt
curl -s https://yoursite.com/capabilities.txt | python tools/validate.py -capabilities.txt is only as useful as the agents that read it. The consumer flow is deliberately simple:
https://host/capabilities.txt (or /.well-known/capabilities.json for structure).A capability that does something — a transfer, a refill, a deploy — should also tell a careful agent whether it may and whether the action is recorded. That governance layer is CHP; capabilities.txt is the public front door to it.
Discovery is the first step. Once an agent knows what you can do, the next questions are may I, what happened, and can I prove it — invocation, governance, and evidence.
Those are defined by the Capability Host Protocol, an open protocol for which capabilities.txt is the natural public face. You can adopt capabilities.txt on its own; CHP is where it leads if you need the rest.
No — they're complementary. MCP is a stateful connection that runs tools. capabilities.txt is the static, crawlable layer before that: an agent (or a search engine) reads it with no connection, then uses MCP/your API to actually invoke. Discovery vs. invocation.
OpenAPI describes the shape of an HTTP API in detail. capabilities.txt is a one-screen, human-and-agent-readable advertisement of what you can do — published at a well-known path, framework-agnostic, and able to point at any invocation method (MCP, HTTP, gRPC). You can generate one from OpenAPI.
Essentially, yes — and that's the point. llms.txt says what's worth reading; capabilities.txt says what you can do. Same spirit, the next layer.
llms.txt + mcp.json already enough?They cover different things, and both assume more than this does. llms.txt is for reading, not actions. An mcp.json advertises that you run an MCP server — which means (a) you have to run one, and (b) discovery is connection-first: a client connects to learn the tools. capabilities.txt is invocation-agnostic (it can point at an MCP server, a plain HTTP API, anything) and static — an agent or even a search engine reads it with no connection and no MCP client. Most sites have a REST API and no MCP server; capabilities.txt works for them too. They compose: capabilities.txt is the public catalog; mcp.json is one of the endpoints it hands off to.
No. capabilities.txt stands alone — publish one today, point it at whatever you already run. CHP is where it leads if you need governance, permissions, and provable evidence for the actions.
It only advertises what you already expose; it grants nothing. Authentication, rate limits, and authorization stay on your invocation endpoint. Declaring a capability is not the same as leaving it open.
It's deliberately minimal and complementary — it fills the one gap none of the others do (what a host can do) and hands off to whatever you already run rather than replacing it. The cost is an afternoon, or zero if you generate it from your OpenAPI. The result is fewer bespoke, per-vendor integrations, not more files to maintain.
Agentic and IDE tooling already fetches well-known files like llms.txt. capabilities.txt is the same cheap, agent-readable infrastructure — for action, not just reading. It's a proposal; adoption is the work, and your feedback shapes it.