Cómo crear un skill para Claude Code paso a paso

Escribir un skill lleva diez minutos. Escribir un skill que se active cuando lo necesitas y produzca siempre el mismo tipo de resultado lleva dos o tres iteraciones. Esta guía va sobre lo segundo.

Antes de empezar: elige la tarea correcta

El primer skill de casi todo el mundo falla por la misma razón: se elige una tarea demasiado grande. «Ayúdame con el marketing» no es una tarea. «Escribe la variante B de un asunto de email para un test A/B, con la hipótesis explícita» sí lo es.

Busca algo que cumpla las tres condiciones:

• Lo has hecho al menos tres veces este mes.
• Sabrías explicárselo a alguien nuevo en cinco minutos.
• Reconoces un resultado bueno de uno malo al verlo.

Esa tercera condición es la importante. Si no sabes distinguir el resultado bueno del malo, no puedes escribir los criterios, y sin criterios el skill es solo un formato.

La estructura mínima

Una carpeta y un archivo:

~/.claude/skills/
└── resumen-reunion/
    └── SKILL.md

El nombre de la carpeta es el identificador del skill: en minúsculas, con guiones, sin acentos. Nada de Resumen Reunión.

Dentro, el archivo tiene una cabecera delimitada por tres guiones y, debajo, Markdown normal:

---
name: resumen-reunion
description: [cuándo debe usarse]
---

# [Título]

[Instrucciones]

La descripción: la parte que decide todo

El asistente no lee tus skills enteros en cada mensaje. Lee las descripciones y, con eso, decide cuál cargar. Si la descripción no menciona las palabras que tú usas de verdad, el skill no se activa nunca.

Una descripción que funciona tiene tres piezas:

1. Qué hace, en una frase con verbo.
2. Cuándo usarlo, con las expresiones reales que dirás. Incluye sinónimos y la forma coloquial.
3. Cuándo no, si hay riesgo de solaparse con otro skill.

Compara:

# Se activa poco
description: Genera resúmenes de reuniones.

# Se activa cuando toca
description: Convierte notas o una transcripción de
  reunión en un resumen con decisiones, responsables y
  fechas. Úsalo cuando el usuario pegue notas de una
  reunión, una transcripción, un acta, o pida "saca los
  acuerdos de esto" o "qué salió de la call".
  No lo uses para resumir documentos que no sean reuniones.

La segunda es más larga y por eso funciona: cubre cómo hablas tú un martes por la tarde, no cómo se llamaría la tarea en un manual.

Escribir las instrucciones

Las instrucciones se leen como un procedimiento, no como un artículo. Cuatro secciones cubren prácticamente cualquier skill:

1. El procedimiento

Pasos numerados, en imperativo. Cada paso debe ser verificable: si no puedes decir si un paso se cumplió o no, reescríbelo.

2. Los criterios

Aquí va tu conocimiento, y es lo que diferencia un skill útil de una plantilla. Qué se prioriza, qué se descarta, qué es un resultado bueno.

## Criterios
- Una decisión sin responsable no es una decisión:
  márcala como pendiente de asignar.
- Si algo se discutió pero no se cerró, va en "abierto",
  no en "acuerdos".
- No inventes fechas. Si no se dijo, escribe "sin fecha".

3. El formato de salida

Descríbelo o, mejor, enséñalo. Un ejemplo de tres líneas ahorra un párrafo de explicación y elimina la ambigüedad.

4. Los límites

Qué no debe hacer. «No propongas soluciones si no te las piden.» «No reescribas las citas literales.» Los límites evitan el 80 % de los resultados que luego hay que corregir a mano.

Probarlo (y por qué casi siempre falla la primera vez)

Prueba con tres entradas distintas: una fácil, una desordenada y una donde falte información. La tercera es la que revela si tus criterios están completos.

Cuando algo salga mal, el diagnóstico es casi siempre uno de estos tres:

Un truco que ahorra tiempo: cuando un resultado te decepcione, en vez de reescribir el skill a ciegas, pregunta qué parte de las instrucciones llevó a esa decisión. La respuesta suele señalar la línea ambigua exacta.

Compartirlo con el equipo

Mueve la carpeta a .claude/skills/ dentro del repositorio y haz commit. A partir de ahí, cualquiera que clone el proyecto tiene el skill disponible sin instalar nada.

Dos consejos que evitan discusiones más adelante:

• Trata el skill como código: pasa por pull request y se revisa. Un skill mal escrito propaga una mala práctica a todo el equipo con mucha eficiencia.
• Escribe en la cabecera del archivo por qué existe. En seis meses nadie recordará qué problema resolvía, y sin ese contexto la gente lo borra o lo duplica.

Plantilla para copiar

---
name: nombre-del-skill
description: [Qué hace, en una frase con verbo.]
  Úsalo cuando el usuario [frases reales, incluye
  sinónimos y la forma coloquial]. No lo uses para
  [caso que pertenece a otro skill].
---

# [Título de la tarea]

## Procedimiento
1. [Paso verificable]
2. [Paso verificable]
3. [Paso verificable]

## Criterios
- [Qué se prioriza y por qué]
- [Qué se descarta]
- [Qué hacer si falta información]

## Formato de salida
[Descripción breve + ejemplo corto real]

## Límites
- No [cosa que no debe hacer]
- No [cosa que no debe hacer]

Con eso tienes un skill funcionando. Si el siguiente paso es enganchar herramientas externas o automatizar algo que ocurre solo, eso ya son plugins y MCP: lo cubrimos en plugins y MCP en Claude Code.