Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Los Agent Skills extienden las capacidades de Claude mediante carpetas organizadas de instrucciones, scripts y recursos. Esta guía te muestra cómo usar Skills predefinidos y personalizados con la API de Claude.
Aprende a usar Agent Skills para crear documentos con la API de Claude en menos de 10 minutos.
Aprende a escribir Skills efectivos que Claude pueda descubrir y usar con éxito.
Los Skills se integran con la API de Messages a través de la herramienta de ejecución de código. Ya sea que uses Skills predefinidos gestionados por Anthropic o Skills personalizados que hayas subido, la forma de integración es idéntica: ambos requieren ejecución de código y usan la misma estructura de container.
Los Skills se integran de forma idéntica en la API de Messages independientemente de su origen. Especificas los 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 personalizados |
|---|---|---|
| Valor de type | anthropic | custom |
| IDs de Skill | Nombres cortos: pptx, xlsx, docx, pdf | Generados: skill_01AbCdEfGhIjKlMnOpQrStUv |
| Formato de versión | Basado en fecha: 20251013 o latest | Marca de tiempo epoch: 1759178010641129 o latest |
| Gestión | Predefinidos y mantenidos por Anthropic | Súbelos y gestiónalos a través de la API de Skills |
| Disponibilidad | Disponibles para todos los usuarios | Privados 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 los Skills y cómo se gestionan.
Para usar Skills, necesitas:
code-execution-2025-08-25 - Habilita la ejecución de código (requerida para Skills)skills-2025-10-02 - Habilita la API de Skillsfiles-api-2025-04-14 - Requerido solo cuando usas la API de Files para subir archivos de entrada o descargar archivos que produce un SkillLos Skills requieren la herramienta de ejecución de código, así que usa un modelo de su lista de compatibilidad de modelos.
Los Skills se especifican usando el parámetro container en la API de Messages. Puedes incluir hasta 8 Skills por cada solicitud.
La estructura es idéntica tanto para Skills de Anthropic como personalizados. Especifica los campos obligatorios 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-5",
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"}],
)Cuando los Skills crean documentos (Excel, PowerPoint, PDF, Word), devuelven atributos file_id en la respuesta. Debes usar la API de Files para descargar estos archivos.
Cómo funciona:
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).Para proporcionar archivos de entrada con los que los Skills puedan trabajar, súbelos con la API de Files 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.beta.messages.create(
model="claude-opus-5",
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":
# 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.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 API de Files:
client = anthropic.Anthropic()
file_id = "file_011CNha8iCJcU1wXNR6q4V8w"
# 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
for file in client.beta.files.list():
print(f"{file.filename} - {file.created_at}")
# Eliminar un archivo
client.beta.files.delete(file_id=file_id)El objeto container de la respuesta contiene el id del contenedor y la marca de tiempo expires_at (consulta Reutilización de contenedores para detalles sobre el tiempo de vida). Reutiliza el mismo contenedor en múltiples mensajes especificando el ID del contenedor:
client = anthropic.Anthropic()
# La primera solicitud crea el contenedor
response1 = client.beta.messages.create(
model="claude-opus-5",
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 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"},
{
# Transfiere 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.beta.messages.create(
model="claude-opus-5",
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"}],
)Los Skills pueden realizar operaciones que requieren múltiples turnos. Maneja los motivos de parada pause_turn:
client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Generate and process a large sample dataset"}]
max_retries = 10
response = client.beta.messages.create(
model="claude-opus-5",
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"}],
)
# Manejar 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.beta.messages.create(
model="claude-opus-5",
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"}],
)Combina múltiples Skills en una sola solicitud para manejar flujos de trabajo complejos:
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-opus-5",
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"}],
)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 Primeros pasos 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 personalizado para que esté disponible en tu espacio de trabajo. Puedes subir un archivo zip o archivos 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. Las cargas de archivos individuales deben mantener un directorio común de nivel superior en sus rutas (el sufijo ;filename= en el ejemplo de cURL y los argumentos de nombre de archivo en los ejemplos del SDK). Un archivo zip debe contener el directorio del Skill como su única entrada de nivel superior. Para el Skill del tutorial, crea uno con zip -r financial_skill.zip financial_skill/ y sustitúyelo por el marcador de posición example_skill.zip en las opciones de carga de zip.
ant beta:skills create \
--file example_skill.zip \
--beta skills-2025-10-02
# La carga por archivo requiere nombres de archivo calificados con ruta, que la CLI
# no puede establecer actualmente. En su lugar, carga un archivo zip.Requisitos:
SKILL.md en el nivel superiorname en el frontmatter de SKILL.md (sin distinguir mayúsculas ni guiones bajos: Financial_Skill coincide con financial-skill)display_title es opcional: cuando se omite, se deriva del name de SKILL.md; un valor explícito debe ser único entre los Skills personalizados de tu espacio de trabajoname: 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 XMLPara consultar los esquemas completos de solicitud/respuesta, visita la referencia de la API Create Skill.
Recupera todos los Skills disponibles en tu espacio de trabajo, incluidos tanto los Skills predefinidos de Anthropic como tus Skills personalizados. Usa el parámetro source para filtrar por tipo de Skill:
# Listar todas las Skills
ant beta:skills list
# Listar solo las Skills personalizadas
ant beta:skills list --source customConsulta la referencia de la API List Skills para conocer las opciones de paginación y filtrado.
Obtén detalles sobre un Skill específico:
ant beta:skills retrieve \
--skill-id skill_01AbCdEfGhIjKlMnOpQrStUvPara eliminar un Skill, primero debes eliminar todas sus versiones:
# Paso 1: Lista las versiones y luego elimina cada una
ant beta:skills:versions list \
--skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
--transform version \
--raw-output
# Repite para cada id de versión que devolvió la lista
ant beta:skills:versions delete \
--skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
--version 1759178010641129 >/dev/null
# Paso 2: Elimina la Skill
ant beta:skills delete \
--skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/nullIntentar eliminar un Skill con versiones existentes devuelve un error 400.
Los Skills admiten versionado para gestionar las actualizaciones de forma segura:
Skills de Anthropic:
20251013Skills personalizados:
1759178010641129"latest" para obtener siempre la versión más recienteUna nueva versión es una instantánea completa, no un delta: sube el conjunto completo de archivos del Skill cada vez, bajo el mismo nombre de directorio de nivel superior usado en la creación. Los archivos que omitas no se conservan. Los siguientes ejemplos vuelven a subir el paquete completo financial_skill/ de Creación de un Skill.
# Crea una nueva versión
VERSION_NUMBER=$(ant beta:skills:versions create \
--skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
--file financial_skill.zip \
--transform version \
--raw-output)
# Usa una versión específica
ant beta:messages create \
--beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-5
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,skills-2025-10-02 <<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
YAMLConsulta la referencia de la API Create Skill Version para obtener detalles completos.
Cuando especificas Skills en un contenedor:
/skills/{skill-name}/. El directorio es el nombre del Skill (pptx para un Skill de Anthropic, el name de SKILL.md para un Skill personalizado), no su ID skill_01....Claude carga las instrucciones completas del Skill solo cuando es necesario.
Los Skills se adaptan tanto al trabajo organizacional como al personal. Las organizaciones los 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 los usan para plantillas de documentos personalizadas, pipelines de datos especializados y convenciones de generación de código o despliegue.
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.beta.skills.create(
files=files_from_dir("/path/to/dcf_skill"),
)
# Úsala con Excel para crear un modelo financiero
response = client.beta.messages.create(
model="claude-opus-5",
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",
}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response)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 XMLLos Skills se ejecutan en el contenedor de ejecución de código con estas limitaciones:
Consulta Herramienta de ejecución de código para ver los paquetes disponibles.
Combina Skills cuando las tareas involucren múltiples tipos de documentos o dominios:
Buenos casos de uso:
Evita:
Las pestañas del SDK en 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 del Skill nunca cambien el comportamiento de tu despliegue. 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: encierra entre comillas los IDs de marca de tiempo epoch en JSON o YAML.
# Fija a versiones específicas para mayor estabilidad
container = {
"skills": [
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "1759178010641129",
}
]
}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",
}
]
}Si usas almacenamiento en caché de prompts, cambiar la lista de Skills en tu contenedor invalida la caché. Los Skills se renderizan en la indicación del sistema en un orden fijo, por lo que la misma lista produce el mismo prefijo cacheable:
client = anthropic.Anthropic()
# Las Skills se renderizan en la indicación del sistema en un orden fijo y favorable para la caché
response1 = client.beta.messages.create(
model="claude-opus-5",
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 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.beta.messages.create(
model="claude-opus-5",
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",
}, # 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 los Skills personalizados también ayuda: con "latest", publicar una nueva versión puede invalidar el prefijo en caché si cambia la descripción del Skill.
Maneja los errores relacionados con Skills de forma adecuada:
client = anthropic.Anthropic()
try:
response = client.beta.messages.create(
model="claude-opus-5",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest",
}
]
},
messages=[{"role": "user", "content": "Process data"}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
except anthropic.BadRequestError as e:
if "skill" in str(e):
print(f"Skill error: {e}")
# Manejar errores específicos de la habilidad
else:
raiseLos Agent Skills no están cubiertos 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.
Referencia completa de la API con todos los endpoints
Aprende a escribir Skills efectivos que Claude pueda descubrir y usar con éxito.
Ejecuta código Python y bash en un contenedor aislado para analizar datos, generar archivos e iterar sobre soluciones.
Was this page helpful?