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 Skills predefinidas y personalizadas con la Claude API.

Enlaces rápidos

Descripción general

Las Skills se integran con la Messages API a través de la “code execution tool” (herramienta de ejecución de código). Ya sea que uses Skills predefinidas administradas 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 de container.

Uso de Skills

Las Skills se integran de forma idéntica en la Messages API, sin importar su origen. Especificas las Skills en el parámetro container con un skill_id, un type y un 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 se devuelven en el endpoint List SkillsVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver. (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 administran.

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 que aparezca en su sección de compatibilidad con la API.

Uso de Skills en Messages

Parámetro container

Las Skills se especifican mediante el parámetro container en la Messages API. Puedes incluir hasta 20 Skills en 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-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 con los que trabajen las Skills, súbelos con la Files API y haz referencia a ellos en tu solicitud con un bloque de carga de contenedor.

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-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 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":
                # cada elemento de contenido es un bloque bash_code_execution_output que lleva 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 los 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 varios 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 conocer los detalles de su vida útil). 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-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 conserva 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-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 varios 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-5",
    max_tokens=4096,
    container={
        "skills": [
            {
                "type": "custom",
                "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                "version": "latest",
            }
        ]
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Gestiona 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-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 varias Skills

Combina varias Skills en una sola solicitud para manejar flujos de trabajo complejos:

client = anthropic.Anthropic()

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

Administració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 de name y description, además de cualquier script o recurso de apoyo. Consulta las mejores prácticas para la creación de Skills 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 también proporciona un helper files_from_dir que acepta una ruta de directorio, y ant apply de la CLI sube el directorio directamente.

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 úsalo en lugar del marcador de posición example_skill.zip en las opciones de carga de zip.

ant apply financial_skill

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

print("financial analysis helper")

Requisitos:

• Debe incluir un archivo SKILL.md en la raíz de la carga (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 espacio de trabajo
• El tamaño total de la carga 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 1,024 caracteres, no vacío, sin etiquetas XML

Para ver los esquemas completos de solicitud/respuesta, consulta la referencia de la API Crear SkillVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver..

Listado de Skills

Obtén todas las Skills disponibles para 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:

client = anthropic.Anthropic()

# Lista todas las Skills
for skill in client.skills.list():
    print(f"{skill.id}: {skill.display_name} (source: {skill.source.type})")

# Lista solo las Skills personalizadas
custom_skills = client.skills.list(source="custom")

Consulta la referencia de la API Listar SkillsVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver. para conocer las opciones de paginación y filtrado.

Obtención de una Skill

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

client = anthropic.Anthropic()

skill = client.skills.retrieve(skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv")

print(f"Skill: {skill.display_name}")
print(f"Latest version: {skill.latest_version_id}")
print(f"Created: {skill.created_at}")

Eliminación de una Skill

Eliminar una Skill también elimina todas sus versiones.

client = anthropic.Anthropic()

client.skills.delete(skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv")

Control de versiones

Las Skills admiten control de versiones para administrar 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.

from anthropic.lib import files_from_dir

client = anthropic.Anthropic()

# Crea una nueva versión

new_version = client.skills.versions.create(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    files=files_from_dir("financial_skill"),
)

# Usa una versión específica
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    container={
        "skills": [
            {
                "type": "custom",
                "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                "version": new_version.id,
            }
        ]
    },
    messages=[{"role": "user", "content": "Use updated Skill"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Usa la versión más reciente
response = client.messages.create(
    model="claude-opus-5-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"}],
)

Consulta la referencia de la API Crear versión de SkillVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver. para obtener todos los detalles.

Cómo se cargan las Skills

Cuando especificas Skills en un contenedor:

1. Descubrimiento de metadatos: Claude recibe los metadatos de cada Skill (nombre, descripción) en la “system prompt” (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: Varias Skills se combinan entre sí para flujos de trabajo complejos.

Claude carga las instrucciones completas de una Skill solo cuando las necesita.

Casos de uso

Las Skills se adaptan tanto al trabajo organizacional como al personal. Las organizaciones las usan para aplicar el formato de marca a los documentos, estructurar notas e informes según las plantillas de la empresa y ejecutar procedimientos analíticos específicos de la empresa. Las personas las usan para plantillas de documentos personalizadas, canalizaciones de datos especializadas y convenciones de generación de código o implementación.

Ejemplo: modelado financiero

Combina la Skill de Excel con una Skill personalizada de análisis DCF. Primero, crea la Skill personalizada de análisis DCF:

ant apply dcf_skill

Luego úsala con la Skill de Excel para crear un modelo financiero. Pasa el ID de la Skill que creaste como el skill_id de la Skill personalizada:

client = anthropic.Anthropic()

# Skill personalizada de análisis DCF (ID obtenido de la respuesta de creación de la API de Skills)
dcf_skill_id = "skill_01AbCdEfGhIjKlMnOpQrStUv"

# Úsala con Excel para crear un modelo financiero
response = client.messages.create(
    model="claude-opus-5-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 carga 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 1,024 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 varias Skills

Combina Skills cuando las tareas involucren varios 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 que no se usan (afecta el rendimiento)

Estrategia de administració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, para que las actualizaciones de la Skill nunca cambien el comportamiento de tu implementación. 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 espacio de trabajo 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 Control de versiones o de la API Listar versiones de SkillVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver.. 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 “prompt caching” (almacenamiento en caché de prompts), cambiar la lista de Skills en tu contenedor invalida la caché. Las Skills se insertan 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 compatible con la caché
response1 = client.messages.create(
    model="claude-opus-5-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] frente a [xlsx, pptx]) cambia el prefijo: fallo de caché; una lista idéntica es un acierto de caché
response2 = client.messages.create(
    model="claude-opus-5-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 almacenado en caché si cambia la descripción de la Skill.

Manejo de errores

Maneja correctamente los errores relacionados con Skills:

client = anthropic.Anthropic()

try:
    response = client.messages.create(
        model="claude-opus-5-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 los errores específicos de las 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 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. Con el SDK, llama a client.skills en lugar de client.beta.skills; mantener client.beta.skills solo funciona en las versiones del SDK que ya no envían el encabezado. Las versiones anteriores lo envían desde client.beta.skills incluso cuando no pasas nombres beta.
2. Renombra los campos en tu código: display_title a display_name y latest_version a latest_version_id. 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 medida de 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, PHP SDK 0.45.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 estructuras que client.skills, con nombres de tipo beta (BetaSkill, BetaSkillVersion, BetaDeletedSkill, BetaDeletedSkillVersion). Acepta nombres beta mediante betas para las funciones de Skills que están en beta. En los tipos beta de Messages, el tipo de referencia de 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 que no son beta. Las versiones anteriores del SDK están tipadas con las estructuras 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 de “Zero Data Retention” (retención de datos cero), o ZDR. Las definiciones de Skills y los datos de ejecución se conservan de acuerdo con la política estándar de retención de datos de Anthropic.

Para conocer la elegibilidad para 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 se pueden recuperar más adelante, así que configura la Compliance API antes de depender de este registro de auditoría.

Próximos pasos