🧮 El problema del contexto
Toda conversación con Claude tiene una ventana de contexto finita: tokens que desaparecen cuando se agotan. Cargar todas las skills de una sola vez sería un desastre para la eficiencia y la calidad de las respuestas.
La ventana de contexto de un LLM es como la RAM de una computadora: finita, valiosa y costosa de usar. Si Claude cargara el contenido completo de cada skill instalada en cada conversación, agotaría el contexto antes incluso de que escribieras la primera palabra.
La solución es la revelación progresiva: cargar solo lo mínimo necesario e ir buscando más según lo exija la complejidad de la tarea.
name+description en la memoria- ✓ Decenas de skills instaladas sin costo de contexto
- ✓ Respuestas más rápidas y enfocadas
- ✓ Contenido profundo solo cuando realmente es necesario
- ✓ Contexto libre para el código y la conversación del usuario
- ✗ Cada skill carga cientos de tokens todo el tiempo
- ✗ 20 skills = 16.000 tokens consumidos antes de empezar
- ✗ Degradación de calidad en conversaciones largas
- ✗ Conflictos entre instrucciones de skills no relevantes
1️⃣ Capa 1: name + description siempre en memoria
El nivel más ligero de divulgación progresiva. Solo el name e a description de cada skill están disponibles todo el tiempo: costo mínimo, máxima visibilidad.
Claude necesita saber que existe una skill y para qué sirve, pero no necesita conocer los detalles de cómo ejecutarla antes de decidir si es relevante. El name es el identificador; la description es el disparador de activación.
Es como el índice de un libro: lees el índice para decidir qué capítulo abrir, no lees todo de una vez.
Cómo leyó Claude en narration-template.sh (escena s3): "La descripción es la parte más importante de todas. Es lo que Claude lee para decidir cuándo usar esa skill. Cuanto más clara y específica, mejor será el activador."
Al abrir Claude Code, el sistema lee automáticamente todos los SKILL.md encontrados en las carpetas .claude/skills/ (del proyecto y global) e indexa solo name + description de cada uno.
Con 20 skills, el costo total es de ~1.000 tokens, una proporción ínfima de la ventana. Claude sabe que estas herramientas existen sin haber consumido nada relevante del contexto.
En cualquier momento de la conversación, Claude compara la solicitud con las descriptions disponibles. Si encuentra una coincidencia, avanza a la Capa 2.
2️⃣ Capa 2: SKILL.md completo se carga al coincidir
Cuando la tarea del usuario coincide con la description de una skill, Claude carga el contenido completo del SKILL.md — instrucciones, flujo, reglas e identidad visual.
Al detectar que la solicitud del usuario se ajusta al alcance descrito por la description, Claude ejecuta el equivalente a «abrir el libro en el capítulo correcto». Todo el SKILL.md se carga en el contexto en este momento, y solo en este momento.
- ✓ Incluye datos reales: valores como
LEAD=0.5,TAIL=0.9 - ✓ Organiza en secciones claras con encabezados Markdown
- ✓ Separa las "reglas de oro" de las instrucciones opcionales
- ✓ Incluye enlaces a los archivos de referencia (Capa 3)
- ✗ No pongas contenido de referencias extensas directamente en SKILL.md
- ✗ No repitas en el cuerpo del archivo lo que está en la description
- ✗ No omitas los valores exactos (Claude necesita números reales)
- ✗ No hagas que SKILL.md supere ~1.000 tokens sin necesidad
Piensa en SKILL.md como el briefing que le darías a un nuevo miembro del equipo: lo suficientemente completo para ejecutar la tarea y lo bastante conciso para que quepa en una reunión de 5 minutos. Los detalles técnicos profundos quedan en las referencias (Capa 3).
3️⃣ Capa 3: referencias y scripts solo bajo demanda
El nivel más profundo: los archivos grandes, como las plantillas de composición, las paletas detalladas y los scripts de shell, se quedan en references/ y se leen solo cuando la tarea lo requiere.
O narration-template.sh tiene ~100 líneas. El composition-template.mjs tiene ~300 líneas. Incluir estos archivos en el SKILL.md consumiría más de 5.000 tokens cada vez que se activara la skill — incluso en tareas que no los necesitan.
Se carga cuando el usuario pide generar una narración TTS; contiene los comandos npx hyperframes tts, la voz pf_dora --speed 0.98 y el loop ffprobe para medir duraciones.
Se carga cuando el usuario pide crear o adaptar el build-index.mjs — contiene la estructura de las escenas, las constantes LEAD=0.5, TAIL=0.9, FADE=0.45 y la escena final de CTA de INEMA.CLUB.
Se carga cuando Claude encuentra errores de diseño durante npx hyperframes lint o inspect — enumera los problemas conocidos y sus correcciones.
Se carga específicamente en el paso 3 del flujo, cuando es momento de descargar los archivos .woff2 (subset latin) para assets/fonts/fonts.css.
El SKILL.md menciona cada archivo de la Capa 3 con la ruta exacta (p. ej., [narration-template.sh](scripts/narration-template.sh)). Claude puede localizar y cargar el archivo correcto cuando lo necesite, sin tener que adivinar el nombre.
📈 Por qué esto escala con decenas de skills
Con la divulgación progresiva, puedes instalar 30, 50 o 100 skills sin degradar la calidad de las respuestas. El costo de contexto crece de forma lineal y controlada, no exponencial.
| Skills instaladas | Sin progreso | Con divulgación progresiva | Ahorro |
|---|---|---|---|
| 5 skills | ~4.000 tokens | ~250 tokens | 94% menos |
| 20 skills | ~16.000 tokens | ~1.000 tokens | 94% menos |
| 50 skills | ~40.000 tokens | ~2.500 tokens | 94% menos |
Una biblioteca de 10.000 libros no ocupa más espacio en tu cabeza que una de 10 — porque no memorizas todos los libros, solo sabes dónde encontrarlos. Las skills funcionan de la misma manera con la divulgación progresiva.
Cada skill adicional agrega solo ~50 tokens a la Capa 1 (name + description). El costo marginal de una nueva skill es casi cero.
- ✓ Escribe descripciones únicas y precisas (sin superposición)
- ✓ Usa TRIGGER/SKIP explícitos en la description
- ✓ Mantén SKILL.md ≤ 1.000 tokens y mueve el resto a la Capa 3
- ✓ Agrupa las skills relacionadas en subcarpetas organizadas
- ✗ Descriptions vagas que activan la skill equivocada (falso positivo)
- ✗ SKILL.md con más de 5.000 tokens (pesa como 100 skills)
- ✗ Dos skills con descripciones superpuestas
- ✗ Usar la carpeta global para skills de proyectos específicos
Skills globales (~/.claude/skills/) están disponibles en todos los proyectos; úsalas para herramientas universales como video-explicativo. Las skills de proyecto (.claude/skills/) están disponibles solo en ese proyecto; úsalas para workflows específicos del cliente o del codebase.
🤔 Cómo decide Claude qué skill activar
El mecanismo de selección de skills no es magia: Claude compara semánticamente la solicitud del usuario con cada description disponible en la Capa 1 y elige la que mejor se adapte.
Claude no hace una búsqueda literal por palabras clave. Usa comprensión semántica para evaluar si la intención de la solicitud coincide con el alcance descrito en la description. Por eso, «crea un video explicativo sobre Docker» activa la skill video-explicativo incluso sin usar esas palabras exactas.
Ej.: "quiero hacer un video corto que muestre cómo funciona el SKILL.md"
Verifica: video-explicativo → "crea videos explicativos HTML→MP4 con HyperFrames". ✓ Coincidencia de alta confianza. Verifica: formato-curso → "crea páginas HTML de cursos". ✗ No es el alcance aquí.
Carga el SKILL.md completo de video-explicativo — instrucciones, flujo, valores como pf_dora --speed 0.98, paleta #0D1321, reglas de oro.
Sigue el flujo de la skill: Guion → Proyecto → Fuentes → Narración → Composición → Validar → Render. Solo busca en la Capa 3 cuando el paso específico lo requiera.
Si dos skills tienen descripciones superpuestas, Claude puede activar la incorrecta o entrar en conflicto. Solución: usa las cláusulas TRIGGER when e SKIP en la description para delimitar el alcance con precisión.
Antes de finalizar una skill, pídele a Claude: "Si pidiera X, ¿qué skill activarías?". Si la respuesta es la skill equivocada, reescribe la description con más especificidad: agrega ejemplos de activadores en el campo TRIGGER y exclusiones en el campo SKIP.
✅ Resumen del Módulo 1.3
- ✓La ventana de contexto es finita: cargarlo todo sería ineficiente y contraproducente.
- ✓Capa 1:
name + descriptionsiempre quedan en la memoria: costo de ~50 tokens por skill. - ✓Capa 2: se carga el SKILL.md completo on match — instrucciones, flujo y reglas de oro.
- ✓Capa 3: referencias y scripts (
references/,scripts/) solo cuando se necesita, cuando el paso específico lo requiere. - ✓Con la divulgación progresiva, 50 skills consumen ~94% menos contexto que sin ella.
- ✓Claude usa matching semántico + TRIGGER/SKIP para decidir qué skill activar.