Uso de Agent Skills con la API

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

Enlaces rápidos

Descripción general

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, un type y una version opcional, y se ejecutan en el entorno de ejecución de código.

Puedes usar Skills de dos orígenes:

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:

1. Clave de API de Claude desde la Claude Console
2. Herramienta de ejecución de código habilitada en tus solicitudes

Las Skills requieren la herramienta de ejecución de código, así que usa un modelo de su lista de compatibilidad de modelos.

Uso de Skills en Messages

Parámetro container

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

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

client = anthropic.Anthropic()

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

1. Las Skills crean archivos durante la ejecución de código.
2. La respuesta incluye un file_id para cada archivo creado, dentro de los bloques de resultado de la herramienta de ejecución de código (consulta Formato de respuesta).
3. Usa la Files API para descargar el contenido real del archivo.
4. Guárdalo localmente o procésalo según sea necesario.

Para proporcionar archivos de entrada sobre los que trabajen las Skills, súbelos con la Files API y haz referencia a ellos en tu solicitud con un bloque container upload.

Ejemplo: crear y descargar un archivo de Excel

client = anthropic.Anthropic()

# Paso 1: Usa una Skill para crear un archivo
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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 ID 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":
                # cada elemento de contenido es un bloque bash_code_execution_output que contiene un file_id
                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.files.retrieve_metadata(file_id=file_id)
    file_content = client.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_011CNha8iCJcU1wXNR6q4V8w"
# Obtener metadatos del archivo
file_info = client.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

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

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

Conversaciones de múltiples turnos

El objeto container de la respuesta contiene el id del contenedor y la marca de tiempo expires_at (consulta Reutilización de contenedores para los detalles sobre su duración). Reutiliza el mismo contenedor en varios mensajes especificando el ID del contenedor:

client = anthropic.Anthropic()

# La primera solicitud crea el contenedor
response1 = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[
        {"role": "user", "content": "Create a sample sales dataset and analyze it"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Continúa la conversación con el mismo contenedor
messages = [
    {"role": "user", "content": "Create a sample sales dataset and analyze it"},
    {
        # Conserva el texto del asistente; container.id mantiene el estado de ejecución
        "role": "assistant",
        "content": "\n".join(
            block.text for block in response1.content if block.type == "text"
        ),
    },
    {"role": "user", "content": "What was the total revenue?"},
]

response2 = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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 motivos de detención pause_turn:

client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Generate and process a large sample dataset"}]
max_retries = 10

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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 _ in range(max_retries):
    if response.stop_reason != "pause_turn":
        break

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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

Creación de una Skill

Un paquete de Skill es un directorio que contiene un archivo SKILL.md en el nivel superior con frontmatter YAML name y description, además de cualquier script o recurso de apoyo. Consulta Comienza con Agent Skills en la API para crear una, 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 workspace. Puedes subir un archivo zip u objetos de archivo individuales. El SDK de Python también proporciona un helper files_from_dir que acepta una ruta de directorio.

Los archivos se identifican por el nombre de archivo que adjuntas (el sufijo ;filename= en el ejemplo de cURL y los argumentos de nombre de archivo en los ejemplos del SDK). Para la skill del tutorial, crea un zip con zip -r financial_skill.zip financial_skill/ y sustitúyelo por el marcador de posición example_skill.zip en las opciones de subida de zip.

zip -r financial_skill.zip financial_skill/
ant skills create --file financial_skill.zip

---
name: financial-skill
description: Docs example skill.
---

print("financial analysis helper")

Requisitos:

• Debe incluir un archivo SKILL.md en la raíz de la subida (o en el nivel superior de una única carpeta contenedora)
• display_name es opcional: cuando se omite, se deriva del name de SKILL.md; un valor explícito puede tener hasta 255 caracteres y no necesita ser único dentro del workspace
• El tamaño total de la subida debe ser inferior a 30 MB (sin comprimir)
• 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 los esquemas completos de solicitud/respuesta, consulta la referencia de la API Create Skill.

Listado de Skills

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

# Listar todas las Skills
ant skills list

# Listar solo las Skills personalizadas
ant skills list --source custom

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

Recuperación de una Skill

Obtén los detalles de una Skill específica:

ant skills retrieve --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv

Eliminación de una Skill

Eliminar una Skill también elimina todas sus versiones.

ant skills delete --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

Versionado

Las Skills admiten versionado para gestionar las actualizaciones de forma segura:

Skills de Anthropic:

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

Skills personalizadas:

• IDs de versión generados automáticamente: skver_01AbCdEfGhIjKlMnOpQrStUv
• Usa "latest" para obtener siempre la versión más reciente
• Crea nuevas versiones al actualizar los archivos de la Skill

Una nueva versión es una instantánea completa, no un delta: sube el conjunto completo de archivos de la Skill cada vez. Los archivos que omitas no se conservan, y el name en el SKILL.md de la nueva versión debe coincidir con el nombre existente de la Skill. Los siguientes ejemplos vuelven a subir el paquete completo financial_skill/ de Creación de una Skill.

# Crea una nueva versión
VERSION_ID=$(ant skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file financial_skill.zip \
  --transform id \
  --raw-output)

# Usa una versión específica
ant messages create <<YAML
model: claude-opus-5
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: "$VERSION_ID"
messages:
  - role: user
    content: Use updated Skill
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

# Usa la versión más reciente
ant messages create <<YAML
model: claude-opus-5
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 todos los detalles.

Cómo se cargan las Skills

Cuando especificas Skills en un contenedor:

1. Descubrimiento de metadatos: Claude ve los metadatos de cada Skill (nombre, descripción) en la indicación del sistema.
2. Carga de archivos: Los archivos de la Skill se copian en el contenedor en /skills/{skill-name}/. El directorio es el nombre de la Skill (pptx para una Skill de Anthropic, el name de SKILL.md para una Skill personalizada), no su ID skill_01....
3. Uso automático: Claude carga y usa automáticamente las Skills cuando son relevantes para tu solicitud.
4. Composición: Múltiples Skills se combinan entre sí para flujos de trabajo complejos.

Claude carga las instrucciones completas de la Skill solo cuando es necesario.

Casos de uso

Las Skills se adaptan tanto al trabajo organizacional como al personal. Las organizaciones las usan para aplicar formato de marca a documentos, estructurar notas e informes en torno a plantillas de la empresa y ejecutar procedimientos analíticos específicos de la empresa. Las personas las usan para plantillas de documentos personalizadas, pipelines de datos especializados y convenciones de generación de código o despliegue.

Ejemplo: modelado financiero

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

from anthropic.lib import files_from_dir

client = anthropic.Anthropic()

# Crea una Skill personalizada de análisis DCF

dcf_skill = client.skills.create(
    files=files_from_dir("/path/to/dcf_skill"),
)

# Úsala con Excel para crear un modelo financiero
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response)

Límites y restricciones

Límites de solicitud

• Máximo de Skills por solicitud: 20
• Tamaño máximo de subida de una Skill: 30 MB (todos los archivos combinados, sin comprimir)
• 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: 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

Las pestañas de SDK de esta sección muestran el valor de container que debes incluir en una solicitud de Messages. Las pestañas de cURL y CLI muestran la solicitud completa.

Para producción: fija una versión específica, de modo que las actualizaciones de la Skill nunca cambien el comportamiento desplegado. Si omites version o lo estableces en "latest", las solicitudes usan la versión más reciente de la Skill, por lo que una versión subida por cualquier persona del workspace cambia de inmediato lo que ejecutan tus agentes en producción. El ID de versión proviene de la respuesta de creación de versión en Versionado o de la API List Skill Versions. El ID siempre es una cadena, así que ponlo entre comillas en JSON o YAML incluso cuando parezca numérico.

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

Para desarrollo: usa latest para obtener automáticamente la versión más reciente mientras iteras.

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

Consideraciones sobre el almacenamiento en caché de prompts

Si usas el almacenamiento en caché de prompts ("prompt caching"), cambiar la lista de Skills en tu contenedor rompe la caché. Las Skills se renderizan en la indicación del sistema en un orden fijo, por lo que la misma lista produce el mismo prefijo almacenable en caché:

client = anthropic.Anthropic()

# Las Skills se renderizan en la indicación del sistema en un orden fijo y favorable para la caché
response1 = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[{"role": "user", "content": "Analyze sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Cambiar la lista de Skills ([xlsx] vs [xlsx, pptx]) cambia el prefijo: un fallo de caché, mientras que una lista idéntica es un acierto de caché
response2 = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {
                "type": "anthropic",
                "skill_id": "pptx",
                "version": "latest",
            },  # prefix change: 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, incluido su orden, consistente entre solicitudes. Fijar las versiones de las Skills personalizadas también ayuda: con "latest", publicar una nueva versión puede invalidar el prefijo en caché si cambia la descripción de la Skill.

Manejo de errores

Maneja los errores relacionados con Skills de forma adecuada:

client = anthropic.Anthropic()

try:
    response = client.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        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 skills
    else:
        raise

Migrar desde skills-2025-10-02

La Skills API ya no está en beta y no necesita encabezado beta. Migrar desde skills-2025-10-02 es opcional: las solicitudes que aún lo envían siguen funcionando y siguen devolviendo las formas de respuesta beta, por lo que una integración existente sigue funcionando hasta que la cambies. Eliminar el encabezado cambia esas solicitudes a las formas documentadas en esta página:

Para migrar:

1. Elimina el encabezado beta. Quita anthropic-beta: skills-2025-10-02 de tus solicitudes. En los SDK, llama a client.skills en lugar de client.beta.skills; mantener client.beta.skills funciona solo en las versiones del SDK que ya no envían el encabezado. Las versiones anteriores lo envían desde client.beta.skills incluso sin argumento betas.
2. Renombra los campos en tu código: display_title a display_name, latest_version a latest_version_id, y lee source.type en lugar de comparar source con una cadena.
3. Usa IDs de versión. Dondequiera que hayas almacenado una versión en microsegundos epoch, almacena en su lugar el id de la versión, o usa latest. Las referencias a Skills en las solicitudes de Messages aceptan un ID de versión, latest o (para las Skills de Anthropic) la versión del catálogo.
4. Revisa las llamadas de eliminación. DELETE /v1/skills/{skill_id} ahora elimina todas las versiones junto con la Skill. Si dependías del rechazo de la beta como protección, agrega tu propia verificación.

Una Skill cuyas versiones fueron todas eliminadas bajo la beta no tiene una versión actual que devolver: GET /v1/skills/{skill_id} devuelve un error 400 y la Skill se omite de las respuestas de listado hasta que le subas una versión. Aún puedes eliminarla.

Espacio de nombres beta del SDK

A partir de Python SDK 1.2.0, TypeScript SDK 0.122.0, Go SDK 1.68.0, Java SDK 2.59.0, Ruby SDK 1.67.0 y C# SDK 12.44.0, client.beta.skills ya no envía skills-2025-10-02 y devuelve las mismas formas que client.skills, con nombres de tipo con prefijo Beta (BetaSkill, BetaSkillVersion, BetaDeletedSkill, BetaDeletedSkillVersion). Acepta un argumento betas para las funciones de Skills que aún están en beta. En los tipos beta de Messages, el tipo de referencia a Skill del contenedor se renombra de BetaSkill a BetaContainerSkill (mismos campos: type, skill_id, version); BetaSkill ahora nombra el recurso Skill, en correspondencia con Skill y ContainerSkill en los tipos no beta. Las versiones anteriores del SDK están tipadas con las formas beta; si dependes de esos tipos, permanece en una versión anterior hasta que migres.

Retención de datos

Las Agent Skills no están cubiertas por los acuerdos 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 ZDR de todas las funciones, consulta API y retención de datos.

Registro de auditoría

Si tu organización tiene habilitada la Compliance API, su Activity Feed registra la creación y eliminación de Skills y versiones de Skills realizadas con una clave de API de Claude o desde la Claude Console. Las operaciones que ocurren mientras la Compliance API está desactivada no se registran y no pueden recuperarse posteriormente, así que configura la Compliance API antes de depender de este registro de auditoría.

Próximos pasos