🪜 Los 3 niveles de carga
El secreto de las skills es el divulgación progresiva: la información se revela por capas, según lo que necesita el agente. En vez de volcarlo todo en el contexto de una vez, la skill expone primero solo los metadatos, luego el cuerpo y, por último, los recursos pesados.
La idea central
Cuanto más alto el nivel, menos cuesta en contexto y más frecuente es la carga. Cuanto más bajo, más contenido cabe, pero solo se incluye cuando realmente es necesario. Eso es lo que permite que las skills enormes funcionen sin desperdiciar contexto.
① Nivel 1 — metadatos
El Nivel 1 es solo el name + description — alrededor de 100 palabras que quedan SIEMPRE en el contexto del agente, junto con los metadatos de todas las demás skills instaladas. Es el escaparate: a partir de ahí, el agente decide si vale la pena cargar el resto.
Qué queda siempre cargado (Nivel 1):
name: skill-creator description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill...
💡 Consejo
Como el Nivel 1 siempre está activo, cada palabra consume contexto multiplicado por TODAS las skills. Mantén unas ~100 palabras: lo bastante descriptivo para activarse y lo bastante conciso para no añadir peso.
② Nivel 2 — contenido del SKILL.md
Cuando la description coincide con la situación, el agente carga el cuerpo del SKILL.md — las instrucciones completas. La recomendación canónica es mantener el cuerpo menos de 500 líneas. Solo entra en el contexto cuando se activa, no antes.
La description se activa
El agente reconoce que la situación actual corresponde al Nivel 1.
El cuerpo se carga
Las instrucciones en Markdown se incorporan al contexto y empiezan a guiar la respuesta.
El agente actúa
Sigue el cuerpo y, si hace falta, busca recursos del Nivel 3.
Por qué <500 líneas
Los cuerpos largos diluyen la atención del agente y desperdician contexto cada vez que se activan. Si el contenido crece demasiado, mueve los detalles a references/ (Nivel 3) y deja el cuerpo solo con lo esencial y referencias.
③ Nivel 3 — recursos incluidos
El Nivel 3 son los recursos empaquetados: archivos en scripts/, references/ e assets/. Tamaño ilimitado, cargados bajo demanda. El detalle poderoso: scripts se ejecutan sin cargar el código en el contexto — el agente solo recibe el resultado.
✗ Todo en el cuerpo
- ✗Tablas gigantes y documentos completos en SKILL.md
- ✗Código pegado en Markdown para que el agente lo «lea y ejecute mentalmente»
- ✗El contexto se desborda con cada activación
✓ Recursos en el Nivel 3
- ✓Documentos largos en references/, que se leen solo cuando hace falta
- ✓Scripts en scripts/ que se ejecutan de verdad, sin ocupar contexto
- ✓Cuerpo conciso que apunta a los recursos
En el cuerpo, apunta al recurso (no pegues el contenido):
Para converter o arquivo, execute: python scripts/convert.py <input> Detalhes de configuração estão em references/config.md — leia se necessário.
💡 Consejo
Siempre que una tarea sea determinista (misma entrada → misma salida), prefiere un script de Nivel 3 a las instrucciones en el cuerpo. Es más confiable, más barato y ni siquiera hace falta incluir el código en el contexto.
🎯 Cómo escribir la description que activa
Aquí está el punto más sutil de toda la anatomía: Claude tiende a activar menos skills de las necesarias. De forma predeterminada es conservador y, ante la duda, no se activa. La corrección es escribir una description un poco "insistente" — sé explícito con los disparadores y deja claro cuándo usarla.
✗ Tímida (se activa de menos)
"Puede ayudar con pruebas."
"Puede" y ningún activador. El agente rara vez se activará.
✓ Insistente (se activa)
"Escribe y revisa pruebas. Úsalo SIEMPRE que el usuario pida pruebas, mencione TDD, cobertura o un bug que se deba reproducir."
Qué + cuándo + disparadores explícitos.
La fórmula de la description que activa:
description: [QUÉ hace] + [CUÁNDO usar — "Usa esta skill cuando..."] + [ACTIVADORES concretos — ejemplos, palabras clave]
Calibra con casos cercanos que no activan la skill
Para afinar, piensa en queries que deberían activarse y en casos cercanos que no deberían. Si la skill ignora casos obvios, sé más insistente; si se activa en situaciones equivocadas, restringe los disparadores. Este ajuste fino es el corazón del ciclo de creación de la Trilha 4.
🗂️ Organización por dominio
Cuando una skill cubre varios dominios, divide las referencias por archivo — references/aws.md, gcp.md, azure.md — para que el agente lo lea solo lo relevante. Y en cualquier archivo con más de 300 líneas, agrega una tabla de contenido al principio.
References divididas por dominio:
references/ ├── aws.md # só lido em tarefas AWS ├── gcp.md # só lido em tarefas GCP └── azure.md # só lido em tarefas Azure
Tabla de contenido al inicio de un archivo de >300 líneas:
# Guia AWS ## Índice - [IAM & permissões](#iam) - [S3 & storage](#s3) - [Lambda & serverless](#lambda) - [Networking (VPC)](#vpc)
Por qué esto ahorra contexto
- •Un único archivo de 900 líneas obliga al agente a cargarlo todo. Tres de 300 le permiten usar solo uno.
- •La tabla de contenido permite que el agente navegue hasta la sección adecuada sin volver a leer el archivo entero.
- •Separar los dominios también facilita el mantenimiento: editas azure.md sin tocar el resto.
💡 Consejo final
Los tres niveles + la organización por dominio forman un sistema: description insistente en el Nivel 1 para activarse, cuerpo conciso en el Nivel 2, recursos divididos por dominio en el Nivel 3. Así funcionan skills como la azure-ai (358k instalaciones) escalan sin perder precisión.
✅ Resumen del módulo
Próximo:
Módulo 3.3 — ⭐ Las mejores anatomías para imitar: disecciona el SKILL.md de skills destacadas y mira qué copiar de cada una.