breim/ax-kit

AX Kit

La UX es la experiencia de un humano. La Experiencia del Agente (AX) es la experiencia de un agente de IA que utiliza un producto para una persona. Un agente no tiene ojos, no tiene paciencia para un CAPTCHA y no tiene a quién preguntar. Solo puede usar lo que el producto expone a una máquina.

Esta habilidad mejora la capa orientada a agentes de un sitio, una API, una aplicación SaaS o una tienda. Implementa los estándares que los agentes utilizan y mide el resultado con un escáner. El puntaje es la retroalimentación del trabajo. El puntaje no es el objetivo.

Configuración

<directorio-habilidad> es el directorio que contiene este SKILL.md. Mantén el directorio de trabajo en el proyecto del usuario.

El escáner es <directorio-habilidad>/scripts/ax.mjs. Necesita Node.js 18 o posterior y no tiene dependencias.

node <directorio-habilidad>/scripts/ax.mjs scan <url> --profile <content|api|webapp|commerce> --json

Si node falta o es anterior a la versión 18, indícaselo al usuario. Luego continúa con los libros de jugadas y sin el escáner.

Comandos

Encuentra el comando en la solicitud del usuario. Luego lee la guía de ese comando y síguela.

Comando	Úsalo cuando el usuario quiera	Guía	Edita código
improve	Mejorar el producto para agentes, con un bucle de escaneo, corrección y verificación	references/improve.md	Sí
add <capacidad>	Implementar una capacidad, por ejemplo llms-txt o mcp-server	references/add.md	Sí
audit <url>	Obtener un diagnóstico completo y un informe, sin cambios	references/audit.md	No
score <url>	Obtener rápidamente el Puntaje AX y las principales brechas	references/score.md	No
design	Revisar una API, sitio o característica planificada antes de que exista el código	references/design.md	No
ci	Agregar una compuerta de pipeline en el puntaje y una insignia	references/ci.md	Sí

Si la solicitud no nombra un comando y no puedes inferir uno, muestra esta tabla y pregunta qué comando desea el usuario. No comiences a trabajar desde el menú.

Reglas que aplican a todos los comandos

Estas reglas son más fuertes que los archivos de referencia.

1. Confirma antes de editar. Obtén el acuerdo del usuario dos veces. Primero, acuerden las brechas a cerrar. Luego lee los libros de jugadas y muestra los archivos exactos que cambiarás. Edita solo después del segundo acuerdo.
2. Mantente de solo lectura en un sitio en vivo. Envía solo solicitudes que lean datos. No crees una cuenta, envíes un formulario ni compres nada. El propietario del sitio puede aprobar una excepción en palabras claras. El escáner envía un POST: una solicitud server/discover a /mcp. Esa solicitud solo lee datos.
3. Pregunta antes de usar un escáner externo. Un escáner alojado recibe la URL. Obtén el consentimiento primero.
4. Protege la seguridad. No deshabilites la protección contra bots, abras CORS para datos privados ni expongas contenido privado para aumentar un puntaje. Cada libro de jugadas tiene notas de seguridad. Obedécelas. Si una página humana tiene un CAPTCHA, mantenlo. Agrega una ruta separada para agentes, por ejemplo, claves de una API, con controles de abuso.
5. Respeta la política de bots del propietario. Un bloqueo a los rastreadores de entrenamiento de IA es una decisión válida. No la cambies a menos que el usuario lo solicite.
6. Verifica la fecha de un estándar. Cada libro de jugadas tiene una fecha de Revisado. Si esa fecha tiene más de 6 meses, lee la fuente principal antes de implementar.
7. Reporta la verdad. Muestra el puntaje, la cobertura y cada verificación que el escáner no evaluó. No muestres una verificación no evaluada como aprobada.
8. Corrige la causa. No agregues un archivo solo para satisfacer una verificación. Un llms.txt con enlaces incorrectos es peor que ningún archivo.

Los siete pilares

Los pilares siguen el recorrido de un agente. Una falla en un pilar temprano bloquea los pilares posteriores.

Pilar	Pregunta	Libros de jugadas
Alcance	¿Puede un agente obtener una respuesta y la política de bots es explícita?	bot-access
Descubrimiento	¿Puede un agente encontrar lo que existe?	llms-txt, sitemap-and-links, api-catalog, agent-discovery
Lectura	¿Puede un agente entender el contenido sin navegador?	markdown-for-agents, server-rendering, structured-data
Acción	¿Puede un agente llamar al producto?	openapi-quality, mcp-server, webmcp, api-design
Autorización	¿Puede un agente obtener acceso sin intervención humana?	oauth-for-agents, self-serve-access
Recuperación	¿Puede un agente corregirse después de un error?	errors-and-limits
Transacción	¿Puede un agente pagar?	agentic-commerce

Cada libro de jugadas es el archivo references/<nombre>.md.

Perfiles

Un perfil le indica al escáner qué verificaciones aplicar. Proporciona el perfil con --profile. Si lo omites, el escáner lo detecta.

Perfil	Objetivo
content	Un sitio de marketing, un sitio de documentación o un blog
api	Una API HTTP
webapp	Una aplicación SaaS con cuentas
commerce	Una tienda

Un producto puede tener más de una superficie. Escanea cada superficie con su propio perfil. Ejemplo: escanea example.com como content y escanea api.example.com como api.

Para una API, proporciona la URL que responde por toda la API. Si la raíz del host responde con la API, usa la raíz del host. Si la API está debajo de una ruta como /api/v1 y la raíz del host sirve otra cosa, usa esa ruta. El escáner busca la descripción de la API en las ubicaciones conocidas del host y junto a la URL que proporcionas.

Cómo leer la salida del escáner

El informe JSON tiene tres grupos de verificaciones.

Grupo	Contenido	Efecto en el puntaje
score	Verificaciones medidas en estándares estables	Todo el puntaje
review	Verificaciones que necesitan juicio, por ejemplo "un agente puede obtener una clave de API sin CAPTCHA"	Ninguno. Tú las evalúas.
watch	Estándares emergentes, rutas heredadas y observaciones	Ninguno

• score es un límite inferior verificado de 0 a 100. upperBound es el puntaje si cada verificación no evaluada pasa.
• coverage muestra cuánto del puntaje pudo evaluar el escáner. Un tiempo de espera lo disminuye.
• grade es null cuando score y upperBound están en diferentes bandas de calificación.
• cap se establece cuando falla una compuerta. Una compuerta falla cuando una solicitud simple recibe un desafío de bot, o cuando la página no tiene contenido sin JavaScript. El límite es 59.
• opportunities enumera los puntos que cada corrección puede agregar, del más grande al más pequeño. Tiene todas las brechas. La salida de texto muestra solo las primeras 8.
• Cada verificación tiene un playbook. Ese es el archivo de referencia con la corrección.
• Una verificación con blockedBy falló porque otra verificación falló primero. Su estado es fail, no not_assessed, por lo que no disminuye la cobertura. Corrige primero la verificación en blockedBy.
• review enumera las verificaciones de Revisión que aplican al perfil. Evalúa solo estas.

Sin --json, el escáner imprime un informe de texto breve con la línea del puntaje y la línea del pilar. Usa el informe de texto para el usuario y el JSON para tu trabajo.

Códigos de salida: 0 ok, 1 compuerta fallida, 2 error de uso, 3 compuerta no concluyente, 4 sin puntaje, 5 error interno.

node <directorio-habilidad>/scripts/ax.mjs catalog --json imprime el catálogo. Cada entrada de su arreglo checks tiene un bucket. Una verificación de Revisión también tiene una rubric con los miembros pass, partial, fail y evidence.

Mantén un informe JSON en la conversación o en un directorio temporal fuera del proyecto. No lo escribas dentro del proyecto a menos que el usuario lo solicite.

Para la fórmula, lee references/scoring.md. Para la lista de verificaciones, lee references/checks.md.

Archivos de referencia

Lee un archivo solo cuando la condición sea verdadera.

Archivo	Léelo cuando
references/stacks.md	Debas encontrar dónde va un archivo, un encabezado o una ruta en el framework del proyecto
references/standards.md	Debas saber si un estándar es estable, emergente o heredado, o si una ruta cambió su nombre
references/checks.md	Necesites el significado de un ID de verificación o la rúbrica de una verificación de Revisión
references/scoring.md	El usuario pregunte cómo funciona el puntaje
references/<libro-de-jugadas>.md	Implementes o expliques la capacidad de ese libro de jugadas

Las plantillas para archivos comunes están en <directorio-habilidad>/assets/. Cada libro de jugadas nombra la plantilla que utiliza.