Lo que vas a aprender
- Qué son las Skills en Claude y cuándo conviene usarlas
- Cómo estructurar una Skill con su archivo SKILL.md
- Cómo empaquetar y subir una Skill vía API
- Cómo invocar una Skill desde una conversación con Claude
- Errores comunes al definir Skills y cómo evitarlos
Paso 1: Entender qué es una Skill
Una Skill (Agent Skill) es una carpeta que empaqueta instrucciones, scripts y recursos que Claude carga bajo demanda para realizar tareas específicas de forma consistente. En lugar de repetir un prompt largo cada vez, defines la lógica una sola vez y Claude la reutiliza cuando la tarea lo requiere. Cada Skill contiene como mínimo un archivo SKILL.md con metadatos (nombre, descripción) y las instrucciones en lenguaje natural. Opcionalmente puede incluir scripts de Python, plantillas o archivos de referencia. Claude decide automáticamente cuándo activar una Skill leyendo su descripción, por eso escribir una descripción clara es clave. Este modelo de 'progressive disclosure' hace que Claude solo cargue el contenido cuando es relevante, ahorrando tokens. Las Skills son ideales para procesos repetibles: generar informes con un formato fijo, procesar facturas siguiendo reglas locales (por ejemplo el IVA en España o LATAM), o aplicar guías de estilo. Antes de escribir código, define claramente qué problema repetitivo quieres resolver.
💡 Consejo: Empieza documentando en una frase qué hace tu Skill y cuándo debería activarse. Esa frase será tu descripción.
⚠️ Error común: No confundas Skills con tools/function calling: las Skills son instrucciones y recursos, no funciones ejecutables que devuelven datos externos.
Paso 2: Crear la estructura de carpetas
Toda Skill vive en su propia carpeta cuyo nombre coincide con el identificador de la Skill. Dentro va obligatoriamente el archivo SKILL.md. Vamos a crear una Skill de ejemplo llamada 'generador-facturas' que ayude a Claude a redactar facturas con formato español. Abre tu terminal y crea la estructura. Mantén nombres en minúsculas y con guiones, sin espacios ni acentos, porque el identificador se usa internamente. Una estructura limpia facilita que Claude localice recursos. Si tu Skill necesita scripts auxiliares, colócalos en una subcarpeta como scripts/. Si necesita plantillas o ejemplos de referencia, usa references/. Por ahora crearemos solo lo mínimo para que la Skill funcione y luego la ampliaremos. Esta organización sigue las convenciones oficiales de Anthropic y hará que empaquetar la Skill sea trivial en pasos posteriores.
mkdir -p generador-facturas
cd generador-facturas
touch SKILL.md
mkdir -p references💡 Consejo: Usa nombres descriptivos en el identificador: 'generador-facturas' es mejor que 'skill1' porque Claude usa señales del nombre para decidir cuándo activarla.
⚠️ Error común: Evita acentos, espacios o mayúsculas en el nombre de la carpeta; provocan errores al empaquetar y subir.
Paso 3: Escribir el archivo SKILL.md
El SKILL.md es el corazón de la Skill. Comienza con un bloque de frontmatter YAML (entre '---') que contiene 'name' y 'description'. La descripción es crítica: Claude la lee para decidir si activa la Skill, así que debe mencionar el propósito y las palabras clave del caso de uso. Después del frontmatter vienen las instrucciones en Markdown normal: explica el rol, los pasos a seguir y el formato de salida esperado. Sé específico y directo, como si escribieras un runbook para un colega. Para nuestro ejemplo definimos una Skill que genera facturas con los campos legales típicos en España (NIF, base imponible, IVA al 21%). Cuanto más concretas sean las instrucciones, más consistente será el resultado. Incluye ejemplos del formato deseado si quieres reducir ambigüedad.
---
name: generador-facturas
description: Genera facturas con formato español incluyendo NIF, base imponible e IVA. Úsala cuando el usuario pida crear, redactar o calcular una factura.
---
# Generador de facturas
Eres un asistente que genera facturas profesionales para España.
## Pasos
1. Pide o identifica: emisor, cliente, conceptos, importes y NIF.
2. Calcula la base imponible sumando los conceptos.
3. Aplica el IVA del 21% (salvo que se indique otro tipo).
4. Muestra el total (base + IVA).
## Formato de salida
- Número de factura y fecha (dd/mm/aaaa)
- Datos fiscales de emisor y cliente
- Tabla de conceptos con importes
- Base imponible, IVA y TOTAL en euros💡 Consejo: La descripción debe incluir verbos y sustantivos que el usuario realmente escribiría ('crear factura', 'calcular IVA'); así Claude activa la Skill con más precisión.
⚠️ Error común: Si el frontmatter YAML tiene mal la indentación o falta el campo 'name', la Skill será rechazada al subirla.
Paso 4: Empaquetar la Skill en un ZIP
Para subir una Skill a través de la API necesitas comprimir su carpeta en un archivo ZIP. El ZIP debe contener la carpeta raíz con el SKILL.md dentro, preservando la estructura. Desde el directorio padre de 'generador-facturas', ejecuta el comando de compresión. En macOS y Linux usa 'zip'; en Windows puedes usar PowerShell con Compress-Archive. Verifica que el ZIP contenga la ruta 'generador-facturas/SKILL.md' y no los archivos sueltos en la raíz, porque el nombre de la carpeta define el identificador de la Skill. Este paquete es autocontenido: incluye tus scripts y referencias si los añadiste. Un empaquetado correcto evita el error más común al integrar Skills.
cd ..
zip -r generador-facturas.zip generador-facturas -x '*.DS_Store'💡 Consejo: Ejecuta 'unzip -l generador-facturas.zip' para inspeccionar el contenido y confirmar que la carpeta raíz aparece correctamente.
⚠️ Error común: No comprimas estando dentro de la carpeta (perderías el directorio raíz). Hazlo desde el directorio padre.
Paso 5: Subir la Skill vía API
Ahora subimos el ZIP a Anthropic usando la API de Skills. Asegúrate de tener la variable de entorno ANTHROPIC_API_KEY exportada. El siguiente script en Python instala el SDK oficial y sube el paquete. La respuesta te devolverá un identificador de Skill y su versión, que necesitarás para invocarla. Instala primero la librería con 'pip install anthropic'. El SDK gestiona la subida multipart automáticamente. Guarda el skill_id que recibas: lo usaremos en el siguiente paso. Si trabajas desde LATAM y tu conexión es lenta, aumenta el timeout del cliente. Este proceso registra tu Skill en tu organización de Anthropic para que esté disponible en tus llamadas al modelo.
import os
from anthropic import Anthropic
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
with open("generador-facturas.zip", "rb") as f:
skill = client.beta.skills.create(
display_title="Generador de facturas",
files=[("generador-facturas.zip", f, "application/zip")],
)
print("Skill ID:", skill.id)
print("Versión:", skill.latest_version)💡 Consejo: Guarda el Skill ID en un archivo .env o gestor de secretos; lo reutilizarás cada vez que quieras usar la Skill.
⚠️ Error común: Las APIs de Skills están en beta: si recibes un 404, revisa que tu cuenta tenga el acceso beta habilitado y usa el prefijo client.beta.
Paso 6: Invocar la Skill en una conversación
Con la Skill registrada, la referenciamos al llamar a Claude mediante el parámetro de skills en la petición de mensajes. Usamos el modelo por defecto claude-opus-4-8. Claude cargará automáticamente el SKILL.md cuando el mensaje del usuario coincida con la descripción. En este ejemplo pedimos generar una factura y Claude aplicará las instrucciones definidas: cálculo de base, IVA al 21% y formato español. Observa que no repetimos las instrucciones en el prompt; la Skill se encarga de eso, manteniendo tus llamadas limpias y consistentes. Ejecuta el script y verás la factura formateada. Ya tienes un flujo reutilizable end-to-end.
import os
from anthropic import Anthropic
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
SKILL_ID = "REEMPLAZA_CON_TU_SKILL_ID"
response = client.beta.messages.create(
model="claude-opus-4-8",
max_tokens=1024,
skills=[{"skill_id": SKILL_ID, "version": "latest"}],
messages=[{
"role": "user",
"content": "Crea una factura de Estudio Nube S.L. (NIF B12345678) a Cliente López por diseño web 1500 euros y hosting 200 euros."
}],
)
print(response.content[0].text)💡 Consejo: Puedes fijar 'version' a un número concreto en producción para evitar que cambios futuros en la Skill alteren el comportamiento.
⚠️ Error común: Si Claude no aplica la Skill, casi siempre es porque la descripción no coincide con el lenguaje del usuario; ajusta el campo description y vuelve a subir.
Resultado
Has creado tu primera Skill en Claude de principio a fin: estructuraste la carpeta, escribiste un SKILL.md con instrucciones claras, empaquetaste todo en un ZIP, lo subiste mediante la API y lo invocaste en una conversación real usando claude-opus-4-8. Ahora tienes un componente reutilizable que aplica lógica consistente (en este caso generar facturas con formato español e IVA) sin repetir prompts largos, y sabes cómo iterar sobre la descripción para mejorar cuándo se activa.
