Documentación hecha para agentes de IA, no solo para personas

Clásica documentación hecha para la humanidad: HTML renderizado, resaltado de sintaxis, menú lateral, búsqueda. Pero cada vez más, la documentación no es para la humanidad, sino para agentes: Claude, Cursor, ChatGPT. A ellos les fastidia el renderizado, les necesitan un texto puro y un contrato que pueda ser leído por máquinas.

Hemos hecho la documentación para que sea adecuada para ambos. Aquí está lo que hay detrás de la escena.

Cada página de la documentación tiene un duplicado original en Markdown en el mismo camino con un sufijo .md. Al abrir /agent-setup, hay también /agent-setup.md, el mismo texto sin el envoltorio HTML, los importes MDX eliminados, se entrega como text/markdown.

Esto alimenta dos acciones en el menú de la página: Copiar como Markdown (pone el texto puro en el portapapeles para que puedas pegarlo en el chat con el modelo) y Ver como Markdown (abre la versión .md directamente). Al agente no le hace falta parsear el DOM, simplemente toma el texto puro.

En la esquina superior derecha de cada página, hay un menú de acciones hecho específicamente para el flujo de trabajo del agente:

• Copiar como Markdown - el texto puro de la página en el portapapeles
• Ver como Markdown - abrir el duplicado .md
• Abrir en ChatGPT - enviar la página a ChatGPT con un solo clic
• Abrir en Claude - lo mismo para Claude
• Conectar MCP - ir a la configuración del servidor MCP

En lugar de “copiar la URL, abrir el chat, pedirle que vaya a la página”, hay una sola acción.

Según el estándar llmstxt.org, entregamos dos archivos:

• /llms.txt - el índice de todas las páginas de documentación, agrupadas en secciones (API Reference, Use Cases, Ejemplos, Productos). La guía para el agente, desde donde empezar.
• /llms-full.txt - toda la documentación en un archivo plain-text. Para la indexación offline en una base de vectores o para insertar en el contexto de la modelo.

Si estás construyendo un RAG sobre nuestro API, llms-full.txt es el corpus listo, no necesitas hacer scraping del sitio.

El contrato se entrega en varias formas para diferentes herramientas:

• /v1/openapi.json - la especificación OpenAPI 3.1 canónica con ejemplos y code-samples. Para la generación de código de clientes y cualquier herramienta de OpenAPI.
• Alias de Swagger - /v1/swagger.json, /v1/v3/api-docs y otros 301-redirigen a la canónica, para que las herramientas que buscan las rutas convencionales no se desvíen.
• Colección de Postman - /postman/astroway-api.json para importar en Postman con un solo clic.

La página /agent-setup/ - no es un guía general, sino instrucciones específicas para siete clientes: Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Cline, Codex. Cada una da el configuración exacta y un ejemplo de curl tools/list para probar la conexión antes de escribir código.

En las páginas de la documentación de API, cada operación tiene un widget try-it incorporado: insertas la clave de sandbox, editas el cuerpo del request, pulsas “Send” - y ves la respuesta real sin salir de los docs. El método, la ruta y el ejemplo del cuerpo se toman del snipeta de curl generado, por lo que el widget no hace peticiones adicionales a openapi.json.

La idea simple: si tu producto es una API, la documentación debe ser adecuada no solo para leer con los ojos, sino también para ser consumida por un agente. La mitad de las integraciones hoy en día comienzan con el desarrollador enviando un enlace a los docs en Claude o Cursor y pidiendo “conecta esto”. Hemos hecho que en el otro extremo haya un texto puro y un contrato que pueda ser leído por máquinas, no HTML que deba ser desglosado.