guide

Generate capabilities.txt from your OpenAPI

By Project Auxo · 2026-06-28

TL;DR. If you already publish an OpenAPI description, you can generate a conformant capabilities.txt from it automatically. The generator groups your operations by tag into capability categories, derives a stable id for each from its operationId (or path + method), and writes a one-line description per capability. Paste your OpenAPI URL into the hosted generator, or run tools/from_openapi.py from the command line, then review, publish, and check it.

Why generate, not hand-write

Your OpenAPI document already encodes the two things a capabilities.txt needs: a list of operations and a short description of each. Generating from it means your declaration starts complete and accurate, stays consistent with your real API, and can be regenerated whenever the API changes. Hand-writing is fine for a handful of capabilities; generation is how you keep it honest at scale.

Option A — the hosted generator

The fastest path. Open the generator, paste your OpenAPI URL (or your domain — it will try the common locations), and it returns a ready capabilities.txt with a copy button and publish instructions. Nothing to install.

Option B — the command line

It is a single deterministic script — good for CI or local use:

# from a hosted OpenAPI URL python tools/from_openapi.py https://api.yoursite.com/openapi.json > capabilities.txt # from a local file python tools/from_openapi.py ./openapi.json > capabilities.txt # or pipe it in cat openapi.json | python tools/from_openapi.py - > capabilities.txt

What the output looks like

Operations grouped by tag become categories; each operation becomes a capability with a stable id and its summary:

# capabilities.txt > One sentence: what this host is and the capabilities it offers. > Structured form: https://yoursite.com/.well-known/capabilities.json ## Orders ### Orders (orders) - orders.create_order (v1.0.0) — Place a new order - orders.get_status (v1.0.0) — Check an order's status ## Inventory ### Inventory (inventory) - inventory.check_stock (v1.0.0) — Check availability for a SKU

The ids come from your operationIds (or path + method as a fallback); the descriptions come from each operation's summary. Cleaner OpenAPI in, cleaner capabilities.txt out.

Review, then publish

Treat the generated file as a first draft: prune internal endpoints, tidy descriptions, and confirm the summary blockquote points at your real invocation endpoint. Then publish at https://yoursite.com/capabilities.txt and run a conformance check for a grade and a badge.

Keep it in sync

Because generation is deterministic, wire it into CI (or use the GitHub Action) to regenerate the file whenever your OpenAPI changes — the same discipline you already apply to generated SDKs and docs.

What does the generator do with my OpenAPI spec?

It reads your OpenAPI 3.x document, groups operations by their tag into capability categories (## headings), and emits one capability per operation. Each capability gets a stable id derived from its operationId — or from the path and HTTP method when no operationId is present — plus the operation summary as its one-line description. The output is plain markdown that conforms to the capabilities.txt format.

My operations have no operationId — will it still work?

Yes. When an operationId is missing, the generator derives a readable id from the HTTP method and path (e.g. GET /orders/{id} becomes something like orders.get_orders_id). It is worth adding operationIds to your spec, though — they produce cleaner, more stable capability ids that will not churn if you reorganize routes.

Should I publish every operation as a capability?

Not necessarily. The generator gives you a complete first draft; then prune it. capabilities.txt is an advertisement of what an agent can usefully do, not an exhaustive route dump. Keep the consequential and commonly useful operations, drop internal or administrative endpoints you do not want agents reaching for.

How do I keep it in sync as my API changes?

Regenerate it in CI. Because the generator is deterministic and runs from your OpenAPI, you can wire it into your build (or the GitHub Action) so the capabilities.txt is regenerated whenever your spec changes — the same way you would regenerate client SDKs.

What if I do not have an OpenAPI spec at all?

Use the implement prompt instead: hand it to your AI coding agent and it reads your actual routes and writes the capabilities.txt directly. The OpenAPI path is the fastest when a spec exists; the prompt path covers everything else.

Next steps

Open the generator The full 10-minute guide The well-known files explained