Agent Skills

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 que uses Skills precompilados gestionados 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 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 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:

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-6",
    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"
    }]
)

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 real del archivo
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-opus-4-6",
    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-opus-4-6",
    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-opus-4-6",
    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-opus-4-6",
    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-opus-4-6",
        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-opus-4-6",
    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

Creación de 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 Create Skill.

Listado de 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.

Recuperación de 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}")

Eliminación de 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

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
Especifica versiones exactas para estabilidad

Skills Personalizadas:

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

# Crear una nueva versión
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"]
)

# Usar versión específica
response = client.beta.messages.create(
    model="claude-opus-4-6",
    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"}]
)

# Usar versión más reciente
response = client.beta.messages.create(
    model="claude-opus-4-6",
    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 Crear Versión de Skill para obtener detalles completos.

Cómo se Cargan las 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 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 reportes, 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 Skills de análisis DCF personalizadas y Excel:

# Crear Skill de análisis DCF personalizado
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"]
)

# Usar con Excel para crear modelo financiero
response = client.beta.messages.create(
    model="claude-opus-4-6",
    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 de Entorno

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

Buenos casos de uso:

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

Evita:

Incluir Skills no utilizadas (impacta el rendimiento)

Estrategia de Gestión de Versiones

Para producción:

# Fijar versiones específicas para estabilidad
container={
    "skills": [{
        "type": "custom",
        "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
        "version": "1759178010641129"  # Versión específica
    }]
}

Para desarrollo:

# Usar latest para desarrollo activo
container={
    "skills": [{
        "type": "custom",
        "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
        "version": "latest"  # Siempre obtener la más nueva
    }]
}

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

# Primera solicitud crea caché
response1 = client.beta.messages.create(
    model="claude-opus-4-6",
    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"}]
)

# Agregar/eliminar Skills rompe el caché
response2 = client.beta.messages.create(
    model="claude-opus-4-6",
    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"}  # Fallo de caché
        ]
    },
    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.beta.messages.create(
        model="claude-opus-4-6",
        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}")
        # Manejar errores específicos de Skill
    else:
        raise

Próximos Pasos

Referencia de API

Referencia de API completa con todos los puntos finales

Guía de Autoría

Mejores prácticas para escribir Skills efectivas

Herramienta de Ejecución de Código

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

Was this page helpful?

Agent Skills

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

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-6",
    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"
    }]
)

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 real del archivo
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-opus-4-6",
    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-opus-4-6",
    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-opus-4-6",
    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-opus-4-6",
    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-opus-4-6",
        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-opus-4-6",
    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

Creación de 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 Create Skill.

Listado de 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 List Skills para opciones de paginación y filtrado.

Recuperación de 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}")

Eliminación de 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

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
Especifica versiones exactas para estabilidad

Skills Personalizadas:

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

# Crear una nueva versión
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"]
)

# Usar versión específica
response = client.beta.messages.create(
    model="claude-opus-4-6",
    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"}]
)

# Usar versión más reciente
response = client.beta.messages.create(
    model="claude-opus-4-6",
    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 Crear Versión de Skill para obtener detalles completos.

Cómo se Cargan las 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 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 reportes, 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 Skills de análisis DCF personalizadas y Excel:

# Crear Skill de análisis DCF personalizado
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"]
)

# Usar con Excel para crear modelo financiero
response = client.beta.messages.create(
    model="claude-opus-4-6",
    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 de Entorno

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

Buenos casos de uso:

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

Evita:

Incluir Skills no utilizadas (impacta el rendimiento)

Estrategia de Gestión de Versiones

Para producción:

# Fijar versiones específicas para estabilidad
container={
    "skills": [{
        "type": "custom",
        "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
        "version": "1759178010641129"  # Versión específica
    }]
}

Para desarrollo:

# Usar latest para desarrollo activo
container={
    "skills": [{
        "type": "custom",
        "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
        "version": "latest"  # Siempre obtener la más nueva
    }]
}

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

# Primera solicitud crea caché
response1 = client.beta.messages.create(
    model="claude-opus-4-6",
    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"}]
)

# Agregar/eliminar Skills rompe el caché
response2 = client.beta.messages.create(
    model="claude-opus-4-6",
    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"}  # Fallo de caché
        ]
    },
    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.beta.messages.create(
        model="claude-opus-4-6",
        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}")
        # Manejar errores específicos de Skill
    else:
        raise

Próximos Pasos

Referencia de API

Referencia de API completa con todos los puntos finales

Guía de Autoría

Mejores prácticas para escribir Skills efectivas

Herramienta de Ejecución de Código

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

Was this page helpful?