🏷️ Paso 1 — Nombre y activador
¿Eres nuevo aquí? O front matter es el bloque de
metadatos al inicio de `skill.md`, entre dos líneas `---`, con el formato `clave: valor`. Allí se encuentran el
name (el identificador de la skill) y la description
(el texto que el agente lee para decidir si usa esta skill o no). El paso 1 es elegir ambos con cuidado.
Piensa en una receta de pastel: el título en la portada del cuaderno («Pastel de zanahoria de la abuela») ya te avisa cuándo vas a
abrir esa página. El `name` es ese título — corto, sin espacios, como relatorio-mensal-cliente.
A description es el resumen de la contraportada: cuándo usarla y en qué situación encaja.
Se explica en detalle en el módulo 3.4; aquí lo importante es saber que existe y está en el paso 1.
💡 Concepto principal
El paso 1 no es burocracia: es lo que hace que el agente ENCUENTRE la skill correcta entre otras 20.
- •
name: identificador técnico, corto y sin ambigüedad con otra skill. - •
description: frase que describe CUÁNDO usarla, no solo qué es.
✨ Consejo práctico
Prueba tu nombre y descripción preguntándole al agente, en una sesión nueva: «¿qué skills tienes instaladas y cuándo usarías cada una?». Si su respuesta sobre tu skill no coincide con tu intención, el paso 1 necesita ajustes.
🎯 Paso 2 — Objetivo en una frase
Justo después del front matter, la skill necesita una frase clara que diga lo que ENTREGA. No "ayuda con informes" (vago), sino "genera un PDF de informe mensual a partir de la hoja de cálculo de ventas del cliente, listo para enviar por correo electrónico" (concreto, con el resultado final identificado). Es el equivalente a la foto del pastel terminado en la primera página de la receta: sabes exactamente adónde vas a llegar antes de leer el paso a paso.
La ambigüedad aquí sale cara: si el objetivo admite dos interpretaciones, el agente elegirá una en el momento equivocado. «Organiza mis archivos» puede significar cambiarles el nombre, moverlos a carpetas por fecha o borrar duplicados: tres cosas muy distintas. Escribe el objetivo como si fuera la última frase que alguien leerá antes de aprobar.
✓ Objetivo claro
- ✓"Genera el informe mensual en PDF, con un gráfico de ventas por región, a partir de la hoja de cálculo `vendas.xlsx`."
- ✓Define la entrada, la salida y el formato final: cero interpretación libre.
✗ Objetivo vago
- ✗"Ayuda a organizar los informes de la empresa."
- ✗No indica el formato de salida ni de dónde vienen los datos: el agente lo adivina.
🪜 Paso 3 — Paso a paso verificable
Aquí está el cuerpo de la skill: la secuencia numerada de acciones que sigue el agente. Cada elemento debe ser verificable — se puede comprobar si ocurrió o no. "1. Abrir la hoja de cálculo `vendas.xlsx`. 2. Sumar la columna 'total' por región. 3. Generar un gráfico de barras. 4. Exportar en PDF." Cada número es una lista de verificación del piloto: antes de despegar, revisa cada elemento, en orden, sin saltarse ninguno.
Leyenda: los 6 pasos forman un pipeline que se cierra en círculo: después del paso 6 (mejora), la skill vuelve al paso 1 en la siguiente ejecución, un poco mejor.
✨ Consejo práctico
Escribe cada paso como una frase que empiece con un verbo de acción ("Abrir", "Sumar", "Generar"). Si no puedes escribir un verbo concreto, probablemente ese paso es demasiado vago y hará que el agente tome decisiones arbitrarias.
📚 Paso 4 — Referencias sin sobrecargar el archivo principal
No todo tiene que estar en `skill.md`. Los detalles largos —tablas de códigos de error, ejemplos extensos, modelos de documentos— van en archivos separados dentro de la carpeta de la skill (generalmente una subcarpeta
references/), y el `skill.md` solo APUNTA a ellos cuando hace falta.
Así se aplica en la práctica la carga en 3 niveles del módulo 3.2: el agente solo lee la referencia si la
situación lo requiere, por eso el `skill.md` principal queda conciso y es barato de cargar cada vez.
Pon en `skill.md` solo lo que siempre es necesario
Los 6 pasos y lo esencial quedan en el archivo principal, que se lee en cada invocación.
Mueve el resto a `references/arquivo.md`
Ejemplos poco frecuentes, tablas grandes, casos límite: solo se cargan cuando se necesitan.
Remite con una línea en el paso relevante
"Si el cliente es X, consulta `references/regras-cliente-x.md` antes de generar."
🚫 Paso 5 — Reglas y «no hagas»
El paso que más se omite — y el que más dolores de cabeza causa cuando falta. Las reglas son restricciones explícitas: lo que el agente NUNCA debe hacer por su cuenta, aunque parezca el camino más rápido. «No envíes el correo sin que lo revise antes». «No sobrescribas el archivo original — crea siempre una copia». «No borres filas de la hoja de cálculo, solo márcalas como procesadas». Sin estos límites, un agente eficiente y sin contexto tomará el atajo peligroso, porque técnicamente funciona — pero no es lo que querías.
✓ Skill con los 6 pasos completos
- ✓Tiene "Reglas" explícitas: "no borrar, solo archivar".
- ✓El agente duda y pregunta antes de una acción irreversible.
- ✓Los errores recurrentes quedan registrados y se convierten en una nueva regla (paso 6).
✗ Skill que se salta las "reglas"
- ✗Solo tiene "haz esto, haz aquello" — ningún límite explícito.
- ✗El agente borra el archivo original porque cree que así queda "más limpio".
- ✗El mismo error se repite en cada ejecución, porque no se escribió nada para evitarlo.
⚠️ Atención
Una regla vaga no protege. «Ten cuidado con los datos sensibles» no impide nada; «nunca escribas el CPF ni el correo electrónico de un cliente en un log o commit» sí. Sé específico, como quien redacta una lista de verificación para un piloto, no un aviso genérico al pie de página.
🔁 Paso 6 — El ciclo de mejora
Una skill no nace perfecta, igual que nadie acierta la receta del pastel en el primer intento. El paso 6 consiste en adquirir el hábito de revisar después de usarla algunas veces: ¿qué salió mal? ¿El agente dudó en algún punto? ¿Hizo algo que no querías? Cada respuesta se convierte en una nueva línea en los pasos 3 o 5 (un paso más o una regla más). Así es como una skill pasa de «funciona a veces» a «siempre es confiable».
Ejecución 1: la skill se ejecuta, pero el agente pregunta demasiado: faltan decisiones explícitas en el paso a paso.
Ejecuciones 2-3: agregas reglas después de ver al agente tomar un atajo peligroso una vez.
Ejecuciones 4-9: los casos poco frecuentes se convierten en referencias separadas; el `skill.md` principal sigue siendo conciso.
A partir de la 10.ª: la skill se ejecuta sin sorpresas: ese es el punto en que se vuelve realmente confiable (se profundiza en el 3.7).
Ejemplo de skill.md con los 6 elementos marcados
---
name: relatorio-mensal-cliente # 1. nome e gatilho
description: Gera o PDF do relatório mensal de vendas quando o
usuário pedir "relatório mensal", "fechamento do mês" ou "PDF de vendas".
---
## Objetivo # 2. objetivo em uma frase
Gerar o PDF do relatório mensal de vendas a partir de vendas.xlsx,
com gráfico por região, pronto para enviar por e-mail.
## Passos # 3. passo a passo verificável
1. Abrir vendas.xlsx e validar que a coluna "total" existe.
2. Somar o total por região.
3. Gerar gráfico de barras (uma barra por região).
4. Exportar como PDF em saida/relatorio-<mes>.pdf.
## Referências # 4. referências
Se o cliente for "Cliente X", ver references/regras-cliente-x.md
antes do passo 3 (ele usa moeda diferente).
## Regras # 5. regras
- Nunca sobrescrever vendas.xlsx.
- Nunca enviar o PDF por e-mail sozinho — sempre aguardar aprovação.
## Histórico de ajustes # 6. ciclo de melhoria
- 2026-06: adicionada regra de não sobrescrever (aconteceu 1x).
- 2026-07: cliente X precisou de referência separada (moeda).Copy-run — objetivo
Pedirle a Claude Code que cree el esqueleto de un `skill.md` nuevo, con los 6 pasos ya marcados y listo para que lo completes.
Crie um skill.md esqueleto para uma skill chamada
<nome-da-skill>, cujo objetivo é <o que ela deve entregar>.
Estruture com os 6 elementos, cada um comentado:
1) front matter com name e description (gatilho),
2) seção Objetivo em uma frase,
3) seção Passos numerada e verificável,
4) seção Referências (aponte para references/ se precisar),
5) seção Regras com pelo menos 2 restrições explícitas de "não faça",
6) seção Histórico de ajustes, vazia, pronta para eu preencher
depois da primeira execução.Cómo verificar: abre el archivo generado y comprueba que estén las 6 secciones, en orden, y que la description menciona situaciones reales (no jerga) que activarían la skill.
Verificación rápida (opcional): ¿por qué el paso 5 (reglas) suele ser el más importante cuando falta?