Cómo crear Skills en Claude paso a paso

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.

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

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

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'

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)

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)