🧮 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 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 de que escribieras la primera palabra.
La solución es la divulgació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 sea 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; el description es el disparador de activación.
Es como el índice de un libro: lees el índice para decidir qué capítulo abrir; no lo 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 disparador."
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 — un porcentaje ínfimo 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 descripción de una skill, Claude carga el contenido completo de SKILL.md — instrucciones, flujo, reglas e identidad visual.
Al detectar que la solicitud del usuario corresponde al alcance descrito por la description, Claude ejecuta el equivalente de «abrir el libro en el capítulo correcto». Todo el SKILL.md se carga en el contexto en ese momento, y solo en ese 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 largas 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 suficientemente conciso para cubrirlo en una reunión de 5 minutos. Los detalles técnicos más 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 guardan 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. Incrustar estos archivos en el SKILL.md consumiría 5.000+ tokens cada vez que se activara la skill, incluso en tareas que no los necesitan.
Se carga cuando el usuario pide generar narración TTS; contiene los comandos npx hyperframes tts, la voz pf_dora --speed 0.98 y el bucle ffprobe para medir duraciones.
Se carga cuando el usuario pide crear o adaptar el build-index.mjs — contiene la estructura de escenas y 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)). Esto permite que Claude localice y cargue el archivo correcto cuando sea necesario, 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 progresiva | 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 igual 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 superposiciones)
- ✓ Usa TRIGGER/SKIP explícitos en la description
- ✓ Mantén SKILL.md ≤ 1.000 tokens, 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 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/) solo están disponibles en ese proyecto; úsalas para flujos de trabajo específicos del cliente o del código base.
🤔 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 encaje.
Claude no hace una búsqueda literal por palabras clave. Usa la 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 aunque no uses 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 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 te 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 permanecen 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 necesite, cuando el paso específico lo requiera. - ✓Con la divulgación progresiva, 50 skills cuestan ~94% menos contexto que sin ella.
- ✓Claude usa la coincidencia semántica + TRIGGER/SKIP para decidir qué skill activar.