🎯 Elige un caso pequeño y real
La primera skill de todo el mundo debería ser aburrida y útil, no ambiciosa. Una convención que repites todo el tiempo y detestas repetir. El ejemplo perfecto: el patrón de mensajes de commit de tu equipo. Es concreto, tiene reglas claras y notarás enseguida si funcionó.
✗ Malos casos de estreno
- ✗"Una skill que hace el deploy completo" — demasiado grande
- ✗"Una skill genérica de buenas prácticas" — vaga, no se activa
- ✗Algo que no puedes probar en 1 minuto
✓ Buenos casos para empezar
- ✓Convención de commits (Conventional Commits)
- ✓Convenciones del proyecto para nombrar archivos/branches
- ✓Tono de voz de las respuestas en PT-BR
💡 Vamos a construir esta
Nuestro caso: una skill conventional-commits que hace que el agente escriba mensajes de commit en el formato tipo(escopo): descrição siempre que vaya a hacer un commit. Pequeña, comprobable, inmediatamente útil.
🧬 La anatomía mínima de un SKILL.md
Una skill es un solo archivo: SKILL.md. Dos partes. Arriba, un frontmatter YAML con dos campos obligatorios — name e description. Abajo, el cuerpo Markdown con las instrucciones en imperativo. Nada más.
name — el identificador
Corto, en minúsculas y con guiones. Se convierte en el nombre de la carpeta y en la forma de referirse a la skill. Ej.: conventional-commits.
description — el activador
El campo más importante. Indica QUÉ la skill hace Y CUÁNDO usarla. Es aquí donde el agente decide activarla. Sé explícito e incluso un poco «insistente»: el agente tiende a activarla menos de lo necesario.
cuerpo — las instrucciones
Markdown en imperativo: "Escribe...", "Usa...", "Evita...". Explica el por qué en vez de gritar MUSTs en mayúsculas. Mantén el contenido conciso (<500 líneas).
✍️ Escribe el SKILL.md (copia esto)
Aquí está la skill completa, lista para pegar. Crea el archivo en skills/conventional-commits/SKILL.md y pega el contenido de abajo. Fíjate: frontmatter entre ---, description que dice qué y cuándo, cuerpo breve e imperativo.
skills/conventional-commits/SKILL.md
--- name: conventional-commits description: Escreve mensagens de commit no padrão Conventional Commits. Use SEMPRE que for criar um commit, sugerir uma mensagem de commit, ou rodar git commit neste repositório. --- # Conventional Commits Ao criar qualquer commit, escreva a mensagem no formato: tipo(escopo): descrição no imperativo Use estes tipos: - feat nova funcionalidade - fix correção de bug - docs só documentação - refactor mudança sem alterar comportamento - test testes - chore build, deps, config Regras: - Descrição em minúscula, no imperativo ("adiciona", não "adicionado"). - Sem ponto final. Máximo ~72 caracteres na primeira linha. - escopo é opcional; use o módulo afetado quando ajudar. Exemplo bom: feat(auth): adiciona login via magic link Exemplo ruim: Adicionei o login.
💡 La description lleva el peso
Nota el "Úsala SIEMPRE que..." con tres activadores concretos (crear un commit, sugerir un mensaje, ejecutar git commit). Es deliberado: una descripción vaga ("ayuda con commits") casi nunca se activa. Dile al agente exactamente cuándo debe actuar.
📥 Instálala localmente y comprueba cómo funciona
No necesitas publicar nada para usarla. Las skills se instalan desde una ruta local con npx skills add ./.... Sigue la timeline: desde la creación del archivo hasta que el agente respeta la regla.
Crea la carpeta y el archivo
La ruta importa: la carpeta se convierte en el nombre de la skill.
$ mkdir -p skills/conventional-commits
$ $EDITOR skills/conventional-commits/SKILL.md # cole o conteúdo
Instala desde la ruta local
$ npx skills add ./skills/conventional-commits
Esto registra la skill en el agente (en .claude/skills/ o equivalente). El name + description pasan a vivir en el contexto.
Actívala con una solicitud real
Pídele al agente que haga el commit. La description coincide con el contexto y la skill se activa por sí sola.
você: "commita as mudanças do login"
agente: feat(auth): adiciona login via magic link ✓
Confirma que se activó
Si el mensaje salió en el formato tipo(escopo): ... sin que lo pidas en ese formato, la skill funcionó. Listo: creaste y ejecutaste tu primera skill.
10 minutos, de verdad
Elegir el caso (1 min) → escribir el SKILL.md (4 min) → instalarlo (1 min) → probar y ajustar (4 min). Sin build, sin deploy, sin dependencias. Solo un archivo de texto.
🚫 Errores comunes de principiantes
Casi todo problema de una primera skill cae en uno de estos grupos. Compara ambos lados y ajusta antes de culpar al agente.
✗ Lo que acaba con una skill
- ✗description vaga: "ayuda con git" — nunca se activa
- ✗sin CUÁNDO usar: describe qué, pero no el desencadenante
- ✗cuerpo enorme: 800 líneas que el agente no lee completas
- ✗frontmatter roto: faltó uno
---o con indentación incorrecta - ✗todo en MAYÚSCULAS a gritos: reglas sin explicar por qué
✓ Qué hace que funcione
- ✓description específica: verbo + objeto + 2-3 activadores
- ✓"Úsala cuando...": dice exactamente en qué situación actuar
- ✓cuerpo conciso: solo lo esencial, ejemplos breves
- ✓YAML válido: dos
---, dos espacios de indentación - ✓imperativo + por qué: "Usa feat para X porque Y"
💡 ¿No se activó? Casi siempre es por la description
Si la skill existe pero el agente la ignora, 9 de cada 10 veces el problema está en una description débil, no en el cuerpo. Añade los activadores concretos («al hacer commit», «al ejecutar git commit») y vuelve a probar. Este ciclo de ajuste de la description es el corazón de la Ruta 4.
🌱 Evoluciona a partir de lo mínimo
Tienes una skill funcionando. Ahora resiste las ganas de inflarla. La evolución saludable es incremental: ajusta la description según lo que falló, añade ejemplos solo cuando hagan falta y extrae los recursos pesados a archivos separados (divulgación progresiva) solo cuando el contenido crezca.
Ajustar la description
¿Se activó demasiado (en conversaciones que no eran sobre commits)? Restringe. ¿Se activó poco? Añade activadores. La description es lo que más vas a modificar.
Agregar ejemplos bajo demanda
¿Te equivocaste en un caso específico? Añade un par "bueno/malo" para ese caso. No intentes preverlo todo de antemano: deja que los errores te guíen.
Versionar junto con el repo
SKILL.md es texto: haz commit junto con el proyecto. Todo el equipo hereda la convención, y la skill evoluciona en el historial de git como cualquier archivo.
el ciclo, en una línea:
escrever mínimo → instalar → testar → ajustar description → repetir
💡 Pequeña y activa > grande y muerta
Una skill de 30 líneas que usas todos los días y ajustas cada semana vale más que una de 500 líneas escrita como «completa» y nunca probada. Empieza con lo mínimo y deja que el uso real la depure y la haga crecer.
✅ Resumen del módulo
Próximo:
1.5 — 🚀 Consejos avanzados: lee el ecosistema como un profesional. Cómo interpretar el número de instalaciones, encontrar nichos vacíos y decidir cuándo NO instalar.