{
  "markdown": "# capabilities.txt\n\n> A simple, open convention for a website to declare **what it can do** — the\n> capabilities an agent can discover and invoke — at a well-known location.\n\nThe web taught machines to read in layers. `robots.txt` says what a crawler *may\naccess*. `sitemap.xml` says what *exists*. `llms.txt` says what's *worth reading*.\nEach answers one narrow question for an automated reader.\n\nNone of them answers the question agents now ask: **what can this host actually\n*do*?**\n\nAgents have stopped only *reading* the web and started *acting* on it. An agent\nthat lands on your site can summarize your docs — but it has no standard way to\ndiscover that you expose a \"create support ticket\" capability, a \"check inventory\"\ncapability, or \"start a return,\" and how to call them. Today that happens through\nbespoke, one-vendor-at-a-time integrations.\n\n`capabilities.txt` is the missing layer: **a public, well-known file where a host\ndeclares the capabilities it offers, so any agent can discover what it can do.**\n\nIt is deliberately small. `llms.txt` worked because you could adopt it in an\nafternoon. `capabilities.txt` follows the same rule.\n\n## The two forms\n\nA host publishes one or both:\n\n- **`/capabilities.txt`** — human- and agent-readable **markdown**: capabilities\n  grouped by category, each with an id, version, and one-line description.\n- **`/.well-known/capabilities.json`** — the **structured** form: an array of\n  capability references, each resolvable to a full descriptor.\n\nThe markdown form is for discovery and reading. The JSON form is for machines that\nwant structure. Publishing the markdown form alone is a perfectly good start.\n\n## Format (`/capabilities.txt`)\n\n```markdown\n# capabilities.txt\n\n> One sentence: what this host is and what kind of capabilities it offers.\n> Structured form: https://example.com/.well-known/capabilities.json\n\n## <Category>\n\n### <Group name> (<group-id>)\n\n- <capability-id> (v<version>) — <one-line description>\n- <capability-id> (v<version>) — <one-line description>\n```\n\nRules, kept minimal:\n\n1. **Line 1** is `# capabilities.txt`.\n2. A **blockquote** (`>`) summary follows: one sentence on what the host offers,\n   plus optional links (the JSON form, docs, an invocation endpoint).\n3. **`##`** headings group capabilities by category (free-form, your choice).\n4. **`###`** headings name a group, optionally with a stable `(group-id)`.\n5. Each capability is a **list item**: a stable `capability-id`, an optional\n   `(v<version>)`, and a short `— description`.\n6. It's just markdown. If a human can read it and an agent can parse it, it's valid.\n\n## Structured form (`/.well-known/capabilities.json`)\n\n```json\n{\n  \"version\": \"1\",\n  \"capabilities\": [\n    {\n      \"id\": \"support.create_ticket\",\n      \"version\": \"1.2.0\",\n      \"description\": \"Open a support ticket\",\n      \"descriptor\": \"https://example.com/.well-known/capabilities/support.create_ticket.json\"\n    }\n  ]\n}\n```\n\nEach entry is a reference; `descriptor` (optional) points to a full machine-readable\ndescription of inputs, permissions, and how to invoke.\n\n## Where it sits among the standards\n\n| File | Answers | For |\n|---|---|---|\n| `robots.txt` | What may a crawler access? | Crawlers |\n| `sitemap.xml` | What pages exist? | Search engines |\n| `llms.txt` | What's worth reading? | LLMs reading |\n| **`capabilities.txt`** | **What can this host *do*?** | **Agents acting** |\n\nIt is **not** a replacement for MCP or an API spec. The Model Context Protocol is a\nstateful connection-and-invocation protocol; OpenAPI describes an HTTP API.\n`capabilities.txt` is the layer *before* invocation — a static, public, crawlable\nadvertisement an agent (or a search engine) can read with no live connection, that\n**points to** your MCP server, HTTP API, or other endpoint for the actual call.\nDiscovery and invocation are different jobs. capabilities.txt does discovery; it\nhands off invocation.\n\n## Adopt it\n\n**Fastest (no spec):** copy the prompt at [capabilitiestxt.org/implement](https://capabilitiestxt.org/implement)\nand hand it to your AI coding agent — it writes your `capabilities.txt` from your code.\n\n**Have an OpenAPI spec?** [Generate it in your browser](https://capabilitiestxt.org/generate)\n(paste the URL) — or keep it current automatically in CI with the\n[GitHub Action](action/):\n\n```yaml\n- uses: capabilityhostprotocol/capabilities-txt/action@main\n  with:\n    openapi: https://api.yoursite.com/openapi.json\n    output: public/capabilities.txt\n```\n\nThen **check it** at [capabilitiestxt.org/submit](https://capabilitiestxt.org/submit)\nfor a grade, fixes, and a badge — and it’s discoverable in the directory + map.\n\nBy hand:\n\n1. List the capabilities your site exposes (or could).\n2. Write them into `/capabilities.txt` using the format above.\n3. Optionally publish `/.well-known/capabilities.json`.\n4. Add yourself to [`adopters.md`](adopters.md) with a pull request.\n\n**Already have an OpenAPI spec?** Generate it — no manual authoring:\n\n```bash\npython tools/from_openapi.py https://api.yoursite.com/openapi.json > capabilities.txt\npython tools/validate.py capabilities.txt   # check it\n```\n\nWorking references — a real, live `capabilities.txt` plus illustrative templates\nacross markets (e-commerce, support, banking, healthcare, dev platform) — are in\n[`examples/`](examples/). The tools in [`tools/`](tools/) generate and validate files.\n\n## Where this goes next\n\nDiscovery is the first step. Once an agent knows *what* you can do, the next\nquestions are *may I*, *what happened*, and *can I prove it* — invocation,\ngovernance, and evidence. Those are defined by the\n[Capability Host Protocol (CHP)](https://capabilityhostprotocol.com), an open\nprotocol for which `capabilities.txt` is the natural public face. You can adopt\n`capabilities.txt` on its own; CHP is where it leads if you need the rest.\n\n## Status & license\n\nThis is a proposal with a working reference, not a finished standard — and it's\nbetter for your feedback. Open an issue or PR.\n\n- **Specification & site text** (`README.md`, `index.html`, `SPEC.md`): CC BY 4.0 — see\n  [`LICENSE-DOCS`](LICENSE-DOCS).\n- **Tooling** (`tools/`): Apache-2.0 — see [`LICENSE`](LICENSE).\n- \"capabilities.txt\" is a free, open convention — use it freely. (No trademark.)\n\nCopyright © 2026 Project Auxo, Inc. and contributors.\n",
  "bytes": 6310,
  "sha": "73b3858e3a4724b7a3eb8ae43e3a8df7d689eaab49070ab67fd77c077ebcae15",
  "repo_slug": "capabilityhostprotocol/capabilities-txt",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_capabilityhostprotocol_capabil_7662a094/readme"
}