La API de Habilidades de Claude (Claude Skills API) está generalmente disponible a partir del 20 de agosto de 2026. Ahora puede crear, versionar y gestionar habilidades personalizadas a través de https://api.anthropic.com/v1/skills con encabezados estándar, sin necesidad de un indicador beta, y ejecutarlas dentro del sandbox de código de Claude sin necesidad de alojar nada usted mismo. Anthropic lanzó la Disponibilidad General (GA) en una sola oleada con el uso de la computadora, la nueva herramienta de navegador y la API de Archivos, enmarcado en el anuncio como la pila de producción para construir agentes en la Plataforma Claude.
Si el concepto de habilidades es nuevo para usted, nuestra guía de Habilidades de Claude cubre la idea desde cero. Este artículo trata sobre la capa de la API: los puntos finales, el modelo de versionado, la forma de la solicitud que carga las habilidades en una llamada de Mensajes, y los aspectos delicados (alcance del espacio de trabajo, versionado de instantáneas) que la GA no suavizó. Dado que todo es HTTP simple, cada llamada aquí puede construirse y probarse mediante regresión en Apidog mientras sigue el proceso.
Un repaso de 30 segundos: qué es una habilidad
Una habilidad es una carpeta. En su nivel superior se encuentra un archivo SKILL.md con un encabezado YAML (YAML frontmatter) que contiene un name y una description; a su alrededor van los scripts, plantillas y archivos de referencia que la tarea necesita. Cuando una solicitud incluye la habilidad, Claude carga las instrucciones solo cuando la tarea las requiere y ejecuta cualquier script empaquetado en su entorno de código en sandbox.
El encabezado tiene reglas de validación reales:
name: máximo 64 caracteres, solo letras minúsculas, números y guiones. No se permiten etiquetas XML, y se rechazan las palabras reservadas "anthropic" y "claude".description: no vacío, máximo 1024 caracteres.- Un
display_nameopcional (hasta 255 caracteres) puede ser más fácil de usar. - La carga completa debe permanecer por debajo de 30 MB sin comprimir.
Las habilidades provienen de dos fuentes. Las habilidades gestionadas por Anthropic (type: "anthropic") se envían preconstruidas con IDs cortos como pptx, xlsx, docx y pdf, y usan versiones basadas en fechas como 20251013. Las habilidades personalizadas (type: "custom") son suyas: subidas a través de la API, privadas para su espacio de trabajo, con IDs generados como skill_01AbCdEfGhIjKlMnOpQrStUv.
Qué cambió realmente la Disponibilidad General (GA)
Tres cosas son nuevas o se han consolidado a partir del 20 de agosto de 2026:
- Sin encabezado beta. La API de Habilidades funciona con la API de Claude con solo
x-api-keyyanthropic-version: 2023-06-01. - Un flujo de carga y versionado más simple. Anthropic describe la GA como la incorporación de "una API más simple para cargar y versionar" habilidades personalizadas. Las versiones son recursos de primera clase con sus propios puntos finales.
- Más plataformas. La API de Habilidades está disponible a través de Microsoft Foundry, así como de la API de Claude. Las habilidades se ejecutan en el sandbox gestionado de Claude, por lo que no hay infraestructura de su parte.
El resto de la ola de GA también es importante para los usuarios de habilidades: las habilidades frecuentemente generan archivos (una presentación, una hoja de cálculo rellena), y esas salidas regresan a través de la API de Archivos, que también ha alcanzado la GA.
La superficie de los puntos finales
Todo reside bajo /v1/skills:
| Operación | Punto final |
|---|---|
| Crear una habilidad | POST /v1/skills |
| Listar habilidades | GET /v1/skills |
| Recuperar una habilidad | GET /v1/skills/{skill_id} |
| Eliminar una habilidad | DELETE /v1/skills/{skill_id} |
| Crear una nueva versión | POST /v1/skills/{skill_id}/versions |
| Listar versiones | GET /v1/skills/{skill_id}/versions |
La creación de una habilidad carga su conjunto completo de archivos; la creación de una versión hace lo mismo contra un ID de habilidad existente. En un proyecto de Apidog, esto se mapea limpiamente a una carpeta de seis solicitudes guardadas con {{skill_id}} y {{skill_version}} como variables de entorno, por lo que promover una nueva versión a través de entornos de desarrollo y producción es un cambio de variable, no una edición de solicitud.
Subiendo una habilidad personalizada
Una habilidad personalizada mínima son dos cosas: la carpeta y la llamada de carga. Supongamos que mantiene una habilidad de informe de marca en su repositorio:
brand-report/
SKILL.md
templates/report.html
scripts/build_report.py
Con SKILL.md comenzando así:
---
name: brand-report
description: Generates the weekly brand performance report as a formatted HTML document from a CSV of metrics. Use when asked for a brand report, weekly summary deck, or performance writeup.
---
Súbalo publicando los archivos como datos de formulario multipart:
curl -X POST https://api.anthropic.com/v1/skills \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-F 'files[]=@brand-report/SKILL.md;filename=brand-report/SKILL.md' \
-F 'files[]=@brand-report/templates/report.html;filename=brand-report/templates/report.html' \
-F 'files[]=@brand-report/scripts/build_report.py;filename=brand-report/scripts/build_report.py'
La respuesta devuelve el skill_id generado y el ID skver_* de la primera versión. Almacene ambos; el ID de habilidad va en sus solicitudes de Mensajes, y el ID de versión es su ancla de reversión. Verifique los nombres exactos de los campos multipart contra la referencia de la API de Habilidades para su versión de SDK, ya que los ayudantes de SDK tipados envuelven esta llamada en la mayoría de los lenguajes.
Observe la descripción: parece una regla de enrutamiento. Claude decide si carga una habilidad leyendo ese campo, por lo que una descripción que enumere las frases de activación que usan sus usuarios siempre supera a una etiqueta de una sola línea.
Usando una habilidad en una solicitud de Mensajes
Las habilidades no se adjuntan a una solicitud por sí solas. Viajan en la herramienta de ejecución de código, declarada a través del parámetro container:
response = client.messages.create(
model="claude-opus-5",
max_tokens=4096,
container={
"skills": [
{"type": "anthropic", "skill_id": "pptx", "version": "latest"},
{"type": "custom", "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv", "version": "latest"}
]
},
messages=[{"role": "user", "content": "Build the Q3 revenue deck from the attached numbers"}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
Las reglas que rigen este bloque:
- La herramienta de ejecución de código debe estar habilitada en
tools, ya que las habilidades se ejecutan dentro de ese sandbox. La compatibilidad del modelo sigue la lista de compatibilidad de la herramienta de ejecución de código. - Hasta 20 habilidades por solicitud. Claude lee la descripción de cada habilidad y carga las instrucciones solo para las que la tarea necesita.
- El anclaje de versiones es suyo para controlar.
"latest"apunta a la versión más reciente; un IDskver_*anclado (o la versión de fecha para las habilidades de Anthropic) congela el comportamiento. Ancle en producción, flote en desarrollo.
Cuando una habilidad produce un documento, la respuesta lleva un file_id que descarga a través de GET /v1/files/{file_id}/content de la API de Archivos. Ese "apretón de manos" entre dos APIs (Habilidades para generar, Archivos para recuperar) es el ciclo de producción principal.
Versionado: instantáneas, no diferencias
El modelo de versionado es la parte que la mayoría de los equipos entienden mal en el primer intento. Una nueva versión es una instantánea completa, no una diferencia. Cuando hace POST /v1/skills/{skill_id}/versions, sube de nuevo todo el conjunto de archivos de la habilidad; los archivos que omite no se trasladan de la versión anterior. El name en el SKILL.md de la nueva versión también debe coincidir con el nombre existente de la habilidad.
Trate las carpetas de habilidades como artefactos de construcción: mantenga la fuente de la verdad en su repositorio, empaquete toda la carpeta en CI y publíquela como una nueva versión. La reversión es entonces trivial, ya que las versiones antiguas siguen siendo accesibles por sus IDs skver_* y un incidente de producción se resuelve redefiniendo una cadena.
Alcance del espacio de trabajo: la trampa del multi-inquilino
Las habilidades personalizadas son accesibles para todo su espacio de trabajo. No están limitadas a un usuario final, una conversación o una sesión, y cada clave API en el espacio de trabajo las comparte. Si ejecuta un producto multi-inquilino donde los inquilinos cargan sus propias habilidades, un solo espacio de trabajo es una fuga de datos a punto de ocurrir.
La solución es la misma que para la API de Archivos: cree un espacio de trabajo separado por inquilino. El espacio de trabajo es el límite de aislamiento, y cada organización obtiene hasta 100 espacios de trabajo antes de necesitar hablar con un equipo de cuentas. Las claves, los archivos y las habilidades heredan ese límite, por lo que una decisión aísla los tres.
Habilidades de larga duración: pause_turn y reutilización de contenedores
Las ejecuciones de habilidades pueden durar más de un solo turno del modelo. Dos mecánicas lo manejan:
pause_turn: cuando una respuesta se detiene constop_reason: "pause_turn", agregue el contenido del asistente a su historial de mensajes y vuelva a llamar, pasando el mismocontainer.id. El sandbox retoma donde lo dejó.- Reutilización de contenedores: el objeto
containeracepta unidde una respuesta anterior, manteniendo los archivos instalados y el estado activos a lo largo de una conversación de múltiples turnos. Esto significa que una habilidad puede construir una hoja de cálculo en el turno uno y revisarla en el turno tres sin regenerarla desde cero.
Ambos patrones son secuencias HTTP con estado, lo que los hace difíciles de probar manualmente y agradables de probar como un escenario de Apidog: la solicitud uno aserción en stop_reason, un script eleva container.id a una variable, la solicitud dos lo reutiliza, y el paso final aserción que el file_id generado se descarga limpiamente. La CLI de Apidog ejecuta el mismo escenario en CI, por lo que una actualización de versión de habilidad no puede romper silenciosamente su pipeline. Si desea ver cómo se comportan las habilidades dentro del ecosistema de otro proveedor para comparar, desglosamos la habilidad de Claude de Postman en una revisión anterior.
Dónde se ejecuta
En la GA, la API de Habilidades está disponible en la API de Claude y a través de Microsoft Foundry. Las habilidades se ejecutan en el sandbox de Anthropic de todos modos, por lo que la "implementación" es una carga, y no hay imagen de contenedor, ni parcheo en tiempo de ejecución, ni control de escalado de su parte. Tenga en cuenta la dependencia del modelo en lugar de la plataforma: la solicitud debe usar un modelo compatible con la herramienta de ejecución de código, como claude-opus-5 en los ejemplos anteriores. Nuestra guía de la API de Claude Opus 5 cubre los conceptos básicos de las solicitudes de ese modelo si está empezando.
Preguntas Frecuentes
¿Todavía necesito el encabezado beta de habilidades? No. Desde el 20 de agosto de 2026, /v1/skills y el parámetro container.skills funcionan con encabezados estándar en la API de Claude. Elimine cualquier indicador beta anclado cuando actualice su SDK.
¿Puede una habilidad llamar a APIs externas mientras se ejecuta? Las habilidades se ejecutan dentro del sandbox de código de Claude con las restricciones de red de la herramienta de ejecución de código. Incluya lo que la habilidad necesita en su carpeta en lugar de asumir una salida abierta, y mantenga la lógica de llamada a la API en su capa de aplicación donde pueda probarla correctamente.
¿Cuántas habilidades puede cargar una solicitud? Hasta 20. Claude lee el encabezado description de cada habilidad para decidir cuáles necesita la tarea, por lo que las descripciones son importantes: escríbalas como reglas de enrutamiento, no como texto de marketing.
¿Cuál es la diferencia entre esto y las habilidades de Claude Code? El mismo concepto, diferente tiempo de ejecución. Claude Code descubre carpetas de habilidades en su sistema de archivos; la API de Habilidades las aloja en el servidor, versionadas, para las llamadas a la API de Mensajes. El formato de carpeta con el encabezado SKILL.md es compartido, por lo que una habilidad que escribió para Claude Code generalmente se traslada con pocos cambios.
Conclusión
La GA convierte las habilidades de un experimento en una superficie operativa: seis puntos finales, versionado por instantáneas, aislamiento del espacio de trabajo y una entrega limpia a la API de Archivos para las salidas. Los equipos que obtienen valor más rápidamente tratan las habilidades como cualquier otro artefacto desplegable, lo que significa empaquetado en CI, versiones ancladas en producción y pruebas automatizadas alrededor del ciclo de vida del contenedor. Modele los seis puntos finales en Apidog, incorpore la actualización de versión en un escenario de prueba, y sabrá que una versión de habilidad defectuosa rompió su generador de presentaciones antes de que lo hagan sus usuarios. Descargue Apidog gratis y construya el arnés en una tarde.