MensajesHabilidades

Uso de Agent Skills con la API

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

Las Agent Skills extienden las capacidades de Claude mediante carpetas organizadas de instrucciones, scripts y recursos. Esta guía te muestra cómo usar Skills predefinidas y personalizadas con la API de Claude.

Para consultar la referencia completa de la API, incluidos los esquemas de solicitud/respuesta y todos los parámetros, visita:

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

Esta función no es elegible para Zero Data Retention (ZDR). Los datos se conservan de acuerdo con la política de retención estándar de la función.

Enlaces rápidos

Comienza con Agent Skills

Crea tu primera Skill

Crea Skills personalizadas

Mejores prácticas para crear Skills

Descripción general

Para profundizar en la arquitectura y las aplicaciones prácticas de las Agent Skills, lee la publicación del blog de ingeniería: Equipping agents for the real world with Agent Skills.

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

Uso de Skills

Las Skills se integran de forma idéntica en la Messages API independientemente de su origen. Especificas las 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 orígenes:

Aspecto	Skills de Anthropic	Skills personalizadas
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 epoch: `1759178010641129` o `latest`
Gestión	Predefinidas y mantenidas por Anthropic	Sube y gestiona a través de la Skills API
Disponibilidad	Disponibles para todos los usuarios	Privadas para tu espacio de trabajo

Ambos orígenes de Skills son devueltos 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 las Skills y cómo se gestionan.

Requisitos previos

Para usar Skills, necesitas:

Clave de API de Claude 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 Skills API
- files-api-2025-04-14 - Para subir/descargar archivos hacia/desde el contenedor
Herramienta de ejecución de código habilitada en tus solicitudes

Uso de Skills en Messages

Parámetro container

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

La estructura es idéntica tanto para Skills de Anthropic como personalizadas. Especifica los campos requeridos type y skill_id, y opcionalmente incluye version para fijar una versión específica:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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 las Skills crean documentos (Excel, PowerPoint, PDF, Word), devuelven atributos file_id en la respuesta. Debes usar la Files API para descargar estos archivos.

Cómo funciona:

Las Skills crean archivos durante la ejecución de código
La respuesta incluye file_id para cada archivo creado
Usa la Files API para descargar el contenido real del archivo
Guárdalo localmente o procésalo según sea necesario

Ejemplo: Crear y descargar un archivo de Excel

client = anthropic.Anthropic()

# Paso 1: Usa una Skill para crear un archivo
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)


# Paso 2: Extrae los IDs de archivo de la respuesta
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":
                # lista con tipo concreto: List[BashCodeExecutionOutputBlock]
                for file in content_item.content:
                    file_ids.append(file.file_id)
    return file_ids


# Paso 3: Descarga el archivo usando la Files API
for file_id in extract_file_ids(response):
    file_metadata = client.beta.files.retrieve_metadata(file_id=file_id)
    file_content = client.beta.files.download(file_id=file_id)

    # Paso 4: Guarda en disco
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

Operaciones adicionales de la Files API:

client = anthropic.Anthropic()
file_id = "file_abc123"
# Obtener metadatos del archivo
file_info = client.beta.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# Listar todos los archivos
files = client.beta.files.list()
for file in files.data:
    print(f"{file.filename} - {file.created_at}")

# Eliminar un archivo
client.beta.files.delete(file_id=file_id)

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

Conversaciones de múltiples turnos

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

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

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

response2 = client.beta.messages.create(
    model="claude-opus-4-8",
    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

Las Skills pueden realizar operaciones que requieren múltiples turnos. Maneja los stop reasons pause_turn:

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

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

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

    messages.append({"role": "assistant", "content": response.content})
    response = client.beta.messages.create(
        model="claude-opus-4-8",
        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 un stop reason 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.

Uso de múltiples Skills

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

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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 personalizadas

Crear una Skill

Un paquete de Skill es un directorio que contiene un archivo SKILL.md en el nivel superior con frontmatter YAML de name y description, además de cualquier script o recurso de apoyo. Consulta Comienza con Agent Skills en la API para crear uno, y la lista de Requisitos que sigue a los ejemplos para conocer todas las restricciones.

Sube tu Skill personalizada para que esté disponible en tu espacio de trabajo. Puedes subir un archivo zip u objetos de archivo individuales; el SDK de Python proporciona adicionalmente un helper files_from_dir que acepta una ruta de directorio.

# Opción 1: Subir archivos individuales (un flag --file por archivo)
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_skill/SKILL.md \
  --file financial_skill/analyze.py \
  --beta skills-2025-10-02

# Opción 2: Subir un archivo zip
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_analysis_skill.zip \
  --beta skills-2025-10-02

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 la carga debe ser inferior a 30 MB
Requisitos del 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 consultar los esquemas completos de solicitud/respuesta, visita la referencia de la API Create Skill.

Listar Skills

Recupera todas las Skills disponibles en tu espacio de trabajo, incluidas tanto las Skills predefinidas de Anthropic como tus Skills personalizadas. Usa el parámetro source para filtrar por tipo de Skill:

# Lista todas las Skills
ant beta:skills list

# Lista solo las Skills personalizadas
ant beta:skills list --source custom

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

Recuperar una Skill

Obtén detalles sobre una Skill específica:

ant beta:skills retrieve \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv

Eliminar una Skill

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

# Paso 1: Elimina todas las versiones
ant beta:skills:versions list \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --transform version --raw-output \
  | while read -r VERSION; do
      ant beta:skills:versions delete \
        --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
        --version "$VERSION" >/dev/null
    done

# Paso 2: Elimina la Skill
ant beta:skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

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

Versionado

Las Skills admiten versionado para gestionar actualizaciones de forma segura:

Skills de Anthropic:

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

Skills personalizadas:

Marcas de tiempo epoch generadas automáticamente: 1759178010641129
Usa "latest" para obtener siempre la versión más reciente
Crea nuevas versiones al actualizar los archivos de la Skill

# Crea una nueva versión
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file updated_skill/SKILL.md \
  --transform version --raw-output)

# Usa una versión específica
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<YAML
model: claude-opus-4-8
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: $VERSION_NUMBER
messages:
  - role: user
    content: Use updated Skill
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

# Usa la versión más reciente
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<'YAML'
model: claude-opus-4-8
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: latest
messages:
  - role: user
    content: Use latest Skill version
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

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

Cómo se cargan las Skills

Cuando especificas Skills en un contenedor:

Descubrimiento de metadatos: Claude ve los metadatos de cada Skill (nombre, descripción) en la indicación del sistema
Carga de archivos: Los archivos de la Skill se copian en el contenedor en /skills/{directory}/
Uso automático: Claude carga y usa automáticamente las 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 las instrucciones completas de la 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 pautas 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 las convenciones del equipo
Crear resúmenes de reuniones y actualizaciones de estado estandarizados

Operaciones de negocio

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

Skills personales

Creación de contenido

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

Análisis de datos

Pipelines de procesamiento de datos personalizados
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
Frameworks de pruebas
Flujos de trabajo de despliegue

Ejemplo: modelado financiero

Combina Skills de Excel y de análisis DCF personalizado:

# Crea una Skill personalizada de análisis DCF
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"),
)

# Úsala con Excel para crear un modelo financiero
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)
print(response)

Límites y restricciones

Límites de solicitud

Máximo de Skills por solicitud: 8
Tamaño máximo de carga de Skill: 30 MB (todos los archivos combinados)
Requisitos del 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

Restricciones del entorno

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

Sin acceso a la red: No pueden realizar llamadas a API externas
Sin instalación de paquetes en tiempo de ejecución: Solo están disponibles los paquetes preinstalados
Entorno aislado: Los contenedores están aislados; se crea un contenedor nuevo a menos que especifiques un ID de contenedor existente

Consulta 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 involucren 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 personalizada + generación de documentos

Evita:

Incluir Skills no utilizadas (afecta el rendimiento)

Estrategia de gestión de versiones

Para producción:

# Fija a versiones específicas para mayor estabilidad
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "1759178010641129",  # Specific version
        }
    ]
}

Para desarrollo:

# Usa latest para desarrollo activo
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest",  # Always get newest
        }
    ]
}

Consideraciones sobre el almacenamiento en caché de prompts

Al usar el almacenamiento en caché de prompts, ten en cuenta que cambiar la lista de Skills en tu contenedor invalida la caché:

# La primera solicitud crea la caché
response1 = client.beta.messages.create(
    model="claude-opus-4-8",
    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 o eliminar Skills invalida la caché
response2 = client.beta.messages.create(
    model="claude-opus-4-8",
    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 obtener el mejor rendimiento de caché, mantén tu lista de Skills consistente entre solicitudes.

Manejo de errores

Maneja los errores relacionados con Skills de forma adecuada:

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-4-8",
        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}")
        # Maneja errores específicos de la habilidad
    else:
        raise

Retención de datos

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

Para conocer la elegibilidad de ZDR en todas las funciones, consulta API y retención de datos.

Próximos pasos

Referencia de la API

Referencia completa de la API con todos los endpoints

Guía de creación

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?

MensajesHabilidades

Uso de Agent Skills con la API

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

Para consultar la referencia completa de la API, incluidos los esquemas de solicitud/respuesta y todos los parámetros, visita:

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

Esta función no es elegible para Zero Data Retention (ZDR). Los datos se conservan de acuerdo con la política de retención estándar de la función.

Enlaces rápidos

Comienza con Agent Skills

Crea tu primera Skill

Crea Skills personalizadas

Mejores prácticas para crear Skills

Descripción general

Para profundizar en la arquitectura y las aplicaciones prácticas de las Agent Skills, lee la publicación del blog de ingeniería: Equipping agents for the real world with Agent Skills.

Uso de Skills

Puedes usar Skills de dos orígenes:

Aspecto	Skills de Anthropic	Skills personalizadas
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 epoch: `1759178010641129` o `latest`
Gestión	Predefinidas y mantenidas por Anthropic	Sube y gestiona a través de la Skills API
Disponibilidad	Disponibles para todos los usuarios	Privadas para tu espacio de trabajo

Requisitos previos

Para usar Skills, necesitas:

Clave de API de Claude 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 Skills API
- files-api-2025-04-14 - Para subir/descargar archivos hacia/desde el contenedor
Herramienta de ejecución de código habilitada en tus solicitudes

Uso de Skills en Messages

Parámetro container

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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 las Skills crean documentos (Excel, PowerPoint, PDF, Word), devuelven atributos file_id en la respuesta. Debes usar la Files API para descargar estos archivos.

Cómo funciona:

Las Skills crean archivos durante la ejecución de código
La respuesta incluye file_id para cada archivo creado
Usa la Files API para descargar el contenido real del archivo
Guárdalo localmente o procésalo según sea necesario

Ejemplo: Crear y descargar un archivo de Excel

client = anthropic.Anthropic()

# Paso 1: Usa una Skill para crear un archivo
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)


# Paso 2: Extrae los IDs de archivo de la respuesta
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":
                # lista con tipo concreto: List[BashCodeExecutionOutputBlock]
                for file in content_item.content:
                    file_ids.append(file.file_id)
    return file_ids


# Paso 3: Descarga el archivo usando la Files API
for file_id in extract_file_ids(response):
    file_metadata = client.beta.files.retrieve_metadata(file_id=file_id)
    file_content = client.beta.files.download(file_id=file_id)

    # Paso 4: Guarda en disco
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

Operaciones adicionales de la Files API:

client = anthropic.Anthropic()
file_id = "file_abc123"
# Obtener metadatos del archivo
file_info = client.beta.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# Listar todos los archivos
files = client.beta.files.list()
for file in files.data:
    print(f"{file.filename} - {file.created_at}")

# Eliminar un archivo
client.beta.files.delete(file_id=file_id)

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

Conversaciones de múltiples turnos

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

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

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

response2 = client.beta.messages.create(
    model="claude-opus-4-8",
    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

Las Skills pueden realizar operaciones que requieren múltiples turnos. Maneja los stop reasons pause_turn:

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

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

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

    messages.append({"role": "assistant", "content": response.content})
    response = client.beta.messages.create(
        model="claude-opus-4-8",
        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 sola solicitud para manejar flujos de trabajo complejos:

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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 personalizadas

Crear una Skill

# Opción 1: Subir archivos individuales (un flag --file por archivo)
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_skill/SKILL.md \
  --file financial_skill/analyze.py \
  --beta skills-2025-10-02

# Opción 2: Subir un archivo zip
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_analysis_skill.zip \
  --beta skills-2025-10-02

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 la carga debe ser inferior a 30 MB
Requisitos del 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 consultar los esquemas completos de solicitud/respuesta, visita la referencia de la API Create Skill.

Listar Skills

# Lista todas las Skills
ant beta:skills list

# Lista solo las Skills personalizadas
ant beta:skills list --source custom

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

Recuperar una Skill

Obtén detalles sobre una Skill específica:

ant beta:skills retrieve \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv

Eliminar una Skill

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

# Paso 1: Elimina todas las versiones
ant beta:skills:versions list \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --transform version --raw-output \
  | while read -r VERSION; do
      ant beta:skills:versions delete \
        --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
        --version "$VERSION" >/dev/null
    done

# Paso 2: Elimina la Skill
ant beta:skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

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

Versionado

Las Skills admiten versionado para gestionar actualizaciones de forma segura:

Skills de Anthropic:

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

Skills personalizadas:

Marcas de tiempo epoch generadas automáticamente: 1759178010641129
Usa "latest" para obtener siempre la versión más reciente
Crea nuevas versiones al actualizar los archivos de la Skill

# Crea una nueva versión
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file updated_skill/SKILL.md \
  --transform version --raw-output)

# Usa una versión específica
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<YAML
model: claude-opus-4-8
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: $VERSION_NUMBER
messages:
  - role: user
    content: Use updated Skill
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

# Usa la versión más reciente
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<'YAML'
model: claude-opus-4-8
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: latest
messages:
  - role: user
    content: Use latest Skill version
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

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

Cómo se cargan las Skills

Cuando especificas Skills en un contenedor:

Descubrimiento de metadatos: Claude ve los metadatos de cada Skill (nombre, descripción) en la indicación del sistema
Carga de archivos: Los archivos de la Skill se copian en el contenedor en /skills/{directory}/
Uso automático: Claude carga y usa automáticamente las 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 las instrucciones completas de la 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 pautas 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 las convenciones del equipo
Crear resúmenes de reuniones y actualizaciones de estado estandarizados

Operaciones de negocio

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

Skills personales

Creación de contenido

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

Análisis de datos

Pipelines de procesamiento de datos personalizados
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
Frameworks de pruebas
Flujos de trabajo de despliegue

Ejemplo: modelado financiero

Combina Skills de Excel y de análisis DCF personalizado:

# Crea una Skill personalizada de análisis DCF
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"),
)

# Úsala con Excel para crear un modelo financiero
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)
print(response)

Límites y restricciones

Límites de solicitud

Máximo de Skills por solicitud: 8
Tamaño máximo de carga de Skill: 30 MB (todos los archivos combinados)
Requisitos del 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

Restricciones del entorno

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

Sin acceso a la red: No pueden realizar llamadas a API externas
Sin instalación de paquetes en tiempo de ejecución: Solo están disponibles los paquetes preinstalados
Entorno aislado: Los contenedores están aislados; se crea un contenedor nuevo a menos que especifiques un ID de contenedor existente

Consulta 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 involucren 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 personalizada + generación de documentos

Evita:

Incluir Skills no utilizadas (afecta el rendimiento)

Estrategia de gestión de versiones

Para producción:

# Fija a versiones específicas para mayor estabilidad
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "1759178010641129",  # Specific version
        }
    ]
}

Para desarrollo:

# Usa latest para desarrollo activo
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest",  # Always get newest
        }
    ]
}

Consideraciones sobre el almacenamiento en caché de prompts

Al usar el almacenamiento en caché de prompts, ten en cuenta que cambiar la lista de Skills en tu contenedor invalida la caché:

# La primera solicitud crea la caché
response1 = client.beta.messages.create(
    model="claude-opus-4-8",
    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 o eliminar Skills invalida la caché
response2 = client.beta.messages.create(
    model="claude-opus-4-8",
    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 obtener el mejor rendimiento de caché, mantén tu lista de Skills consistente entre solicitudes.

Manejo de errores

Maneja los errores relacionados con Skills de forma adecuada:

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-4-8",
        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}")
        # Maneja errores específicos de la habilidad
    else:
        raise

Retención de datos

Para conocer la elegibilidad de ZDR en todas las funciones, consulta API y retención de datos.

Próximos pasos

Referencia de la API

Referencia completa de la API con todos los endpoints

Guía de creación

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?

Enlaces rápidos

Descripción general

Uso de Skills

Requisitos previos

Uso de Skills en Messages

Parámetro container

Descarga de archivos generados

Conversaciones de múltiples turnos

Operaciones de larga duración

Uso de múltiples Skills

Gestión de Skills personalizadas

Crear una Skill

Listar Skills

Recuperar una Skill

Eliminar una Skill

Versionado

Cómo se cargan las 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 sobre el almacenamiento en caché de prompts

Manejo de errores

Retención de datos

Próximos pasos

Enlaces rápidos

Descripción general

Uso de Skills

Requisitos previos

Uso de Skills en Messages

Parámetro container

Descarga de archivos generados

Conversaciones de múltiples turnos

Operaciones de larga duración

Uso de múltiples Skills

Gestión de Skills personalizadas

Crear una Skill

Listar Skills

Recuperar una Skill

Eliminar una Skill

Versionado

Cómo se cargan las 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 sobre el almacenamiento en caché de prompts

Manejo de errores

Retención de datos

Próximos pasos

Enlaces rápidos

Descripción general

Uso de Skills

Requisitos previos

Uso de Skills en Messages

Parámetro container

Descarga de archivos generados

Conversaciones de múltiples turnos

Operaciones de larga duración

Uso de múltiples Skills

Gestión de Skills personalizadas

Crear una Skill

Listar Skills

Recuperar una Skill

Eliminar una Skill

Versionado

Cómo se cargan las 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 sobre el almacenamiento en caché de prompts

Manejo de errores

Retención de datos

Próximos pasos

Enlaces rápidos

Descripción general

Uso de Skills

Requisitos previos

Uso de Skills en Messages

Parámetro container

Descarga de archivos generados

Conversaciones de múltiples turnos

Operaciones de larga duración

Uso de múltiples Skills

Gestión de Skills personalizadas

Crear una Skill

Listar Skills

Recuperar una Skill

Eliminar una Skill

Versionado

Cómo se cargan las 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 sobre el almacenamiento en caché de prompts

Manejo de errores

Retención de datos

Próximos pasos