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.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.
> 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 SKU
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.
| 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.
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 | ||
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.
- 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:
python tools/from_openapi.py https://api.yoursite.com/openapi.json > 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.
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.
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.