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.
> 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.

Where it sits

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):

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
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 -

For agents (how to consume it)

capabilities.txt is only as useful as the agents that read it. The consumer flow is deliberately simple:

1. Discover — fetch https://host/capabilities.txt (or /.well-known/capabilities.json for structure).
2. Choose — pick a capability by id and read its one-line description.
3. 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

FAQ

Isn't this just MCP?

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.

Isn't this just OpenAPI?

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.

Isn't this just llms.txt for actions?

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.

Do I need CHP to use it?

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.

Won't this expose me to abuse?

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.

Will agents actually use it?

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.