capabilities.txt — declare what your site can do
Background
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.
The proposal
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.txt
Human- and agent-readable markdown: capabilities grouped by category, each with an id, version, and one-line description.
/.well-known/capabilities.json
The 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.
Format
# capabilities.txt
> One sentence: what this host is and the capabilities it offers.<br>> Structured form: https://example.com/.well-known/capabilities.json
## Support
### Tickets (support.tickets)
- support.create_ticket (v1.2.0) — Open a support ticket<br>- 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 SKU<br>Line 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.
Where it sits
FileAnswersFor<br>robots.txtWhat may a crawler access?Crawlers<br>sitemap.xmlWhat pages exist?Search engines<br>llms.txtWhat's worth reading?LLMs reading<br>capabilities.txtWhat 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.
Examples
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):
MarketExampleCapabilities like…<br>E-commerceshop.examplecheck stock, place order, start a return<br>Customer supportsupport.examplecreate ticket, search KB, escalate to a human<br>Banking / fintechbank.examplebalance, initiate transfer (step-up), open dispute<br>Healthcareclinic.examplebook appointment, request records (consent), refill (clinician-gated)<br>Developer platformcloud.exampledeploy, 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.
Adopt it
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. Add yourself to the directory with a pull request.
Already have an OpenAPI spec or an MCP server? Generate it — no manual authoring:
# from an OpenAPI description<br>python tools/from_openapi.py https://api.yoursite.com/openapi.json > capabilities.txt
# validate any capabilities.txt<br>curl -s https://yoursite.com/capabilities.txt | python tools/validate.py -
For agents (how to consume it)
capabilities.txt is only as useful as the agents that read it. The consumer flow is deliberately simple:
Discover — fetch https://host/capabilities.txt (or /.well-known/capabilities.json for structure).
Choose — pick a capability by id and read its one-line description.
Invoke — call it via the host's invocation endpoint (an MCP server, an HTTP API, etc.) that the file points to. capabilities.txt does discovery; it hands off invocation.
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.
Where this goes next
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,...