Contenido detallado
🪜 Qué es progressive disclosure
Revelación progresiva (revelación progresiva) es un principio tomado del diseño
de interfaces: muestra primero solo lo esencial y revela los detalles únicamente cuando sean necesarios. En una skill, esto significa
que SKILL.md carga el flujo principal, y el
conocimiento profundo queda guardado en archivos que solo se leen bajo demanda.
🪜 Por qué esto importa
Todo lo que entra en el SKILL.md cuesta contexto cada vez que se activa la skill, incluso si esa ejecución específica no va a usar ese detalle.
- •Capa 1 — siempre visible: la description (en el índice).
- •Capa 2 — al activarse: el cuerpo del SKILL.md.
- •Capa 3 — bajo demanda: los archivos de
references/,scripts/,assets/.
💡 Consejo práctico
Piensa en el manual de un producto: la portada dice qué es, el índice muestra los capítulos y solo lees el capítulo 7 cuando necesitas el capítulo 7. Una skill bien estructurada funciona igual: no te pone todo el libro delante.
📚 La carpeta references/
La carpeta references/ guarda el conocimiento
profundo de la skill: plantillas HTML, sistemas de diseño, tablas de colores, listas de verificación, ejemplos largos. Son cosas que
harían que el SKILL.md gigantesco si quedaran inline, y que no toda ejecución lo necesita.
minha-skill/
├── SKILL.md ← enxuto: fluxo + roteamento
└── references/
├── DESIGN-REFERENCE.md ← paleta, componentes, tokens
├── TEMPLATE.md ← esqueleto da saída
└── CHECKLIST.md ← revisão antes de entregar📊 Un caso real
El generador de itinerarios que el curso analiza mantiene un documento de Design System por separado, con paleta, tipografía y una biblioteca de 12 componentes (banner principal, tarjetas de vuelos, selector de días, desglose del presupuesto...). El SKILL.md solo dice «sigue el sistema de diseño»; no repite todo esto en línea.
Resultado: el archivo principal queda legible y el detalle más extenso solo se incluye en el contexto cuando realmente se va a construir la página.
💡 Consejo práctico
Regla práctica: si un bloque de tu SKILL.md supera ~40 líneas y es "conocimiento de consulta" (una tabla, una plantilla), probablemente corresponde a references/.
⚙️ La carpeta scripts/
Cuando una tarea tiene lógica determinista — filtrar datos, transformar un archivo, llamar a una API con reglas fijas—, es mejor escribir un script y hacer que la skill lo ejecute, en vez de pedirle a Claude que reinvente la lógica en cada llamada. El código siempre se ejecuta igual; la prosa regenerada, no.
✓ Buen candidato a script
- ✓Cálculo repetible (scoring, parsing, conversión)
- ✓Llamada a la API con formato fijo
- ✓Transformación de datos estructurados
- ✓Cualquier cosa que deba ser exacta e idéntica cada vez
✗ NO es trabajo de script
- ✗Criterio, redacción, creatividad
- ✗Decisiones que dependen del contexto de la conversación
- ✗Interpretación del lenguaje natural
- ✗Tareas donde «depende» es la respuesta correcta
## Workflow
1. Ask the user for the leads CSV path.
2. Run `python scripts/qualify_leads.py <path>` to score each lead.
3. Read the script's JSON output and summarize the top 10.
# A lógica de scoring vive no script — não é regenerada
# em cada execução. O Claude orquestra, o código calcula.🖼️ La carpeta assets/
assets/ guarda los recursos estáticos
que la salida usa o referencia: fuentes, imágenes, íconos, un ejemplo de salida listo, un archivo de configuración. La idea es
mantener la skill autocontenida — todo lo que necesita viaja junto, así que funciona
igual en cualquier máquina.
📦 El valor de un ejemplo listo para usar
Uno de los activos más valiosos es un ejemplo completo de salida. El generador de itinerarios, por ejemplo, incluye un archivo de ejemplo (un viaje de demostración ya renderizado).
- •Ancla la calidad: Claude ve el nivel esperado.
- •Documenta el formato mejor que mil palabras.
- •Sirve como prueba: la nueva salida debe quedar igual de bien.
🧷 Autocontenido en la práctica
Las skills bien hechas evitan dependencias externas. El principio de "un archivo, cero dependencias" del generador de itinerarios —CSS y JS inline, imágenes en base64, solo una fuente externa— tiene el mismo espíritu: el entregable no se rompe porque un servidor dejó de funcionar o cambió un enlace.
🪶 Manteniendo el SKILL.md conciso
Esta es la regla de oro de la estructura: el SKILL.md es un
un enrutador, no una enciclopedia. Debe contener el flujo, las decisiones y las reglas
— y señalar para los detalles, no los vuelques. Un SKILL.md inflado paga el precio en contexto en cada ejecución.
✓ Se queda en SKILL.md
- ✓Frontmatter (name + description)
- ✓El workflow de alto nivel
- ✓Las reglas estrictas y los principios
- ✓La tabla "lee X cuando Y"
✗ Va a los archivos de apoyo
- ✗Templates HTML/CSS completos
- ✗Tablas largas de datos de consulta
- ✗Lógica de cálculo (se convierte en script)
- ✗Ejemplos enormes de salida
⚠️ El síntoma del SKILL.md inflado
Si tu archivo principal tiene 800 líneas y la mayoría son tablas y templates que solo se usan en la mitad de las ejecuciones, estás pagando contexto de más cada vez que se activa la skill. Mueve el peso a references/ y deja que SKILL.md respire.
💡 Consejo práctico
Lee tu SKILL.md completo en voz alta. Si te descubres «saltándote» un bloque porque es solo una tabla de referencia, Claude tampoco lo necesita siempre: ese bloque es candidato a convertirse en un archivo de apoyo.
🗺️ Enrutamiento entre los archivos
Tener carpetas de apoyo solo funciona si el SKILL.md sepa cuándo
abrir cada una. El patrón es simple y poderoso: una instrucción condicional del tipo
"lee references/X.md cuando vayas a hacer Y". Esto transforma un montón de archivos
en una skill que se puede recorrer por sí sola.
## Quando ler cada arquivo
| Se você vai... | Leia primeiro |
|-----------------------------|----------------------------|
| construir a página de saída | references/DESIGN.md |
| revisar antes de entregar | references/CHECKLIST.md |
| calcular o score | (rode scripts/score.py) |
Não leia tudo de uma vez — abra cada arquivo só na etapa
que precisa dele.Nombra la condición
"Al construir el resultado", "cuando el usuario pida una revisión". La condición debe poder reconocerse dentro del flujo.
Señala el archivo correcto
Un camino explícito por condición. Evita «lee todo en references/»: eso anula el beneficio de la revelación progresiva.
Refuerza «solo cuando sea necesario»
Deja explícito que los archivos no deben cargarse por adelantado. Esta línea protege el contexto.
🧰 Prompts copiables
Usa estos prompts para refactorizar tus skills aplicando progressive disclosure.
Aqui está meu SKILL.md: <cole>. Aponte quais blocos são
"conhecimento de consulta" (tabelas, templates, exemplos longos)
que deveriam sair para references/, e quais blocos são fluxo/regras
que devem ficar. Justifique cada um.Para uma skill que faz <descreva>, proponha a árvore de pastas
(SKILL.md + references/ + scripts/ + assets/) e diga, para cada
arquivo, o que ele contém e em que etapa do workflow é lido.Escreva uma seção "Quando ler cada arquivo" para minha skill,
em forma de tabela (condição → arquivo a abrir), deixando claro
que os arquivos só devem ser carregados sob demanda.📤 Ejemplo de salida
Uno SKILL.md conciso que delega en archivos de apoyo: el patrón de progressive disclosure en acción.
---
name: invoice-builder
description: Builds a clean PDF-ready HTML invoice. Use when the
user wants to "create an invoice", "bill a client", or /invoice.
---
# Invoice Builder
## Workflow
1. Collect client, items, amounts, due date.
2. When building the layout, read `references/TEMPLATE.md`.
3. Before delivering, run `references/CHECKLIST.md`.
## Rules
- Never invent line items the user didn't provide.
- Totals must match the sum of the lines exactly.
## When to read each file
| If you are... | Read first |
|----------------------|-------------------------|
| building the layout | references/TEMPLATE.md |
| reviewing the output | references/CHECKLIST.md |
Load support files only at the step that needs them.✏️ Ejercicios prácticos
1. Clasifica cada bloque
Toma una skill existente y clasifica cada bloque del SKILL.md como: "se queda" (flujo/reglas), "va a references/" o "se convierte en script". Cuenta cuántas líneas podrías mover fuera.
2. Dibuja el árbol
Para una skill que genere informes de auditoría, diseña el árbol completo de carpetas (SKILL.md + references/ + scripts/ + assets/) y justifica por qué cada elemento está donde está.
3. Crea un SKILL.md ejecutable con referencia ⭐
Escribe un SKILL.md conciso MÁS un archivo references/TEMPLATE.md de apoyo. El SKILL.md debe incluir una instrucción de enrutamiento ("lee la plantilla al construir la salida"). Después pídele a Claude que ejecute la skill y confirma que abre la plantilla solo en la etapa adecuada; no antes.
📂 Resumen del módulo
Siguiente módulo:
1.3 — Descripciones que activan