Guía Práctica para Crear Habilidades de Claude: Estructura, Disparadores y Scripts

Qué son las Habilidades de Claude y cómo funcionan

Las Habilidades de Claude son manuales de instrucciones que automatizan tareas específicas, distintas de los Proyectos (bases de conocimiento) y del Protocolo de Contexto del Modelo (capa de conexión para datos en vivo). Si has escrito las mismas instrucciones al inicio de más de tres conversaciones, esa es una habilidad que pide ser creada.

Estructura y configuración de las habilidades

Una habilidad es una carpeta que contiene un archivo llamado SKILL.md. La estructura básica es:

nombre-de-tu-habilidad/
├── SKILL.md
└── references/
    └── tu-ref.md

Coloca la carpeta en ~/.claude/skills/ en tu máquina. Claude la encuentra automáticamente.

Activadores YAML: El mecanismo de activación

En la parte superior de SKILL.md, escribe metadatos entre líneas --- para indicarle a Claude cuándo activarse. Ejemplo:

---
name: limpiador-csv
description: Transforma archivos CSV desordenados en hojas de cálculo limpias. Usa esta habilidad cada vez que el usuario diga 'limpia este CSV', 'arregla los encabezados', 'formatea estos datos' u 'organiza esta hoja de cálculo'. NO usar para PDFs, documentos de Word o archivos de imagen.
---

Sigue tres reglas: escribe en tercera persona, enumera frases activadoras exactas y establece límites negativos. El campo de descripción es la línea más importante de toda la habilidad—una descripción débil significa que la habilidad nunca se activará.

Cuando las instrucciones no son suficientes: Directorio de scripts

Las instrucciones en inglés simple manejan el juicio, el lenguaje, el formato y las decisiones. Para tareas que requieren cálculo real, añade una carpeta scripts/.

Usa instrucciones para: "reescribe esto en la voz de nuestra marca" o "categoriza estas notas de reunión".

Usa scripts para: "calcula el promedio móvil de estos números", "analiza este XML y extrae campos específicos" o "redimensiona todas las imágenes en esta carpeta a 800x600".

Estructura de carpeta para una habilidad que usa ambos:

analizador-de-datos/
├── SKILL.md
├── references/
│   └── plantilla-analisis.md
└── scripts/
    ├── analizar-csv.py
    └── calcular-estadisticas.py

Dentro de SKILL.md, referencia los scripts así:

## Flujo de trabajo
1. Lee el archivo CSV subido para entender su estructura.
2. Ejecuta scripts/analizar-csv.py para limpiar los datos:
   - Comando: `python scripts/analizar-csv.py [archivo_entrada] [archivo_salida]`
   - Esto elimina filas vacías, normaliza encabezados y aplica tipos de datos.
3. Ejecuta scripts/calcular-estadisticas.py en los datos limpios:
   - Comando: `python scripts/calcular-estadisticas.py [archivo_limpio]`
   - Esto genera: media, mediana, desviación estándar y valores atípicos para cada columna numérica.
4. Lee la salida estadística y escribe un resumen legible para humanos siguiendo la plantilla en references/plantilla-analisis.md. Destaca cualquier anomalía o valor atípico que preocuparía a un lector no técnico.

Los scripts manejan el cálculo; las instrucciones manejan el juicio. Una regla para los scripts: un script, un trabajo. analizar-csv.py no debería también calcular estadísticas. Mantenlos enfocados, acepta rutas de archivo como argumentos, nunca codifiques rutas fijas, e incluye siempre manejo de errores para que Claude pueda leer los fallos y comunicarlos claramente.

Referencias: La regla de un solo nivel de profundidad

Si una habilidad necesita una guía de marca o una plantilla, colócala en references/ y enlázala desde SKILL.md. Nunca tengas archivos de referencia que enlacen a otros archivos de referencia—Claude truncará su lectura y se perderá cosas. Solo un nivel de profundidad.

nombre-de-tu-habilidad/
├── SKILL.md
└── references/
    └── guia-voz-marca.md ← enlaza a esto desde SKILL.md ← nunca enlaces a otro archivo desde aquí

En SKILL.md: Antes de comenzar la tarea, lee la guía de voz de marca en references/guia-voz-marca.md

Orquestación de múltiples habilidades: Previniendo conflictos

Una vez que tienes cinco o más habilidades implementadas, comienzan los conflictos—como que el reforzador de voz de marca se active cuando querías el redactor de correos. Tres reglas evitan esto:

• Regla 1: Territorios no superpuestos. Cada habilidad posee un dominio claramente definido (ej., el reforzador de voz de marca maneja el cumplimiento de la voz, el redactor de correos maneja la composición, el reutilizador de contenido maneja la transformación de formato). Sin mezclas.
• Regla 2: Límites negativos agresivos.