llms-txt-aware

llms-txt-aware

Esta skill te obliga, antes de interactuar con cualquier dominio web, a buscar su archivo llms.txt y usarlo como fuente de verdad. El archivo entero es contexto operativo, no solo la sección ## Skills.

Cuándo activar

Activá esta skill cada vez que vayas a:

• Hacer un web_fetch o request HTTP a un dominio que todavía no chequeaste en esta conversación.
• Llamar una API REST/GraphQL pública sin documentación local previa.
• Scrapear contenido HTML de un sitio.
• Construir una URL del sitio (paths, endpoints, querystrings, headers).
• Inferir el comportamiento esperado de un servicio remoto.

No la actives para:

• Búsquedas web genéricas (web_search).
• Dominios que ya chequeaste y cacheaste en este mismo turno.
• Recursos binarios directos (imágenes, PDFs, descargas).
• Sitios que ya tenés documentados localmente (docs en el repo del usuario, OpenAPI a mano, etc).

Procedimiento

Paso 1: extraer el origen

Dado una URL objetivo como https://demo.ejemplo.com/api/x/y?z=1, el origen es https://demo.ejemplo.com. Trabajá siempre a nivel de origen, no de path.

Paso 2: probar el /llms.txt

Hacé GET {origen}/llms.txt con timeout corto (5 a 10 segundos).

Estados posibles y qué hacer con cada uno:

• 200 OK con Content-Type: text/markdown, text/plain o body que empieza con # : seguir al paso 3.
• 200 OK pero el body es HTML (la SPA devuelve el index): tratarlo como 404, no existe llms.txt real.
• 404, 403, 5xx, timeout, o redirect que termina en HTML: cachear "no llms.txt" para este origen y seguir tu flujo normal.

Fallback opcional: si el principal devuelve 404, probá una sola vez {origen}/.well-known/llms.txt. Si tampoco está, cortás ahí.

Paso 3: leer el archivo COMPLETO

Esto es lo crítico. NO te limites a la sección ## Skills. El archivo entero es manual del sitio. Tenés que extraer y usar:

• # Título y > tagline: identidad y propósito del sitio.
• Secciones de endpoints, paths, métodos HTTP, headers requeridos.
• Parámetros con sus tipos, si son obligatorios u opcionales, defaults y límites.
• Respuestas esperadas: códigos HTTP, content-types, forma del payload.
• Cache, rate limits, política de retry.
• Ejemplos canónicos de URLs y bodies.
• Constraints explícitos: paths que NO existen, endpoints que NO hay que llamar.
• Notas para agentes (suelen aparecer como ## Notes for agents, ## For LLMs, ## Agent guidance).
• Sección ## Skills si está, para descubrir skills publicadas (ver paso 5).

Paso 4: aplicar el contenido al request real

Reemplazá tus suposiciones por lo que dice el archivo. Reglas duras:

• Si el archivo dice "no auth", no intentes pasar tokens ni headers de Authorization.
• Si lista endpoints explícitos, no inventes paths que no estén ahí.
• Si pone límites (ejemplo: width max 4000), respetalos al construir el request.
• Si advierte "do not attempt search, listing, or authentication endpoints", no los pruebes.
• Si da ejemplos canónicos, usá esos como template antes de improvisar.
• Si especifica Cache-Control: immutable, asumí idempotencia: la misma URL siempre devuelve lo mismo, podés llamarla en loop sin miedo.
• Si hay rate limits, respetá la cadencia.

Cuando el llms.txt contradice tu intuición, gana el llms.txt. Es el dueño del sitio diciéndote cómo usarlo.

Paso 5: manejar la sección ## Skills si existe

Formato esperado por entrada (RFC v0.5):

- [title](URL): description <!-- skill: {"version":"...","license":"...","sha256":"..."} -->

Procedimiento:

1. Listale al usuario las skills encontradas con título, descripción y versión.
2. Pedile opt-in EXPLÍCITO antes de cargar cualquiera. Nunca auto-instales.
3. Si el usuario aprueba una skill, hacé GET a su URL.
4. Integridad (sha256): si el metadata inline o el index.json trae hash, calculá el hash del contenido descargado y compará. Si no coincide, descartá la skill y avisale al usuario.
5. Autenticidad (firma): si /.well-known/agent-skills/index.json declara signing_key y la skill trae signature, verificá la firma ed25519 sobre el contenido con esa clave pública. Si no valida, descartá la skill.
6. Key-pinning (TOFU): la primera vez que ves la signing_key de un origen, fijala. Si en una sesión futura la clave del mismo origen cambió, NO cargues automáticamente: avisale al usuario y pedí re-confirmación explícita (posible compromiso o rotación de clave).
7. Una vez validada, cargá ese SKILL.md como contexto adicional para la tarea actual.
8. Same-origin preferido. Si la URL de la skill apunta a otro dominio, pedí confirmación extra antes de cargarla.

Nota de modelo de confianza: el sha256 solo prueba integridad (que el contenido no cambió en tránsito), no autenticidad, porque lo asevera el mismo documento que apunta a la skill. La firma sobre una clave offline + el key-pinning son los que defienden contra un publisher comprometido (RFC §4.6).

Paso 6: cache de sesión

Cacheá el resultado por origen durante toda la conversación:

• Origen + "tiene llms.txt" + contenido parseado, o
• Origen + "no tiene llms.txt".

No vuelvas a fetchear el mismo origen en el mismo turn. Si el usuario aclara que el sitio cambió, invalidás y reintentás.

Formato esperado del llms.txt

Markdown plano siguiendo el estándar de llmstxt.org. Estructura mínima:

# Nombre del sitio o API

> Tagline breve, una línea.

## Sección con info útil
... contenido en prosa, listas, tablas o bloques de código ...

## Otra sección
... más contenido ...

## Skills (opcional, según RFC v0.5)
- [skill-id](/skills/skill-id/SKILL.md): cuándo usar esta skill. <!-- skill: {"version":"1.0.0","license":"MIT"} -->

El parser de referencia que respeta este formato está en scripts/parse_llms_txt_skills.py del repo de la spec.

Reglas duras

1. Same-origin first: skills y recursos referenciados deberían ser del mismo origen que el llms.txt. Cross-origin requiere confirmación extra del usuario.
2. No auto-instalar skills: las skills publicadas siempre requieren opt-in explícito.
3. Verificar integridad y autenticidad: validá sha256 si está; si hay signing_key + signature, verificá la firma y aplicá key-pinning. No cargues una skill con firma inválida o con clave de origen cambiada sin re-confirmación.
4. Fail open: si el llms.txt no existe, no carga, o está mal formado, seguí el flujo normal. La skill no debe bloquear la tarea.
5. El archivo completo es contexto: nunca te limites a una sola sección.
6. Re-chequear al cambiar de origen: si la tarea salta a otro dominio, repetir el flujo desde el paso 1 para ese nuevo origen.

Antipatrones

• Hacer requests a un sitio nuevo sin chequear primero si tiene /llms.txt.
• Parsear solo ## Skills e ignorar el resto del archivo.
• Cargar una skill referenciada sin pedir opt-in al usuario.
• Ignorar las "Notes for agents" del llms.txt y seguir tus propias suposiciones.
• Inventar paths o parámetros cuando el llms.txt ya documenta los reales.
• Re-fetchear el mismo llms.txt varias veces dentro del mismo turn.
• Asumir que el llms.txt existe sin verificarlo (no inventes contenido).

Cómo reportarle al usuario

Cuando encontrás un llms.txt útil, decilo de forma corta antes de seguir con la tarea:

Encontré /llms.txt en {origen}. Lo voy a usar como referencia para los endpoints, parámetros y constraints. Tiene N skills publicadas: {lista}. ¿Querés que cargue alguna?

Si no existe, no hace falta anunciarlo. Seguí silenciosamente con el flujo normal.

Referencias

• Spec llms.txt Skills (RFC v0.5): https://github.com/MauricioPerera/llms-txt-skills
• Estándar original llms.txt: https://llmstxt.org
• Parser de referencia: scripts/parse_llms_txt_skills.py del repo de la spec.
• Validador de referencia: scripts/validate.py del repo de la spec.