🧭 El camino desde cero hasta SKILL.md
Crear una skill es un recorrido de seis paradas: capturar intent → frontmatter → cuerpo → carpetas → empaquetar → iterar. En este módulo recorres el camino desde la carpeta vacía hasta el archivo listo. La iteración (probar y optimizar la description) es el tema de la Trilha 4; aquí el foco es el montaje.
Empieza con algo mínimo
Un SKILL.md válido tiene solo dos partes: frontmatter con name + description y un cuerpo Markdown. Las carpetas son opcionales: créalas solo cuando el contenido lo requiera. No armes scripts/ el primer día.
🏷️ Paso 1 — frontmatter: name en kebab-case
O name es el identificador. Regla única e innegociable: kebab-case en minúsculas, igual al nombre de la carpeta. Sin espacios, sin mayúsculas, sin guiones bajos.
✗ Names mal formados
- ✗ PDF Extractor
- ✗ pdf_extractor
- ✗ PdfExtractor
- ✗ minha-skill-v2-final
✓ Nombres correctos
- ✓ pdf-extractor
- ✓ frontend-design
- ✓ skill-creator
- ✓ supabase
💡 Consejo
El nombre de la carpeta DEBE coincidir con el name. Si la carpeta es pdf-extractor/, el frontmatter es name: pdf-extractor. La discrepancia impide la carga.
🎣 Paso 2 — description: el disparador
A description es el único texto que siempre se carga y el que hace que se active la skill. Sigue la fórmula: [QUÉ hace] + [CUÁNDO usarla] + [DESENCADENANTES concretos]. Insiste: Claude activa menos de lo debido de forma predeterminada.
la fórmula aplicada (ejemplo de una skill nueva):
description: Extract structured data from PDF invoices and receipts into JSON. Use this skill whenever the user uploads a PDF invoice/receipt, asks to "parse", "extract fields", or "read" a financial document, or mentions OCR on a scanned bill.
QUÉ hace
"Extrae datos estructurados de facturas en PDF..." — empieza con un verbo y describe el resultado.
CUÁNDO usar
"Usa esta skill cuando el usuario suba una factura en PDF..." — la condición de activación.
DISPARADORES concretos
"parse", "extract fields", "read", "OCR" — palabras clave que el usuario realmente escribe.
~100 palabras es el límite
Los metadatos (name + description) son el Nivel 1 del progressive disclosure y SIEMPRE están en el contexto. Mantenlos alrededor de las 100 palabras: lo bastante directos para activar la skill y lo bastante concisos para no pesar en cada conversación.
📝 Paso 3 — el cuerpo: imperativo, When to Use, Steps
El cuerpo es Markdown en modo imperativo ("Lee el archivo", "Ejecuta el script"), explicando el por qué en vez de gritar MUSTs en mayúsculas. Una estructura que funciona: título, una línea sobre lo que hace la skill, Cuándo usar, Pasos numerados y ejemplos de salida.
esqueleto del cuerpo:
# PDF Invoice Extractor
Extracts fields from PDF invoices into clean JSON.
## When to Use
Use when the user provides a PDF invoice and asks
to extract fields, parse, or read it.
## Steps
1. Run `python scripts/extract.py <file.pdf>`.
2. Validate the JSON against the schema below.
3. Return the JSON; flag any missing field.
## Output Format
{ "vendor": str, "total": number, "date": str }
✗ Cuerpo malo
- ✗"SIEMPRE DEBES..." a gritos y en mayúsculas
- ✗Párrafos largos sin pasos
- ✗Sin indicar cuándo usarla
✓ Buen contenido
- ✓Imperativo claro + el porqué
- ✓Pasos numerados y prácticos
- ✓Cuándo usar + formato de salida explícitos
📁 Paso 4 — cuándo crear cada carpeta
Las carpetas son opcionales y surgen de la necesidad, no de la estética. Crea solo cuando aparezca el activador de abajo:
scripts/ — código determinista
Créalo cuando una tarea tenga la misma entrada → la misma salida (convertir un archivo, validar un schema). Es más confiable que las instrucciones y se ejecuta sin cargar el código en el contexto.
references/ — docs bajo demanda
Créalo cuando el cuerpo superaría las 500 líneas con detalles que solo importan en casos específicos. El agente solo lee el archivo relevante.
assets/ — archivos de salida
Créalo cuando la skill produzca algo a partir de una plantilla (HTML, fuente, ícono, boilerplate). Son archivos que se usan no output, no leídos como instrucciones.
el árbol final de la skill de ejemplo:
pdf-extractor/
├── SKILL.md # frontmatter + corpo
├── scripts/
│ └── extract.py # roda sem ir pro contexto
├── references/
│ └── field-map.md # lido só em casos raros
└── assets/
└── report.html # template de saída
💡 Consejo
No crees carpetas vacías "para el futuro". Cada archivo debe tener una referencia correspondiente en el cuerpo del SKILL.md que indique cuándo leerlo o ejecutarlo.
📄 Paso 5 — plantilla completa para copiar
Reúne todo. Este es un SKILL.md completo, listo para pegar en un archivo, cambiar los nombres y empezar. Incluye frontmatter, When to Use, Steps, Output Format y referencias a las carpetas.
SKILL.md — plantilla completa:
---
name: pdf-extractor
description: Extract structured data from PDF
invoices and receipts into JSON. Use this skill
whenever the user uploads a PDF invoice/receipt,
asks to "parse", "extract fields", or "read" a
financial document, or mentions OCR on a bill.
metadata:
author: seu-usuario
version: "0.1.0"
---
# PDF Invoice Extractor
Extracts fields from PDF invoices into clean,
validated JSON. Built for accounts-payable flows.
## When to Use
Use when the user provides a PDF invoice or
receipt and asks to extract, parse, or read its
fields. Do NOT use for plain-text data or images
without a document layout.
## Steps
1. Run `python scripts/extract.py <file.pdf>` to
pull raw fields. The script handles OCR.
2. Validate the result against the schema in
`references/field-map.md` — read it only if a
field is missing or ambiguous.
3. If the user wants a report, fill the template
`assets/report.html` with the JSON.
4. Return the JSON and flag any field you could
not extract. Never invent values.
## Output Format
```json
{ "vendor": "string", "total": 0.00,
"date": "YYYY-MM-DD", "line_items": [] }
```
## Notes
Explain to the user which fields were uncertain so
they can verify — accuracy matters more here than
speed.
Listo: ahora prueba
Guarda como pdf-extractor/SKILL.md, crea las carpetas mencionadas y tendrás una skill instalable. El paso 6 —probar, evaluar y optimizar la description en un ciclo— es exactamente el tema de la Trilha 4. El 3.5, a continuación, muestra cómo dejar realmente afilada la estructura de varios archivos.
✅ Resumen del módulo
Próximo:
Módulo 3.5 — 🚀 Consejos avanzados: progressive disclosure de verdad, enrutamiento por dominio, scripts que se ejecutan sin contexto y cómo mantener el SKILL.md por debajo de 500 líneas.