🪜 Divulgación progresiva de verdad
Ya viste los 3 niveles en el 3.2. Aquí los ponemos en práctica: el objetivo es que el agente carga solo lo que necesitas, cuando lo necesitas. Una skill avanzada es como un menú: el SKILL.md muestra las opciones y cada archivo solo entra en el contexto cuando se elige esa ruta.
La meta
En una tarea de AWS, el agente lee aws.md e ignora gcp.md y azure.md. El contexto carga un tercio del contenido. Así es como skills como azure-ai (358k) cubren decenas de servicios sin desbordar el contexto.
🗂️ references/ por dominio
El patrón canónico de skill-creator: cuando una skill cubre varios dominios, organiza por variante y deja que el SKILL.md haga la selección. El agente lee solo el archivo de referencia pertinente.
estructura de organización por dominio (de skill-creator):
cloud-deploy/
├── SKILL.md # workflow + seleção
└── references/
├── aws.md # lido só em tarefas AWS
├── gcp.md # lido só em tarefas GCP
└── azure.md # lido só em tarefas Azure
En el cuerpo, el enrutamiento es explícito: una tabla "si el dominio es X, lee Y":
enrutamiento en el cuerpo del SKILL.md:
## Selecione o provedor | Provedor | Leia | |----------|---------------------| | AWS | references/aws.md | | GCP | references/gcp.md | | Azure | references/azure.md | Read ONLY the file for the user's provider.
💡 Consejo profesional
Un único archivo de 900 líneas obliga al agente a cargarlo todo. Tres de 300 le permiten usar solo uno: un ahorro del 66% de contexto. Además, el mantenimiento es muy sencillo: editas azure.md sin tocar el resto.
⚙️ scripts/ que se ejecutan sin contexto
La jugada más poderosa del Nivel 3: un script se ejecuta y el agente solo recibe el resultado — el código nunca entra en el contexto. Para tareas deterministas (misma entrada → mismo resultado), esto es más confiable y barato que instruir al agente para que "razone" cada paso.
✗ Instrucción en el cuerpo
- ✗"Procesa el CSV, suma la columna 3, da formato..."
- ✗El agente puede equivocarse en la aritmética
- ✗Gasta tokens razonando lo obvio
✓ Script en el Nivel 3
- ✓"Ejecuta
python scripts/sum.py" - ✓Resultado exacto, siempre
- ✓El código no ocupa contexto
en el cuerpo: señala y ejecuta, no pegues el código:
## Steps 1. Run `python scripts/package_skill.py <path>` to bundle the skill into a .skill file. 2. The script prints the output path — return it. # o conteúdo de package_skill.py NUNCA entra # no contexto; só a saída do comando.
Señal de extracción
Si notas que el agente reescribe el mismo helper en cada ejecución, esa es la señal: escríbelo una vez, ponlo en scripts/, y dile a la skill que lo use. Es exactamente lo que recomienda skill-creator en el ciclo de iteración.
📑 Tabla de contenido en archivos de >300 líneas
Regla de skill-creator: cualquier archivo de referencia con más de 300 líneas obtiene una tabla de contenido al principio. Así, el agente navega directamente a la sección correcta sin volver a leer el archivo entero.
índice al inicio de una referencia extensa:
# Guia AWS ## Índice - [IAM & permissões](#iam) - [S3 & storage](#s3) - [Lambda & serverless](#lambda) - [Networking (VPC)](#vpc) ## IAM ...
💡 Consejo profesional
Si un reference supera las ~300 líneas con la TOC y aun así parece demasiado grande, es señal de dividirlo en dos archivos por subtema. La TOC es el primer remedio; la partición, el segundo.
📏 SKILL.md <500 líneas + jerarquía con pointers
La regla de oro: mantén el cuerpo por debajo de 500 líneas. Al acercarte al límite, no recortes contenido — añade una capa de jerarquía con indicaciones claras sobre adónde debe ir el agente después.
Identifica qué es un detalle
Los casos límite, las tablas grandes y los ejemplos largos rara vez necesitan estar en el cuerpo.
Mueve a references/
Sácalo del cuerpo y ponlo en un archivo de referencia dedicado por subtema.
Deja un pointer en el cuerpo
"Consulta references/schemas.md for the full schema" — di cuándo leerlo.
referencias reales (estilo skill-creator):
See `references/schemas.md` for the full schema (including the `assertions` field). The references/ directory has more docs: - `references/schemas.md` — JSON structures - `references/eval-format.md` — eval layout
Por qué importa el límite
El cuerpo entra completo en el contexto cada vez que se activa la skill. Los cuerpos largos diluyen la atención del agente y consumen tokens cada vez. La jerarquía con referencias hace que el costo se pague solo cuando el detalle realmente hace falta.
🎨 assets/ y la lista de verificación final
La carpeta assets/ guarda archivos usados en el output: plantillas HTML, fuentes, íconos, boilerplate. A diferencia de references/ (que el agente lee para aprender), los assets se rellenan o copian al resultado final — como el assets/eval_review.html que el skill-creator completa con datos.
los tres directorios, con roles distintos:
scripts/ → executado (resultado no contexto) references/ → lido (aprende sob demanda) assets/ → preenchido (vai pro output final)
Checklist para una skill precisa con varios archivos
- ✓SKILL.md de menos de 500 líneas, con pointers claros
- ✓references/ dividido por dominio; el agente lee solo lo relevante
- ✓TOC en cada reference de más de 300 líneas
- ✓Las tareas deterministas se convirtieron en scripts/ que se ejecutan sin contexto
- ✓assets/ solo con archivos que van a la salida
- ✓Cada archivo tiene un indicador correspondiente en el cuerpo
💡 Consejo final
Un buen trabajo con varios archivos es lo que distingue una skill de juguete de una como azure-ai o supabase. Con la anatomía dominada, la siguiente frontera es el ciclo de creación — probar, evaluar y optimizar la description —, que es exactamente el tema de la Trilha 4.
✅ Resumen del módulo
Próximo:
Trilha 4 — ⚙️ Cómo crear (el loop): captar intent, redactar, probar con prompts realistas, evaluar y optimizar la description hasta que la skill quede afinada.