Buildkite is Good to agents.

What we found

• —An agent can reach Buildkite the way it's designed to be reached: Buildkite ships an official MCP server (managed remote + local, on the Docker MCP catalog, Smithery and Glama), a dedicated coding-agents skills repo, and a 'Getting started with coding agents' guide — very few APIs document agent onboarding this deliberately.
• —Documentation is near-perfect for comprehension: every doc page is available as clean Markdown (append .md), a rich 107KB llms.txt indexes the whole corpus with per-section descriptions, headings nest cleanly, and endpoint pages lead with method/URL/purpose — an agent can parse it without loss.
• —The single biggest gap is discovery-side: there is no official machine-readable OpenAPI/Swagger spec for the REST API, so an agent that wants a typed contract must scrape the HTML/Markdown reference or rely on unofficial community specs.
• —Error recovery is genuinely agent-usable: the listing endpoint returns a 400 that literally tells you how to fix it ('narrow your query using filters such as branch or created_from'), 422s return a structured errors array, and the rate-limit docs specify exact backoff behavior.
• —robots.txt places no restrictions on AI crawlers (GPTBot, ClaudeBot, CCBot, etc. all pass), and the API surface is discoverable — but llms-full.txt returns 403 and there is no .well-known/mcp.json, leaving two low-weight discovery signals unmet.

What to change

Prioritized by impact on discoverability. You (or your docs platform) deploy these — Discry never touches your API.

1. 01Publish an official, versioned OpenAPI 3.x spec for the REST API at a stable URL (e.g. buildkite.com/docs/apis/rest-api/openapi.json) and link it from the API overview. This is the highest-impact discovery fix — it's the single largest rubric weight and currently scores zero.
2. 02Serve a working llms-full.txt (or fix the 403 on the existing path). Buildkite already generates per-section llms.txt files, so a consolidated agent-optimized dump is a small step that closes a discovery gap.
3. 03Trim or split the root llms.txt: at 107KB it exceeds the ~50KB/12K-token comfort zone for a single agent read. Keep the high-value API-focused index and rely on the per-section files for depth so llms.txt quality moves from partial to pass.
4. 04Add per-endpoint code examples in at least one additional language (e.g. Python or JavaScript) alongside curl. Examples are highly realistic and copy-pasteable today, but curl-only limits polyglot agents.
5. 05Ensure documentation pages (docs.buildkite.com / /docs paths) are explicitly enumerated in the sitemap index so crawlers that rely on sitemaps — not just llms.txt — can discover the full reference.