Referencias, plantillas y progressive disclosure avanzada

En el capítulo 5 vimos cómo calibrar el contenido de SKILL.md. Este capítulo trata el paso siguiente: qué hacer cuando el conocimiento que necesita el agente no cabe en un SKILL.md razonable.

La respuesta del formato no es escribir un archivo más largo. Es partir el conocimiento en capas y dejar que el agente traiga cada capa solo cuando la tarea la pide. Eso es lo que la especificación llama progressive disclosure (divulgación progresiva), y los directorios references/ y assets/ son las herramientas para aplicarla.

El problema concreto: el cuerpo entero se carga de golpe

La especificación es explícita sobre el coste de activar un skill:

Note that the agent will load this entire file once it’s decided to activate a skill. Consider splitting longer SKILL.md content into referenced files.

No hay carga parcial de SKILL.md. Si el agente activa el skill, entra el cuerpo completo: la sección que aplica y las cuatro que no. La guía de buenas prácticas describe la consecuencia: “Every token in your skill competes for the agent’s attention with everything else in that window.”

Son dos efectos, no uno. El primero es coste: tokens gastados en material que no se va a usar. El segundo es ruido: instrucciones que no aplican al caso actual y que el agente puede seguir igualmente. La guía lo señala entre las causas de trabajo improductivo, “instructions that don’t apply to the current task — the agent follows them anyway”.

Un archivo de referencia resuelve los dos a la vez: mientras no se abre, ni cuesta ni distrae.

Las tres capas, vistas como presupuesto

La especificación define la carga progresiva en tres etapas, con su coste asociado:

Etapa	Qué se carga	Cuándo	Coste indicado por la spec
1. Metadata	name y description	Al arrancar, para todos los skills instalados	~100 tokens
2. Instructions	Cuerpo completo de SKILL.md	Al activarse el skill	< 5000 tokens (recomendado)
3. Resources	Archivos de scripts/, references/, assets/	Solo cuando se requieren	Variable

Y la frase normativa que las une:

Agents load skills progressively, pulling in more detail only as a task calls for it. Skills should be structured to take advantage of this.

Ese should —en minúscula en el original, porque la especificación no declara adherencia a RFC 2119— es un DEBERÍA: estructurar el skill para aprovechar la carga progresiva es una recomendación fuerte del formato, no una restricción validable. Lo mismo aplica a las guías de tamaño —“Keep your main SKILL.md under 500 lines. Move detailed reference material to separate files”—: ni las 500 líneas ni los 5000 tokens se validan. Los límites duros siguen siendo los del capítulo 3: 64 caracteres de name, 1024 de description, 500 de compatibility.

flowchart TD
    A["Arranque de sesión<br/>Etapa 1 · Metadata"] --> B{"¿La tarea encaja<br/>con la description?"}
    B -->|No| Z["Coste total: ~100 tokens"]
    B -->|Sí| C["Etapa 2 · Instructions<br/>cuerpo completo de SKILL.md"]
    C --> D{"¿El cuerpo enuncia<br/>una condición de carga<br/>que se cumple ahora?"}
    D -->|No| E["El recurso no se abre<br/>coste cero"]
    D -->|Sí| F["Etapa 3 · Resources<br/>el agente lee el archivo concreto"]
    F --> G["Trabajo con el detalle cargado"]
    E --> G

La observación clave está en la guía de implementación para clientes: un agente con veinte skills instalados no paga veinte juegos de instrucciones por adelantado, solo los que se usan en la conversación. La etapa 3 lleva esa misma lógica dentro de un mismo skill.

references/ y assets/: qué va en cada uno

La especificación abre la sección de directorios opcionales con una cláusula permisiva:

A skill directory may contain any files and directories beyond the required SKILL.md. The conventions below are recommendations for organizing common types of content.

Ese may —también en minúscula en el original— es un PUEDE. Ningún directorio es obligatorio, ni siquiera los tres canónicos: scripts/, references/ y assets/ son convenciones de organización.

references/ — documentación que el agente lee bajo demanda

Contains additional documentation that agents can read when needed:

• REFERENCE.md - Detailed technical reference
• FORMS.md - Form templates or structured data formats
• Domain-specific files (finance.md, legal.md, etc.)

Keep individual reference files focused. Agents load these on demand, so smaller files mean less use of context.

Esa última frase es el criterio de diseño completo: archivos enfocados y pequeños. Un references/todo.md de 3000 líneas anula el beneficio, porque abrirlo cuesta casi lo mismo que haber puesto todo en SKILL.md.

assets/ — recursos estáticos

Contains static resources:

• Templates (document templates, configuration templates)
• Images (diagrams, examples)
• Data files (lookup tables, schemas)

La distinción práctica

	references/	assets/
Naturaleza	Prosa técnica, documentación	Material estático: plantillas, imágenes, datos
Qué hace el agente con ello	Lo lee para decidir cómo actuar	Lo copia, rellena o consulta
Ejemplos de la spec	REFERENCE.md, FORMS.md, finance.md	plantillas de documento, diagramas, tablas de lookup, esquemas
Formato típico	Markdown	Markdown, .docx, .yaml, .json, .csv, .png

La frontera no está normada y hay zonas grises deliberadas: FORMS.md aparece bajo references/ en la spec aunque hable de plantillas. Si dudas, decide por qué hace el agente con el archivo: si lo lee para orientarse, references/; si lo usa como materia prima de la salida, assets/. Un skill que usa las tres capas:

document-review/
- SKILL.md          # Required: metadata + instructions
- references/
  - style-guide.md  # Guía de estilo completa
  - legal-terms.md  # Terminología legal, solo contratos
  - api-errors.md   # Tabla de códigos de error
- assets/
  - report-template.md
  - contract-template.docx
  - schema.yaml
- scripts/
  - validate.py

Cómo se enlaza desde SKILL.md

Regla de la especificación, con su ejemplo literal:

When referencing other files in your skill, use relative paths from the skill root

See [the reference guide](references/REFERENCE.md) for details.

Run the extraction script:
scripts/extract.py

Tres consecuencias prácticas:

1. Nada de rutas absolutas. La guía de scripts lo refuerza: “The agent resolves these paths automatically — no absolute paths needed”. El cliente conoce el directorio base del skill —el padre del SKILL.md— y resuelve contra él.
2. Nada de rutas relativas al directorio de trabajo del usuario. El punto de partida es la raíz del skill, no el proyecto donde se ejecuta.
3. La misma convención vale dentro de los archivos de apoyo. La guía de scripts aclara que las rutas de ejecución en bloques de código siguen siendo relativas a la raíz del directorio del skill, porque el agente ejecuta los comandos desde ahí. Dentro de references/api-errors.md escribes scripts/retry.py, no ../scripts/retry.py.

Un nivel de profundidad

Keep file references one level deep from SKILL.md. Avoid deeply nested reference chains.

Recomendación, no requisito, pero con razón operativa: cada salto es una decisión más que el agente puede no tomar. Una cadena SKILL.md → references/index.md → references/detalle/tabla.md obliga a acertar dos veces seguidas, y si el segundo salto es imprescindible, es señal de que el primer archivo no estaba lo bastante enfocado.

Cómo decide el agente abrir un archivo

Aquí es donde más skills fallan. El enlace no basta: el agente necesita saber cuándo vale la pena pagar la lectura. La guía de buenas prácticas lo dice sin rodeos:

The key is telling the agent when to load each file. “Read references/api-errors.md if the API returns a non-200 status code” is more useful than a generic “see references/ for details.”

<!-- Insuficiente: no hay disparador -->
Consulta references/ para más detalles.

<!-- Insuficiente: condición no observable -->
Lee references/api-errors.md si lo necesitas.

<!-- Correcto: condición observable y verificable -->
Si la API devuelve un status distinto de 200, lee `references/api-errors.md`
antes de reintentar.

La tercera describe un estado del mundo que el agente puede comprobar. Las dos primeras delegan en un juicio difuso que el agente resolverá casi siempre por omisión.

Patrones de disparador que funcionan

Tipo de disparador	Forma	Ejemplo
Por resultado observado	”Si ocurre X, lee Y"	"Si la validación falla, lee references/errores-comunes.md”
Por tipo de entrada	”Cuando el documento sea de tipo X, lee Y"	"Si el documento es un contrato, lee references/legal-terms.md”
Por fase del flujo	”Antes del paso N, lee Y"	"Antes de escribir el informe, lee assets/report-template.md”
Por dato desconocido	”Para resolver X, consulta Y"	"Para el nombre exacto de la tabla, consulta assets/schema.yaml”
Por defecto explícito	”Siempre / nunca"	"No abras references/ salvo que se cumpla una de las condiciones anteriores”

El último fija el comportamiento base y evita que el agente abra archivos “por si acaso”.

El índice de recursos dentro de SKILL.md

La guía de scripts recomienda listar los archivos disponibles “so the agent knows they exist”. El mismo patrón se aplica a referencias y assets, y la versión más útil combina inventario y disparador en una sola línea:

## Recursos disponibles

Carga cada archivo solo si se cumple su condición. No los abras por adelantado.

- **`references/legal-terms.md`** — Terminología legal. Léela solo si el documento
  es un contrato, un NDA o unos términos de servicio.
- **`assets/report-template.md`** — Plantilla del informe final. Cópiala antes de
  redactar la salida.
- **`assets/schema.yaml`** — Esquema de la base de datos. Consúltalo para resolver
  nombres de tabla o de columna.

Qué hace el cliente por su lado

La guía de implementación para clientes explica por qué el disparador es cosa tuya y no del cliente: una herramienta de activación dedicada puede enumerar los archivos de apoyo del directorio del skill, “but it should not eagerly read them. The model loads specific files on demand using its file-read tools when the skill’s instructions reference them”.

El cliente puede listar los recursos, nunca cargarlos por adelantado. La decisión de abrir es del modelo, y la única información que tiene para decidir es la que tú escribiste en SKILL.md.

La misma guía recomienda al implementador poner los directorios de skill en la allowlist de permisos, para que leer un recurso empaquetado no dispare un diálogo de confirmación. Sin eso, “every reference to a bundled script or reference file results in a permission dialog”. Si tu skill con recursos se siente lento en un cliente concreto, esa suele ser la causa, y es del cliente, no del formato.

Estrategia de partición: decidir qué capa merece cada cosa

La pregunta operativa no es “¿esto es largo?” sino “¿en qué fracción de las ejecuciones se usa?”. Cruza esa fracción con el tamaño:

	Se usa casi siempre	Se usa a veces
Corto	SKILL.md	SKILL.md — el ahorro no compensa el salto
Largo	SKILL.md, pero revisa si de verdad se usa entero	references/ o assets/ con disparador

La casilla inferior derecha es la única que gana claramente; en las otras tres pagas un salto de lectura para ahorrar poco.

flowchart TD
    A["Un bloque de contenido<br/>del skill"] --> B{"¿Se usa en casi<br/>todas las ejecuciones?"}
    B -->|Sí| C["Queda en SKILL.md"]
    B -->|No| D{"¿Es largo<br/>o autocontenido?"}
    D -->|No| C
    D -->|Sí| E{"¿El agente reconocerá<br/>el disparador sin ayuda?"}
    E -->|No| F["Queda en SKILL.md<br/>caso típico: gotchas"]
    E -->|Sí| G["Va a references/ o assets/<br/>con condición explícita"]

Lo que nunca debe salir de SKILL.md

La guía de buenas prácticas marca una excepción importante para la sección de gotchas:

Keep gotchas in SKILL.md where the agent reads them before encountering the situation. A separate reference file works if you tell the agent when to load it, but for non-obvious issues, the agent may not recognize the trigger.

El contenido más valioso de muchos skills —los hechos que contradicen las suposiciones razonables— es justo el que no puede vivir en un archivo condicional: el agente no sabe que necesita la advertencia hasta que ya se equivocó. Si la tabla users usa borrado lógico y hay que filtrar por WHERE deleted_at IS NULL, el agente no va a pensar “esto huele a borrado lógico, mejor consulto la referencia”. Va a escribir la query mal.

Regla derivada: el disparador tiene que ser reconocible desde fuera del conocimiento que guarda el archivo. Junto a los gotchas se quedan en SKILL.md el flujo de trabajo y su orden, el inventario de recursos con sus condiciones, los defaults —un default, no un menú de opciones— y las restricciones duras del tipo “nunca emitas datos personales”.

Caso 1: un skill de estilo con guía larga

Escenario: revisión editorial. La guía de estilo del equipo son 900 líneas: tono, glosario, tratamiento de cifras, reglas de titulación, ejemplos aprobados y rechazados. Ponerlas en SKILL.md viola la recomendación de 500 líneas y, peor, carga las reglas de titulación cuando el usuario pide revisar un párrafo suelto.

revision-editorial/
- SKILL.md
- references/
  - tono-y-voz.md         # ~120 líneas
  - glosario.md           # ~400 líneas, tabla de términos
  - cifras-y-unidades.md  # ~90 líneas
  - titulacion.md         # ~150 líneas

La guía no se parte en dos mitades arbitrarias, sino por eje temático, que es lo que permite formular condiciones. SKILL.md:

## Reglas que aplican siempre

- Español neutro. Voz activa por defecto.
- Nunca cambies citas textuales ni nombres propios.

## Referencias

Carga cada archivo solo si se cumple su condición:

- **`references/tono-y-voz.md`** — si el texto es de cara al público: artículo,
  nota de prensa, landing. No hace falta para documentación interna.
- **`references/glosario.md`** — si el texto menciona productos, funciones o siglas
  del dominio. Es la fuente de verdad para nombres y capitalización.
- **`references/cifras-y-unidades.md`** — si el texto contiene números, porcentajes,
  fechas, monedas o unidades de medida.
- **`references/titulacion.md`** — si el texto tiene títulos o subtítulos.

Si ninguna condición se cumple, revisa solo con las reglas de esta página.

## Gotchas

- "Siempre Listo" se escribe con dos mayúsculas y sin guion. Los correctores
  automáticos lo convierten en "siempre listo".
- Los porcentajes van con espacio antes del signo: `40 %`, no `40%`.
- El equipo usa comillas latinas «» en títulos y comillas altas "" en el cuerpo.

Los gotchas se quedan arriba: el agente no reconocería el disparador de ninguno de los tres.

Caso 2: un skill con plantillas de documento

Escenario: generar informes trimestrales. Hay tres formatos distintos según el destinatario, y cada plantilla ocupa entre 80 y 200 líneas.

La guía de buenas prácticas fija exactamente esta decisión:

Short templates can live inline in SKILL.md; for longer templates, or templates only needed in certain cases, store them in assets/ and reference them from SKILL.md so they only load when needed.

Se cumplen las dos condiciones —largas y condicionales—, así que las tres plantillas van a assets/, junto a un scripts/extraer_metricas.py que alimenta las cifras. En SKILL.md, la selección se resuelve con una tabla, no con prosa:

## Elegir plantilla

| Destinatario | Plantilla a copiar |
|---|---|
| Dirección, comité, board | `assets/plantilla-ejecutiva.md` |
| Equipo técnico, postmortem | `assets/plantilla-tecnica.md` |
| Cliente externo | `assets/plantilla-cliente.md` |

Lee **una sola** plantilla, la que corresponda. Si el destinatario no está claro,
pregunta antes de leer ninguna.

Copia la estructura de la plantilla tal cual, incluidos los encabezados y su orden.
No añadas ni elimines secciones de nivel 2.

El “lee una sola” y el “si no está claro, pregunta” son deliberados: sin ellos el agente tiende a leer las tres para comparar, que es justo el coste que la partición quería evitar. Y si la plantilla de cliente contiene secciones legales que deben salir palabra por palabra, dilo en SKILL.md: es el caso donde la guía recomienda ser prescriptivo.

Caso 3: un skill con datos de referencia

Escenario: consultas analíticas sobre un almacén de datos con 60 tablas. El esquema completo son varios miles de líneas, y cada consulta toca dos o tres tablas.

Aquí el recurso no es prosa: es un dato estructurado que el agente consulta puntualmente. Va a assets/, ya que la spec lista explícitamente “Data files (lookup tables, schemas)”. La guía de buenas prácticas usa el mismo patrón en su ejemplo de procedimientos frente a declaraciones —“Read the schema from references/schema.yaml to find relevant tables”— pero lo coloca en references/. Ambas ubicaciones son válidas, porque los directorios son convención y no norma; lo que no es negociable es que el archivo esté enfocado y el enlace lleve condición.

analitica-almacen/
- SKILL.md
- assets/
  - schema-ventas.yaml
  - schema-usuarios.yaml
  - schema-facturacion.yaml
- scripts/
  - explicar_plan.sh

En SKILL.md, un mapa dominio → archivo que evita abrir los tres:

## Esquemas

Antes de escribir SQL, carga **solo** el esquema del dominio implicado:

| Si la pregunta trata de… | Carga |
|---|---|
| pedidos, productos, devoluciones, ingresos | `assets/schema-ventas.yaml` |
| cuentas, sesiones, permisos, actividad | `assets/schema-usuarios.yaml` |
| suscripciones, cobros, impuestos, morosidad | `assets/schema-facturacion.yaml` |

Si la consulta cruza dos dominios, carga ambos esquemas y usa la convención de
clave foránea `_id` para unir.

## Gotchas

- `users` usa borrado lógico. Toda query debe incluir `WHERE deleted_at IS NULL`.
- El identificador es `user_id` en el almacén, `uid` en el servicio de auth y
  `accountId` en la API de facturación. Los tres son el mismo valor.

Dividir el esquema por dominio funciona porque el usuario menciona el dominio en su pregunta. Si el criterio de partición no aparece nunca en la petición, el agente no podrá elegir y acabarás con un skill que carga todo o nada. Parte por el eje que el usuario nombra.

Medir la huella de contexto de un skill

Sin medición, la partición es intuición. Hay tres cosas medibles.

1. La huella permanente: metadata

Es lo que pagas en todas las sesiones, se use el skill o no. La spec la estima en ~100 tokens y la guía de clientes en ~50-100 tokens por skill. Lo que sí puedes medir con exactitud es el límite duro de 1024 caracteres:

awk '/^description:/{sub(/^description: */,""); print length($0)}' SKILL.md

El capítulo 6 trata la optimización de este campo. Aquí solo importa que es el único coste que no puedes evitar.

2. La huella de activación: el cuerpo de SKILL.md

Es lo que pagas cada vez que el skill se activa:

# Líneas totales (recomendación de la spec: < 500)
wc -l SKILL.md

# Líneas y caracteres solo del cuerpo, descontando el frontmatter
awk 'BEGIN{d=0} /^---$/{d++; next} d>=2' SKILL.md | wc -lc

Sobre los tokens: la recomendación de la spec es < 5000 para el cuerpo, pero la especificación no define ninguna conversión de caracteres a tokens, así que cualquier regla de tres es una aproximación tuya y no del formato. Para una cifra real, mide con el tokenizador del modelo que vayas a usar o con el conteo de la propia ejecución.

3. La huella real de ejecución: tokens medidos

Es la única cifra que incluye los recursos que el agente decidió abrir. La guía de evaluación registra por cada corrida un timing.json con total_tokens y duration_ms, y su patrón central es correr cada caso dos veces: una con el skill y otra sin él. El agregado por iteración incluye un bloque delta, y su interpretación es literal:

The delta tells you what the skill costs (more time, more tokens) and what it buys (higher pass rate).

Ese es el número que valida o refuta tu partición. Si mueves 400 líneas a references/ y el total_tokens medio no baja, el agente estaba abriendo el archivo igualmente: tu condición era demasiado laxa. Si baja mucho pero la tasa de acierto cae, era demasiado estricta y el agente se quedó sin información que necesitaba. El capítulo 9 desarrolla el montaje completo de evals.

Inventario y validación

# Tamaño de cada recurso, de mayor a menor
find . -type f -not -name SKILL.md -exec wc -l {} + | sort -rn

# Validación del formato, con la librería de referencia que indica la spec
skills-ref validate ./mi-skill

skills-ref comprueba el frontmatter y las convenciones de nombres. No mide contexto ni verifica que tus enlaces a references/ existan: eso queda de tu lado.

Presupuesto de trabajo

Concepto	Referencia	Cómo lo compruebas
description	≤ 1024 caracteres (duro)	awk sobre el frontmatter
Cuerpo de SKILL.md	< 500 líneas y < 5000 tokens (recomendado)	wc -l y tokenizador del modelo
Cada archivo de references/	”focused”, sin cifra en la spec	wc -l, y revisa si necesita partirse
Profundidad de enlaces	1 nivel (recomendado)	inspección del árbol
Coste real por tarea	sin referencia fija	total_tokens con y sin skill

Antipatrones

Antipatrón	Por qué falla	Corrección
”Consulta references/ para más detalles”	No hay condición; el agente casi nunca abre	Enunciar el estado observable que dispara la lectura
Un único references/todo.md gigante	Abrirlo cuesta lo mismo que no haber partido	Partir por eje temático, uno por condición
Mover los gotchas a un archivo de referencia	El agente no reconoce el disparador de lo que no sabe	Los gotchas se quedan en SKILL.md
Cadenas de índices anidados	Cada salto es una decisión que puede fallar	Un nivel desde SKILL.md
Rutas absolutas, o ../scripts/x.py dentro de references/	Todo se resuelve desde la raíz del skill	scripts/x.py
Listar cinco plantillas sin decir cuántas leer	El agente las lee todas para comparar	”Lee una sola, la que corresponda”
Partir por un eje que el usuario nunca menciona	El agente no puede elegir; carga todo o nada	Partir por el vocabulario de la petición
Vaciar SKILL.md hasta dejarlo en un índice	Se pierde el flujo y los defaults; el agente navega a ciegas	El flujo principal y los defaults se quedan

Cómo encaja con el resto del curso

• Los scripts son la otra mitad de la etapa 3 y siguen las mismas reglas de ruta relativa e inventario explícito: capítulo 7.
• Al empaquetar y distribuir un skill con recursos, todo el directorio viaja junto: ver capítulo 10 y el curso hermano Agent Plugins Spec, que cubre cómo se agrupan skills y servidores MCP en un plugin instalable.
• Para ver particiones reales y a qué tamaño llegan sus references/, el catálogo de Google Skills es un buen banco de ejemplos.

Resumen

• El cuerpo de SKILL.md se carga entero al activarse el skill; la spec recomienda mantenerlo bajo 500 líneas y 5000 tokens y mover el material detallado a archivos aparte. Ambas cifras son recomendaciones, no límites validados.
• references/ guarda documentación que el agente lee bajo demanda; assets/ guarda recursos estáticos: plantillas, imágenes y archivos de datos. Ambos son convenciones opcionales: un directorio de skill PUEDE (may) contener cualquier archivo adicional.
• Los enlaces usan rutas relativas desde la raíz del skill, un solo nivel de profundidad, y la misma convención rige dentro de los archivos de apoyo.
• Enlazar no basta: hay que decir cuándo cargar cada archivo con una condición observable. “Lee X si la API devuelve un status distinto de 200” funciona; “consulta references/” no.
• El criterio de partición es frecuencia de uso cruzada con tamaño: solo gana claramente lo largo y ocasional. Y parte por el eje que el usuario menciona en su petición, o el agente no podrá elegir.
• Los gotchas se quedan en SKILL.md: si el agente necesitara el contenido del archivo para saber que debe abrirlo, ese contenido no puede vivir en un archivo condicional.
• Mide tres cosas distintas: la huella permanente de la description, la huella de activación del cuerpo y la huella real de ejecución vía total_tokens con y sin skill. El delta entre ambas corridas es lo que valida la partición.
• El cliente puede listar los recursos empaquetados, pero no debe leerlos por adelantado. La decisión de abrir es del modelo, con la información que tú escribiste.

Siguiente: Evaluar la calidad de un skill con evals