Habilidades del Agente

Uso de Agent Skills con la API

Aprende cómo usar Agent Skills para extender las capacidades de Claude a través de 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

Comienza con Agent Skills

Crea tu primer Skill

Crea 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: Equipando 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.

Uso de 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 de Listar 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 desde 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

Uso de 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:

Python

import anthropic

client = anthropic.Anthropic()

response = client.beta.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"
    }]
)

TypeScript

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

const response = await client.beta.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'
  }]
});

Shell

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: code-execution-2025-08-25,skills-2025-10-02" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 4096,
    "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"
    }]
  }'

Descarga de 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 actual
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.beta.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 de Múltiples Turnos

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

# First request creates container
response1 = client.beta.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.beta.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.beta.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.beta.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 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.

Uso de Múltiples Skills

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

response = client.beta.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"
    }]
)

Gestión de 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 inferior a 8MB
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 de Crear 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 de Listar 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 admiten versionado para gestionar actualizaciones de forma segura:

Skills Administrados por Anthropic:

Las versiones usan formato de fecha: 20251013
Nuevas versiones lanzadas 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 al actualizar 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.beta.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.beta.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 de Crear Versión de Skill 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 Empresariales

Crea informes, 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 Excel y Skills personalizados de análisis DCF:

# 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-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)
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 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 implican múltiples tipos de documentos o dominios:

Buenos casos de uso:

Análisis de datos (Excel) + creación de presentaciones (PowerPoint)
Generación de informes (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.beta.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.beta.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 manera elegante:

try:
    response = client.beta.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

Habilidades del Agente

Uso de Agent Skills con la API

Aprende cómo usar Agent Skills para extender las capacidades de Claude a través de la API.

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

Comienza con Agent Skills

Crea tu primer Skill

Crea 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: Equipando agentes para el mundo real con Agent Skills.

Uso de Skills

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

Requisitos Previos

Para usar Skills, necesitas:

Clave API de Anthropic desde 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

Uso de 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:

Python

import anthropic

client = anthropic.Anthropic()

response = client.beta.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"
    }]
)

TypeScript

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

const response = await client.beta.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'
  }]
});

Shell

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: code-execution-2025-08-25,skills-2025-10-02" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 4096,
    "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"
    }]
  }'

Descarga de 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 actual
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.beta.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 de Múltiples Turnos

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

# First request creates container
response1 = client.beta.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.beta.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.beta.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.beta.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"}]
    )

Uso de Múltiples Skills

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

response = client.beta.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"
    }]
)

Gestión de 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 inferior a 8MB
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 de Crear Skill.

Listar Skills

# 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 de Listar 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 admiten versionado para gestionar actualizaciones de forma segura:

Skills Administrados por Anthropic:

Las versiones usan formato de fecha: 20251013
Nuevas versiones lanzadas 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 al actualizar 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.beta.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.beta.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 de Crear Versión de Skill 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 Empresariales

Crea informes, 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 Excel y Skills personalizados de análisis DCF:

# 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-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)
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 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 implican múltiples tipos de documentos o dominios:

Buenos casos de uso:

Análisis de datos (Excel) + creación de presentaciones (PowerPoint)
Generación de informes (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.beta.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.beta.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 manera elegante:

try:
    response = client.beta.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