Cómo crear tu primera skill de Claude paso a paso: el archivo SKILL.md

Una skill es, en esencia, una carpeta con un archivo de texto. Esa sencillez es su mayor virtud: si sabes escribir instrucciones claras para un compañero nuevo, sabes crear una skill. Esta guía te lleva de cero a una skill que Claude usa sola cuando toca.

Qué contiene una skill

La estructura mínima es una carpeta con un archivo SKILL.md. A partir de ahí puedes añadir lo que necesites:

informe-semanal/
├── SKILL.md          ← obligatorio: cuándo usarla y cómo
├── plantilla.md      ← opcional: material de referencia
└── scripts/
    └── resumen.py    ← opcional: código que Claude puede ejecutar

El SKILL.md empieza con un bloque de metadatos (frontmatter YAML) y sigue con las instrucciones en Markdown:

---
name: informe-semanal
description: Redacta el informe semanal de resultados del equipo a partir de las notas y cifras que el usuario pegue. Úsala cuando pidan "informe semanal", "resumen de la semana" o "reporte para dirección".
---

# Informe semanal

## Objetivo
Producir un informe de una página para dirección.

## Pasos
1. Pide las cifras clave si faltan (ventas, incidencias, hitos).
2. Estructura: Resumen (3 líneas), Cifras, Riesgos, Próximos pasos.
3. Tono directo, sin adjetivos vacíos. Cada cifra con su variación frente a la semana anterior.

Paso a paso

1. Elige una tarea que repites a menudo y que siempre explicas igual (un informe, una revisión, un formato de correo).
2. Haz la tarea una vez con Claude en conversación normal y anota qué correcciones tuviste que darle.
3. Convierte esas correcciones en instrucciones: orden de los pasos, formato de salida, lo que NO debe hacer.
4. Crea la carpeta y el SKILL.md con un name en minúsculas y con guiones, y una description que diga qué hace y cuándo usarla.
5. Colócala donde Claude la encuentre: en Claude Code, en la carpeta de skills de tu proyecto (.claude/skills/) o en la personal (~/.claude/skills/); en Claude.ai, súbela desde los ajustes de capacidades.
6. Pruébala con tres peticiones distintas, incluida una que NO debería activarla, y ajusta la descripción hasta que acierte las tres.

Cuándo añadir scripts

Si una parte de la tarea es determinista (calcular, convertir un formato, validar un campo), no se la pidas a Claude en prosa: guárdala como script dentro de la skill e indica en el SKILL.md cuándo ejecutarlo. Ejecutar código es más fiable y más barato que razonar la misma operación cada vez.

Errores habituales

• Descripción genérica («ayuda con documentos»). Sé específico: qué entrega produce y qué frases del usuario la activan.
• Un SKILL.md gigante. Si pasa de unos cientos de líneas, divide: deja lo esencial en el archivo principal y mueve el detalle a ficheros aparte que se lean solo cuando hagan falta.
• Instrucciones que explican lo obvio. Claude ya sabe escribir bien; cuéntale lo que es tuyo: tu formato, tus reglas, tus excepciones.
• No probarla. Una skill sin pruebas es una hipótesis. Guarda tus tres peticiones de prueba y repítelas cada vez que cambies algo.

Un prompt para que Claude te ayude a escribirla

Siguiente paso

Cuando tengas una skill funcionando, compártela con tu equipo versionándola en el repositorio del proyecto: las instrucciones de «cómo trabajamos aquí» dejan de vivir en la cabeza de una persona y pasan a ser un archivo revisable.