Usar Agent Skills con la API

Habilidades en la API

Agent Skills extienden las capacidades de Claude a través de carpetas organizadas de instrucciones, scripts y recursos. Esta guía te muestra cómo usar tanto Skills precompiladas como personalizadas con la API de Claude.

Para la referencia completa de la API incluyendo esquemas de solicitud/respuesta y todos los parámetros, consulta:

Referencia de API de Gestión de Skills - Operaciones CRUD para Skills
Referencia de API de Versiones de Skills - Gestión de versiones

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

Enlaces Rápidos

Comenzar con Agent Skills

Crea tu primer Skill

Crear Skills Personalizados

Mejores prácticas para crear Skills

Descripción General

Para un análisis profundo de la arquitectura y aplicaciones del mundo real de Agent Skills, lee la publicación del blog de ingeniería: Equipping agents for the real world with Agent Skills.

Skills se integran con la API de Messages a través de la herramienta de ejecución de código. Ya sea que uses Skills precompiladas gestionadas por Anthropic o Skills personalizadas que hayas cargado, la forma de integración es idéntica: ambas requieren ejecución de código y usan la misma estructura container.

Usar Skills

Skills se integran de manera idéntica en la API de Messages independientemente de la fuente. Especificas Skills en el parámetro container con un skill_id, type y opcionalmente version, y se ejecutan en el entorno de ejecución de código.

Puedes usar Skills de dos fuentes:

Aspecto	Skills de Anthropic	Skills Personalizados
Valor de Type	`anthropic`	`custom`
IDs de Skill	Nombres cortos: `pptx`, `xlsx`, `docx`, `pdf`	Generados: `skill_01AbCdEfGhIjKlMnOpQrStUv`
Formato de versión	Basado en fecha: `20251013` o `latest`	Marca de tiempo de época: `1759178010641129` o `latest`

Ambas fuentes de skills son devueltas por el endpoint List Skills (usa el parámetro source para filtrar). La forma de integración y el entorno de ejecución son idénticos. La única diferencia es de dónde provienen los Skills y cómo se gestionan.

Requisitos Previos

Para usar Skills, necesitas:

Clave de API de Claude del Console
Encabezados Beta:
- code-execution-2025-08-25 - Habilita la ejecución de código (requerido para Skills)
- skills-2025-10-02 - Habilita la API de Skills
- files-api-2025-04-14 - Para cargar/descargar archivos hacia/desde el contenedor
Herramienta de ejecución de código habilitada en tus solicitudes

Usar Skills en Messages

Parámetro Container

Skills se especifican usando el parámetro container en la API de Messages. Puedes incluir hasta 8 Skills por solicitud.

La estructura es idéntica para Skills de Anthropic y personalizados. Especifica el type y skill_id requeridos, e incluye opcionalmente version para fijar una versión específica:

Descargando archivos generados

Cuando las Skills crean documentos (Excel, PowerPoint, PDF, Word), devuelven atributos file_id en la respuesta. Debes usar la API de Archivos para descargar estos archivos.

Cómo funciona:

Las Skills crean archivos durante la ejecución del código
La respuesta incluye file_id para cada archivo creado
Usa la API de Archivos para descargar el contenido real del archivo
Guarda localmente o procesa según sea necesario

Ejemplo: Crear y descargar un archivo Excel

Operaciones adicionales de la API de Archivos:

Para obtener detalles completos sobre la API de Archivos, consulta la documentación de la API de Archivos.

Conversaciones Multi-Turno

Reutiliza el mismo contenedor en múltiples mensajes especificando el ID del contenedor:

Operaciones de Larga Duración

Las habilidades pueden realizar operaciones que requieren múltiples turnos. Maneja las razones de parada pause_turn:

La respuesta puede incluir una razón de parada pause_turn, que indica que la API pausó una operación de Habilidad de larga duración. Puedes proporcionar la respuesta tal como está en una solicitud posterior para permitir que Claude continúe su turno, o modificar el contenido si deseas interrumpir la conversación y proporcionar orientación adicional.

Usando Múltiples Skills

Combina múltiples Skills en una única solicitud para manejar flujos de trabajo complejos:

Gestión de Skills Personalizados

Creando un Skill

Carga tu Skill personalizado para que esté disponible en tu espacio de trabajo. Puedes cargar usando una ruta de directorio u objetos de archivo individuales.

Requisitos:

Debe incluir un archivo SKILL.md en el nivel superior
Todos los archivos deben especificar un directorio raíz común en sus rutas
El tamaño total de carga debe ser inferior a 30 MB
Requisitos de frontmatter YAML:
- name: Máximo 64 caracteres, solo letras minúsculas/números/guiones, sin etiquetas XML, sin palabras reservadas ("anthropic", "claude")
- description: Máximo 1024 caracteres, no vacío, sin etiquetas XML

Para esquemas completos de solicitud/respuesta, consulta la referencia de API Crear Skill.

Listando Skills

Recupera todos los Skills disponibles en tu espacio de trabajo, incluyendo tanto Skills precompilados de Anthropic como tus Skills personalizados. Usa el parámetro source para filtrar por tipo de skill:

Consulta la referencia de API Listar Skills para opciones de paginación y filtrado.

Recuperando un Skill

Obtén detalles sobre un Skill específico:

Eliminar una Skill

Para eliminar una Skill, primero debe eliminar todas sus versiones:

Intentar eliminar una Skill con versiones existentes devuelve un error 400.

Versionado

Las Skills admiten versionado para gestionar actualizaciones de forma segura:

Skills Gestionadas por Anthropic:

Las versiones utilizan formato de fecha: 20251013
Se lanzan nuevas versiones a medida que se realizan actualizaciones
Especifique versiones exactas para mayor estabilidad

Skills Personalizadas:

Marcas de tiempo de época generadas automáticamente: 1759178010641129
Use "latest" para obtener siempre la versión más reciente
Cree nuevas versiones al actualizar archivos de Skill

Consulte la referencia de API Crear Versión de Skill para obtener detalles completos.

Cómo se Cargan las Skills

Cuando especifica Skills en un contenedor:

Descubrimiento de Metadatos: Claude ve metadatos para cada Skill (nombre, descripción) en el mensaje del sistema
Carga de Archivos: Los archivos de Skill se copian en el contenedor en /skills/{directory}/
Uso Automático: Claude carga y utiliza automáticamente Skills cuando son relevantes para su solicitud
Composición: Múltiples Skills se componen juntas para flujos de trabajo complejos

La arquitectura de divulgación progresiva garantiza un uso eficiente del contexto: Claude solo carga instrucciones completas de Skill cuando es necesario.

Casos de Uso

Skills Organizacionales

Marca y Comunicaciones

Aplicar formato específico de la empresa (colores, fuentes, diseños) a documentos
Generar comunicaciones siguiendo plantillas organizacionales
Garantizar directrices de marca consistentes en todos los resultados

Gestión de Proyectos

Estructurar notas con formatos específicos de la empresa (OKRs, registros de decisiones)
Generar tareas siguiendo convenciones del equipo
Crear resúmenes de reuniones y actualizaciones de estado estandarizadas

Operaciones Comerciales

Crear informes, propuestas y análisis estándar de la empresa
Ejecutar procedimientos analíticos específicos de la empresa
Generar modelos financieros siguiendo plantillas organizacionales

Skills Personales

Creación de Contenido

Plantillas de documentos personalizadas
Formato y estilo especializados
Generación de contenido específico del dominio

Análisis de Datos

Canalizaciones de procesamiento de datos personalizadas
Plantillas de visualización especializadas
Métodos analíticos específicos de la industria

Desarrollo y Automatización

Plantillas de generación de código
Marcos de prueba
Flujos de trabajo de implementación

Ejemplo: Modelado Financiero

Combina Excel y análisis DCF personalizado Skills:

Límites y Restricciones

Límites de Solicitud

Máximo de Skills por solicitud: 8
Tamaño máximo de carga de Skill: 30 MB (todos los archivos combinados)
Requisitos de frontmatter YAML:
- name: Máximo 64 caracteres, solo letras minúsculas/números/guiones, sin etiquetas XML, sin palabras reservadas
- description: Máximo 1024 caracteres, no vacío, sin etiquetas XML

Restricciones de Entorno

Los Skills se ejecutan en el contenedor de ejecución de código con estas limitaciones:

Sin acceso a la red - No puede realizar llamadas a API externas
Sin instalación de paquetes en tiempo de ejecución - Solo paquetes preinstalados disponibles
Entorno aislado - Cada solicitud obtiene un contenedor nuevo

Consulta la documentación de la herramienta de ejecución de código para ver los paquetes disponibles.

Mejores Prácticas

Cuándo Usar Múltiples Skills

Combina Skills cuando las tareas involucran múltiples tipos de documentos o dominios:

Casos de uso recomendados:

Análisis de datos (Excel) + creación de presentaciones (PowerPoint)
Generación de reportes (Word) + exportación a PDF
Lógica de dominio personalizada + generación de documentos

Evita:

Incluir Skills no utilizados (impacta el rendimiento)

Estrategia de Gestión de Versiones

Para producción:

# Pin to specific versions for stability
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "1759178010641129",  # Specific version
        }
    ]
}

Para desarrollo:

# Use latest for active development
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest",  # Always get newest
        }
    ]
}

Consideraciones de Almacenamiento en Caché de Prompts

Cuando uses almacenamiento en caché de prompts, ten en cuenta que cambiar la lista de Skills en tu contenedor rompe el caché:

Para obtener el mejor rendimiento de almacenamiento en caché, mantén tu lista de Skills consistente en todas las solicitudes.

Manejo de errores

Maneja los errores relacionados con Skills de manera elegante:

Retención de datos

Agent Skills no están cubiertos por arreglos de ZDR. Las definiciones de Skills y los datos de ejecución se retienen de acuerdo con la política estándar de retención de datos de Anthropic.

Para elegibilidad de ZDR en todas las características, consulta API and data retention.

Próximos pasos

Referencia de API

Referencia completa de API con todos los puntos finales

Guía de autoría

Mejores prácticas para escribir Skills efectivos

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]
    },
    messages=[
        {"role": "user", "content": "Create a presentation about renewable energy"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

client = anthropic.Anthropic()
file_id = "file_abc123"
# Obtén metadatos del archivo
file_info = client.beta.files.retrieve_metadata(
    file_id=file_id, betas=["files-api-2025-04-14"]
)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# Lista todos los archivos
files = client.beta.files.list(betas=["files-api-2025-04-14"])
for file in files.data:
    print(f"{file.filename} - {file.created_at}")

# Elimina un archivo
client.beta.files.delete(file_id=file_id, betas=["files-api-2025-04-14"])

# La primera solicitud crea el contenedor
response1 = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[{"role": "user", "content": "Analyze this sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Continúa la conversación con el mismo contenedor
messages = [
    {"role": "user", "content": "Analyze this sales data"},
    {"role": "assistant", "content": response1.content},
    {"role": "user", "content": "What was the total revenue?"},
]

response2 = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "id": response1.container.id,  # Reutiliza el contenedor
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}],
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

messages = [{"role": "user", "content": "Process this large dataset"}]
max_retries = 10

response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {
                "type": "custom",
                "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                "version": "latest",
            }
        ]
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Maneja pause_turn para operaciones largas
for i in range(max_retries):
    if response.stop_reason != "pause_turn":
        break

    messages.append({"role": "assistant", "content": response.content})
    response = client.beta.messages.create(
        model="claude-opus-4-7",
        max_tokens=4096,
        betas=["code-execution-2025-08-25", "skills-2025-10-02"],
        container={
            "id": response.container.id,
            "skills": [
                {
                    "type": "custom",
                    "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                    "version": "latest",
                }
            ],
        },
        messages=messages,
        tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    )

response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {"type": "anthropic", "skill_id": "pptx", "version": "latest"},
            {
                "type": "custom",
                "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                "version": "latest",
            },
        ]
    },
    messages=[
        {"role": "user", "content": "Analyze sales data and create a presentation"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Option 1: Upload individual files (one --file flag per file)
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_skill/SKILL.md \
  --file financial_skill/analyze.py \
  --beta skills-2025-10-02

# Option 2: Upload a zip archive
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_analysis_skill.zip \
  --beta skills-2025-10-02

# Step 1: Delete all versions
ant beta:skills:versions list \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --transform version --format yaml \
  | tr -d '"' \
  | while read -r VERSION; do
      ant beta:skills:versions delete \
        --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
        --version "$VERSION" >/dev/null
    done

# Step 2: Delete the Skill
ant beta:skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

# Create a new version
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file updated_skill/SKILL.md \
  --transform version --format yaml)

# Use specific version
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<YAML
model: claude-opus-4-7
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: $VERSION_NUMBER
messages:
  - role: user
    content: Use updated Skill
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

# Use latest version
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<'YAML'
model: claude-opus-4-7
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: latest
messages:
  - role: user
    content: Use latest Skill version
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

# Create custom DCF analysis Skill
from anthropic.lib import files_from_dir

dcf_skill = client.beta.skills.create(
    display_title="DCF Analysis",
    files=files_from_dir("/path/to/dcf_skill"),
    betas=["skills-2025-10-02"],
)

# Use with Excel to create financial model
response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {"type": "custom", "skill_id": dcf_skill.id, "version": "latest"},
        ]
    },
    messages=[
        {
            "role": "user",
            "content": "Build a DCF valuation model for a SaaS company with the attached financials",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# First request creates cache
response1 = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    betas=[
        "code-execution-2025-08-25",
        "skills-2025-10-02",
        "prompt-caching-2024-07-31",
    ],
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[{"role": "user", "content": "Analyze sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Adding/removing Skills breaks cache
response2 = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    betas=[
        "code-execution-2025-08-25",
        "skills-2025-10-02",
        "prompt-caching-2024-07-31",
    ],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {
                "type": "anthropic",
                "skill_id": "pptx",
                "version": "latest",
            },  # Cache miss
        ]
    },
    messages=[{"role": "user", "content": "Create a presentation"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-4-7",
        max_tokens=4096,
        betas=["code-execution-2025-08-25", "skills-2025-10-02"],
        container={
            "skills": [
                {
                    "type": "custom",
                    "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                    "version": "latest",
                }
            ]
        },
        messages=[{"role": "user", "content": "Process data"}],
        tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    )
except anthropic.BadRequestError as e:
    if "skill" in str(e):
        print(f"Skill error: {e}")
        # Handle skill-specific errors
    else:
        raise