🎯 Qué vamos a construir
Vamos a crear la skill gerar-ata: pegas en el chat las notas sueltas que tomaste durante una reunión —aunque estén desordenadas, con abreviaturas y frases incompletas— y el agente te devuelve un acta con formato, con la fecha, los participantes, las decisiones y los próximos pasos separados en secciones. Es un ejemplo pequeño de propósito, pero el procedimiento de construcción es exactamente el mismo que vas a usar para cualquier skill más grande.
¿Por qué este ejemplo y no otro más llamativo? Porque tiene una entrada clara (el texto suelto), una salida clara (el acta con formato) y reglas que puedes probar en el momento: los tres ingredientes de una primera skill que enseña bien sin ahogarte en detalles.
💡 Concepto principal
- •Entrada: notas sueltas de una reunión, pegadas en el chat.
- •Resultado: acta formateada con fecha, participantes, decisiones y próximos pasos.
- •El procedimiento de construcción sirve para cualquier skill futura tuya.
📁 El esqueleto de carpetas
Toda skill empieza con una carpeta. Dentro de ella, como mínimo, un archivo `skill.md`. Como esta es una skill personal,
que quieres usar en cualquier proyecto (hablaremos más sobre esta elección en el módulo 3.5), vivirá en
~/.claude/skills/gerar-ata/ — `~` es un atajo para "carpeta personal de
tu usuario" en la terminal (el cuadro de texto donde das órdenes directamente a la computadora).
Leyenda: de la idea a la carpeta con las 4 partes de `skill.md`, hasta la prueba real y el ajuste que cierra el ciclo.
✏️ Copy-run — crear la carpeta y el archivo
Objetivo: pedirle a Claude Code que cree la estructura de carpetas de la skill.
Crie a pasta ~/.claude/skills/<nome-da-sua-skill>/ com um
arquivo skill.md vazio dentro. Não escreva conteúdo ainda,
só a estrutura.Cómo verificar: ejecuta ls ~/.claude/skills/ en el terminal y confirma que aparezca la carpeta con el archivo `skill.md`.
🏷️ Escribiendo el front matter
¿Eres nuevo aquí? Front matter es el bloque de metadatos en la parte superior de `skill.md`, entre dos líneas con tres guiones (`---`). Allí están `name` (el nombre de la skill) y `description` (la frase que el agente compara con tu solicitud para decidir si usa esa skill, tema que se profundiza en el módulo 3.4). Sin front matter, el agente ni siquiera sabe que la skill existe.
skill.md — encabezado
---
name: gerar-ata
description: Transforma anotações soltas de reunião (coladas no
chat) em uma ata formatada com data, participantes, decisões
e próximos passos. Use quando o usuário colar anotações de
reunião ou pedir "gera a ata", "organiza essa reunião".
---✓ Description específica
- ✓Indica qué entrega la skill
- ✓Indica cuándo usarlo, con frases reales del usuario
✗ Description vaga
- ✗"Ayuda con reuniones" — no dice qué ni cuándo
- ✗El agente puede no activarse nunca
📝 Escribiendo el cuerpo
Después del front matter viene el cuerpo en markdown normal: el paso a paso que sigue el agente cuando se activa la skill. Escríbelo como si estuvieras orientando a un pasante atento: breve, numerado y sin adornos.
Lee las notas pegadas
Identifica la fecha (si no la tienes, pregunta), los participantes mencionados, las decisiones tomadas y los asuntos pendientes.
Organiza el acta en 4 secciones fijas
Fecha y participantes / Agenda / Decisiones / Próximos pasos con responsable.
Muestra el acta y pregunta si falta algo
Nunca inventes una decisión que no estaba en el texto original.
💡 Consejo práctico
Si el cuerpo supera 1-2 páginas de instrucciones muy detalladas, es señal de mover parte del contenido a un archivo de referencia (módulo 3.1 y 3.2) en lugar de recargar el `skill.md` principal.
🧪 Probar y ajustar
Una skill escrita no es una skill lista: solo demuestra su valor cuando se activa de verdad, con un caso real. Pega notas de una reunión ficticia y fíjate si el agente identifica por sí solo que debe usar `gerar-ata`.
✏️ Copy-run — probar la skill
Objetivo: confirmar que la skill se active sola con lenguaje natural, sin ejecutar `/gerar-ata` manualmente.
gera a ata dessa reunião: presentes joão, marcela e eu.
falamos do orçamento de , decidimos
adiar pra semana que vem, marcela fica de mandar a planilha
até sexta. Cómo verificar: la respuesta debe venir ya formateada en las 4 secciones del tema 4 — si viene como texto corrido, vuelve al cuerpo del `skill.md` y haz más explícitas las secciones.
✓ Probada antes de usarla de verdad
- ✓Ya sabes dónde falla antes de depender de ella en una reunión importante
✗ Directo al uso real
- ✗La primera prueba es con un acta que va al cliente — riesgo alto por ahorrar 2 minutos
⚠️ Errores comunes y lista de verificación
Antes de dar por terminada la skill, repasa los errores más comunes de quienes están creando la primera.
⚠️ Atención
- Front matter mal formateado (olvidaste un `---`): la skill ni siquiera aparece para el agente.
- Descripción demasiado genérica: la skill nunca se activa sola mediante lenguaje natural.
- Cuerpo sin ejemplo: el agente entiende mal el formato en el primer intento.
✅ Lista de verificación del build
- ☐ Carpeta creada en `~/.claude/skills/`
- ☐ Front matter con `name` y `description` específica
- ☐ Cuerpo con instrucciones paso a paso numeradas
- ☐ Probada con un caso real, sin invocar `/comando` manualmente
Ejercicio: después de que `gerar-ata` esté funcionando, adáptala para un segundo caso de uso, por ejemplo, "generar resumen de llamada de ventas", cambiando solo la description y las secciones de la salida. Es el mismo esqueleto, con un propósito diferente.
Verificación rápida: ¿por qué probar la skill con un caso ficticio antes de usarla de verdad?