Usar Agent Skills con 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 precompilados como personalizados 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

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 nuestro blog de ingeniería: Equipar agentes para el mundo real con Agent Skills.

Skills se integran con la API de Mensajes a través de la herramienta de ejecución de código. Ya sea usando Skills precompilados administrados por Anthropic o Skills personalizados que hayas cargado, la forma de integración es idéntica—ambos 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 Mensajes 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`
Gestión	Precompilados y mantenidos por Anthropic	Carga y gestión a través de API de Skills
Disponibilidad	Disponible para todos los usuarios	Privado para tu espacio de trabajo

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 API de Anthropic de la Consola
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 Mensajes

Parámetro Container

Skills se especifican usando el parámetro container en la API de Mensajes. 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:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    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"
    }]
)

Descargar Archivos Generados

Cuando 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:

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

Ejemplo: Crear y descargar un archivo Excel

import anthropic

client = anthropic.Anthropic()

# Step 1: Use a Skill to create a file
response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    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": "Create an Excel file with a simple budget spreadsheet"
    }],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

# Step 2: Extract file IDs from the response
def extract_file_ids(response):
    file_ids = []
    for item in response.content:
        if item.type == 'bash_code_execution_tool_result':
            content_item = item.content
            if content_item.type == 'bash_code_execution_result':
                for file in content_item.content:
                    if hasattr(file, 'file_id'):
                        file_ids.append(file.file_id)
    return file_ids

# Step 3: Download the file using Files API
for file_id in extract_file_ids(response):
    file_metadata = client.beta.files.retrieve_metadata(
        file_id=file_id,
        betas=["files-api-2025-04-14"]
    )
    file_content = client.beta.files.download(
        file_id=file_id,
        betas=["files-api-2025-04-14"]
    )

    # Step 4: Save to disk
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

Operaciones adicionales de la API de Archivos:

# Get file metadata
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")

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

# Delete a file
client.beta.files.delete(
    file_id=file_id,
    betas=["files-api-2025-04-14"]
)

Para 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:

# First request creates container
response1 = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    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"}]
)

# Continue conversation with same container
messages = [
    {"role": "user", "content": "Analyze this sales data"},
    {"role": "assistant", "content": response1.content},
    {"role": "user", "content": "What was the total revenue?"}
]

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

Operaciones de Larga Duración

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

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

response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    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"}]
)

# Handle pause_turn for long operations
for i in range(max_retries):
    if response.stop_reason != "pause_turn":
        break

    messages.append({"role": "assistant", "content": response.content})
    response = client.messages.create(
        model="claude-sonnet-4-5-20250929",
        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"}]
    )

La respuesta puede incluir una razón de parada pause_turn, que indica que la API pausó una operación de Skill de larga duración. Puedes proporcionar la respuesta tal cual 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.

Usar Múltiples Skills

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

response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    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"
    }]
)

Gestionar Skills Personalizados

Crear un Skill

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

import anthropic

client = anthropic.Anthropic()

# Option 1: Using files_from_dir helper (Python only, recommended)
from anthropic.lib import files_from_dir

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

# Option 2: Using a zip file
skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=[("skill.zip", open("financial_analysis_skill.zip", "rb"))],
    betas=["skills-2025-10-02"]
)

# Option 3: Using file tuples (filename, file_content, mime_type)
skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=[
        ("financial_skill/SKILL.md", open("financial_skill/SKILL.md", "rb"), "text/markdown"),
        ("financial_skill/analyze.py", open("financial_skill/analyze.py", "rb"), "text/x-python"),
    ],
    betas=["skills-2025-10-02"]
)

print(f"Created skill: {skill.id}")
print(f"Latest version: {skill.latest_version}")

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 menor a 8MB
Frontmatter YAML: name (máximo 64 caracteres), description (máximo 1024 caracteres)

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

Listar Skills

Recupera todos los Skills disponibles para 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:

# List all Skills
skills = client.beta.skills.list(
    betas=["skills-2025-10-02"]
)

for skill in skills.data:
    print(f"{skill.id}: {skill.display_title} (source: {skill.source})")

# List only custom Skills
custom_skills = client.beta.skills.list(
    source="custom",
    betas=["skills-2025-10-02"]
)

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

Recuperar un Skill

Obtén detalles sobre un Skill específico:

skill = client.beta.skills.retrieve(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)

print(f"Skill: {skill.display_title}")
print(f"Latest version: {skill.latest_version}")
print(f"Created: {skill.created_at}")

Eliminar un Skill

Para eliminar un Skill, primero debes eliminar todas sus versiones:

# Step 1: Delete all versions
versions = client.beta.skills.versions.list(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)

for version in versions.data:
    client.beta.skills.versions.delete(
        skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
        version=version.version,
        betas=["skills-2025-10-02"]
    )

# Step 2: Delete the Skill
client.beta.skills.delete(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)

Intentar eliminar un Skill con versiones existentes devolverá un error 400.

Versionado

Skills soportan versionado para gestionar actualizaciones de forma segura: Skills Administrados por Anthropic:

Las versiones usan formato de fecha: 20251013
Nuevas versiones se lanzan cuando se realizan actualizaciones
Especifica versiones exactas para estabilidad

Skills Personalizados:

Marcas de tiempo de época generadas automáticamente: 1759178010641129
Usa "latest" para obtener siempre la versión más reciente
Crea nuevas versiones cuando actualices archivos de Skill

# Create a new version
from anthropic.lib import files_from_dir

new_version = client.beta.skills.versions.create(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    files=files_from_dir("/path/to/updated_skill"),
    betas=["skills-2025-10-02"]
)

# Use specific version
response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": new_version.version
        }]
    },
    messages=[{"role": "user", "content": "Use updated Skill"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

# Use latest version
response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    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": "Use latest Skill version"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

Consulta la referencia de API Create Skill Version para detalles completos.

Cómo se Cargan los Skills

Cuando especificas 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 usa automáticamente Skills cuando son relevantes para tu solicitud
Composición: Múltiples Skills se componen juntos para flujos de trabajo complejos

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

Casos de Uso

Skills Organizacionales

Marca y Comunicaciones

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

Gestión de Proyectos

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

Operaciones Comerciales

Crea reportes, propuestas y análisis estándar de la empresa
Ejecuta procedimientos analíticos específicos de la empresa
Genera modelos financieros siguiendo plantillas organizacionales

Skills Personales

Creación de Contenido

Plantillas de documento 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 Skills de Excel y análisis DCF personalizado:

# 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.messages.create(
    model="claude-sonnet-4-5-20250929",
    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"}]
)

Límites y Restricciones

Límites de Solicitud

Máximo de Skills por solicitud: 8
Tamaño máximo de carga de Skill: 8MB (todos los archivos combinados)
Límites de frontmatter YAML: name 64 caracteres, description 1024 caracteres

Restricciones del Entorno

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

Sin acceso a la red - No puede hacer 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 fresco

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

Mejores Prácticas

Cuándo Usar Múltiples Skills

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

Análisis de datos (Excel) + creación de presentación (PowerPoint)
Generación de reportes (Word) + exportación a PDF
Lógica de dominio personalizado + 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 romperá el caché:

# First request creates cache
response1 = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    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.messages.create(
    model="claude-sonnet-4-5-20250929",
    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"}]
)

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

Manejo de Errores

Maneja errores relacionados con Skills de forma elegante:

try:
    response = client.messages.create(
        model="claude-sonnet-4-5-20250929",
        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

Próximos Pasos

Referencia de API

Referencia completa de API con todos los endpoints

Guía de Autoría

Mejores prácticas para escribir Skills efectivos

Herramienta de Ejecución de Código

Aprende sobre el entorno de ejecución de código

Uso de las APIs

Referencia de API

SDKs

Ejemplos

APIs de terceros

Uso de la API de administración

Soporte y configuración

​Enlaces Rápidos

Comenzar con Agent Skills

Crear Skills Personalizados

​Descripción General

​Usar Skills

​Requisitos Previos

​Usar Skills en Mensajes

​Parámetro Container

​Descargar Archivos Generados

​Conversaciones Multi-Turno

​Operaciones de Larga Duración

​Usar Múltiples Skills

​Gestionar Skills Personalizados

​Crear un Skill

​Listar Skills

​Recuperar un Skill

​Eliminar un Skill

​Versionado

​Cómo se Cargan los Skills

​Casos de Uso

​Skills Organizacionales

​Skills Personales

​Ejemplo: Modelado Financiero

​Límites y Restricciones

​Límites de Solicitud

​Restricciones del Entorno

​Mejores Prácticas

​Cuándo Usar Múltiples Skills

​Estrategia de Gestión de Versiones

​Consideraciones de Almacenamiento en Caché de Prompts

​Manejo de Errores

​Próximos Pasos

Referencia de API

Guía de Autoría

Herramienta de Ejecución de Código

Enlaces Rápidos

Descripción General

Usar Skills

Requisitos Previos

Usar Skills en Mensajes

Parámetro Container

Descargar Archivos Generados

Conversaciones Multi-Turno

Operaciones de Larga Duración

Usar Múltiples Skills

Gestionar Skills Personalizados

Crear un Skill

Listar Skills

Recuperar un Skill

Eliminar un Skill

Versionado

Cómo se Cargan los Skills

Casos de Uso

Skills Organizacionales

Skills Personales

Ejemplo: Modelado Financiero

Límites y Restricciones

Límites de Solicitud

Restricciones del Entorno

Mejores Prácticas

Cuándo Usar Múltiples Skills

Estrategia de Gestión de Versiones

Consideraciones de Almacenamiento en Caché de Prompts

Manejo de Errores

Próximos Pasos