APS Docs Skill: dar a Codex un camino hasta la documentación oficial
Cuando pido a un agente que consulte mis proyectos de Autodesk, quiero poder seguir de dónde sale la ruta que propone. Con APS Docs Skill el primer trabajo consiste en encontrar la referencia oficial y leerla antes de escribir código. Me interesa ese orden: una llamada que parece correcta puede estar mezclando una versión, un permiso o un ejemplo que no corresponde.
La presentación de Autodesk explica cómo dar al agente ese acceso a la documentación. Aquí sigo el recorrido manual para localizar la consulta de proyectos y comprobar su ruta y su permiso. No he instalado una skill activa ni ejecutado esa consulta contra APS en este ejercicio.
Tabla de contenidos
El problema empieza cuando una página descargada no contiene la referencia
El portal APS se presenta al lector como una web en la que navegar por servicios, guías y operaciones. Sin embargo, descargar la dirección visible no siempre proporciona al agente el contenido que estás viendo. Parte del portal funciona como una aplicación web y su HTML inicial puede contener la estructura necesaria para cargar la página, sin incluir la referencia técnica. Una descarga que termina correctamente no demuestra que se haya obtenido la tabla de parámetros que necesitamos.
Esta diferencia explica un fallo frecuente en la investigación con agentes. El sistema encuentra una URL con aspecto correcto, recibe una respuesta HTTP válida y continúa redactando como si hubiera leído la documentación. Puede acabar completando de memoria lo que faltaba en la descarga. La solución no consiste en pedirle que esté más seguro, sino en darle un método para localizar y extraer el contenido técnico real, conservando el enlace que una persona pueda abrir después.
El recurso llms.txt de APS ofrece vocabulario y un procedimiento para orientar esa consulta. El skill del repositorio oficial organiza también instrucciones y requisitos de herramientas. No equivale a tener todo el portal dentro de un archivo: ayuda a reconocer la familia de APIs, consultar su índice y llegar a una página concreta. Esa diferencia permite actualizar o revisar la información sin convertir cada conversación en una copia de miles de líneas.
Para el ejemplo de proyectos, primero hace falta interpretar qué significa un hub y situar la consulta en Data Management. Después se localiza en el índice la página que describe la colección de proyectos de ese hub. Leer sus encabezados permite reconocer si estamos ante una guía general, un tutorial o la referencia de una operación. Solo entonces tiene sentido extraer la información que responde a la pregunta, en lugar de procesar toda la web esperando que aparezca la respuesta.
El índice también resuelve una dificultad menos visible: el enlace de navegación del portal y la ubicación estática del contenido no tienen por qué construirse igual. Reconstruir una URL a partir de un nombre de archivo puede producir un enlace que parezca razonable y no corresponda a la página. El recorrido verificable conserva la relación indicada por el índice. Para el lector, el resultado debería ser una fuente oficial navegable que permita comprobar la afirmación, sin tener que entender la estructura interna del portal.
Instalar un recurso de consulta sin cambiar las reglas del proyecto
Un skill reúne instrucciones y, cuando hace falta, archivos de apoyo o scripts. Su función en este caso es orientar la consulta de documentación. No necesita credenciales de Autodesk para explicar una ruta pública, y su instalación no debería interpretarse como permiso para utilizar los secretos del proyecto o ejecutar llamadas reales. Separar esos ámbitos permite incorporar ayuda documental sin ampliar automáticamente el alcance del trabajo del agente.
La documentación vigente de Codex contempla skills de repositorio dentro de .agents/skills. Una ubicación como .agents/skills/aps-docs-portal/ puede conservar el archivo SKILL.md y las referencias necesarias. Antes de copiarlo, hay que leer su contenido y comprobar los requisitos de herramientas del recurso elegido. Una instalación incompleta puede ser reconocida por el agente y fallar después al intentar extraer una página.
El artículo original de junio mostraba distintas formas de incorporar el contenido a las instrucciones del agente. Para un repositorio que ya dispone de AGENTS.md, conservar el recurso como un skill separado evita mezclar documentación de APS con decisiones propias sobre código, pruebas y operaciones autorizadas. También permite actualizar ese recurso sin sustituir las instrucciones del proyecto. La ubicación documentada hoy por Codex y el ejemplo histórico de instalación deben distinguirse al reproducir el recorrido.
Conviene comprobar si ya existe una copia con el mismo nombre en otro ámbito. Codex puede descubrir skills desde distintas ubicaciones y no fusiona automáticamente los que comparten nombre. Dos versiones parecidas dificultan saber cuál ha leído el agente y qué comportamiento estás evaluando. Para una primera comprobación resulta más útil una única instalación identificada que un catálogo amplio de recursos solapados.
Una vez disponible la skill en el entorno que utilices, comprueba que el agente puede localizar una referencia concreta y devolver su enlace. Esa primera tarea permite revisar la instalación antes de pedirle una implementación completa.
Seguir una pregunta hasta el endpoint y sus requisitos
El ensayo documental partió de una pregunta acotada: cómo consultar los proyectos de un hub y qué scope necesita esa operación. Primero se identificó Data Management como familia relevante; después se leyó su índice y se localizaron las entradas de hubs y proyectos. Por último se extrajo el contexto de las páginas técnicas correspondientes. La evidencia conservada permite reconstruir ese recorrido, en lugar de depender únicamente de una respuesta final del agente.
La referencia de proyectos de un hub identifica GET /project/v1/hubs/{hub_id}/projects y el scope data:read. La referencia de hubs proporciona el paso anterior para localizar esos contenedores. El identificador del hub se obtiene del resultado correspondiente; no debería inventarse a partir del nombre visible de una empresa o copiarse de un ejemplo como si fuera válido para cualquier cuenta.
Aquí aparece un detalle que ayuda a evitar errores al generar código: el portal de Data Management v2 describe una ruta REST con /project/v1/. Esos números pertenecen a referencias distintas y no tienen por qué coincidir. Cambiar la ruta a /project/v2/ para hacerla parecer coherente con la URL documental sería modificar el contrato de la API sin ninguna evidencia. El agente necesita conservar los valores de la operación, no normalizarlos según una intuición de nomenclatura.
El resultado documental todavía deja abiertas varias preguntas de integración. Hay que revisar qué contexto de autenticación acepta la operación, qué permisos tiene la identidad utilizada y cómo se trata la paginación. Encontrar el scope requerido no demuestra que una cuenta pueda leer cualquier proyecto. Del mismo modo, una primera respuesta con datos no acredita que se hayan recorrido todos los resultados disponibles. Esas condiciones deben acompañar al endpoint cuando se propone su implementación.
La salida que buscamos en este ejercicio es pequeña: ruta, permiso y enlace a la referencia que los respalda. Con esos tres datos ya podemos revisar la propuesta antes de introducir credenciales o hacer una petición real.
Pedir código después de poder revisar de dónde sale
Un encargo útil puede pedir primero la operación, la fuente oficial y los requisitos de autenticación, paginación y errores, indicando que todavía no se ejecuten llamadas con credenciales. El primer resultado es así una decisión revisable. Si la familia de API es incorrecta, se detecta antes de que aparezca una aplicación entera construida a su alrededor. Este orden también permite a quien está aprendiendo entender qué parte del resultado procede de la documentación y qué parte propone el agente.
Con esa base se puede solicitar una implementación pequeña que separe la petición HTTP, la validación de la respuesta y el tratamiento de fallos. Por ejemplo, una prueba con datos simulados puede comprobar qué ocurre cuando falta una colección esperada o cuando el proveedor rechaza la autorización. Sirve para revisar la lógica local sin acceder a una cuenta. La integración real necesita después sus propias comprobaciones; una simulación correcta no valida credenciales ni permisos del entorno Autodesk.
La trazabilidad documental también mejora las correcciones. Si el agente propone un parámetro dudoso, puedes volver a la página que supuestamente lo respalda y comprobar el contexto. Tal vez ha interpretado mal una tabla, utilizado un ejemplo de otra operación o omitido una condición. Conservar la fuente hace que la discusión pueda resolverse sobre una referencia concreta. Repetir «revisa el código» sin aclarar qué debe comprobar suele producir otra redacción de la misma incertidumbre.
Para Revit de escritorio, la referencia tiene otra procedencia. dll2llm genera material desde ensamblados .NET de una instalación, mientras APS Docs Skill orienta la lectura de servicios cloud. Ambos pueden aportar contexto, pero responden a problemas distintos. Una firma encontrada en la API de Revit no demuestra que exista una operación REST equivalente, ni una consulta de proyectos abre acceso directo al documento activo del escritorio.
En Issues Manager, la entrega del login solo necesita leer el perfil. La consulta de proyectos incorpora después data:read y la integración de la aplicación en la cuenta. Es un ejemplo de por qué quiero comprobar los requisitos del endpoint antes de aprovechar una conexión que ya funciona.
Antes de seguir, abre la referencia que cita el agente y busca allí la operación y sus requisitos. Si esa comprobación falla, toca corregir la búsqueda antes de pedir más código. La skill resulta útil cuando facilita ese contraste; ese es el criterio con el que puedes evaluar su aportación a tu proyecto.
Respuestas