Cómo crear tus propias Skills para la API de Claude y usarlas con code execution, paso a paso

Una skill personalizada, creada con tres líneas de código

Crear una skill propia para usar con la API de Claude ya no requiere pasar por ninguna cabecera beta: desde que la API de Skills salió de beta, basta con empaquetar una carpeta con un archivo SKILL.md en la raíz —con un bloque YAML de cabecera indicando nombre y descripción— y subirla con una sola llamada. En Python, con el SDK oficial, el flujo se reduce a client.skills.create(files=files_from_dir("/ruta/a/la/skill")), que devuelve un identificador skill_ con el que esa skill queda disponible para cualquier solicitud del workspace. A partir de ahí, se combina con la herramienta de ejecución de código dentro de una llamada normal a la API, indicando el listado de skills que se quieren usar en el parámetro container.

Qué es exactamente una skill y cómo encaja con el resto de la API

Una skill es una carpeta de instrucciones, scripts y recursos que Claude carga dinámicamente cuando la tarea lo requiere. Hay dos orígenes distintos: las skills predefinidas de Anthropic —identificadas con nombres cortos como pptx, xlsx, docx o pdf, con versiones fechadas como 20251013 o la etiqueta latest— y las skills personalizadas que cada organización sube a su propio workspace, identificadas con un id generado automáticamente y versiones con prefijo skver_. Ambos tipos se integran exactamente de la misma forma dentro de la API: se especifican en el parámetro container junto con la herramienta code_execution_20250825, y el modelo elige de forma automática cuándo usarlas según la tarea que se le pida, cargando las instrucciones completas de la skill solo cuando resulta relevante. Es posible combinar hasta 20 skills en una misma solicitud, por ejemplo mezclando la skill de Excel de Anthropic con una skill propia que sepa construir un modelo de flujo de caja descontado siguiendo las convenciones internas de una empresa concreta.

El matiz de seguridad que la mayoría de guías rápidas no menciona

Aquí está el detalle que resulta decisivo para cualquiera que construya un producto real sobre esta API, y que muy pocas guías señalan con claridad: una skill personalizada no está vinculada a la persona que la subió, ni a una conversación, ni a una sesión concreta. Es accesible para todo el workspace: cualquier clave de API con acceso a ese workspace puede leer, invocar y eliminar cualquier skill personalizada que exista en él, sin distinción de quién la creó. Además, cualquier cuenta de servicio y cualquier usuario cuyo rol dentro de la organización permita acceso a la API puede utilizar el Workspace por defecto, además de cualquier otro workspace al que se le haya añadido explícitamente. La recomendación oficial de Anthropic para quien construya una plataforma con varios clientes o inquilinos distintos es crear un workspace separado por cada uno de ellos, porque el workspace es el límite real de aislamiento entre las skills de un cliente y las de otro; cada organización dispone de hasta 100 workspaces por defecto, ampliables contactando con el equipo de cuenta si se necesitan más.

Hay dos consideraciones prácticas más que conviene tener presentes antes de llevar esto a producción. La primera es el almacenamiento en caché de prompts: las skills se insertan en el prompt del sistema en un orden fijo, así que mantener siempre la misma lista de skills, y en el mismo orden, entre solicitudes evita romper la caché; cambiar esa lista, o dejar la versión de una skill personalizada en latest en lugar de fijarla a un id de versión concreto, puede invalidar el prefijo cacheado en cuanto alguien publique una versión nueva. La segunda es sobre retención de datos: las Agent Skills no están cubiertas por los acuerdos de retención cero de datos (ZDR); las definiciones de skills y los datos de su ejecución se conservan según la política estándar de retención de Anthropic, algo que hay que tener en cuenta antes de empaquetar lógica con información especialmente sensible dentro de una skill.

Límites técnicos del entorno de ejecución

Las skills se ejecutan dentro del contenedor de ejecución de código, con restricciones claras: no hay acceso a red, así que no pueden hacer llamadas a APIs externas por su cuenta; no permiten instalar paquetes en tiempo de ejecución, solo se puede usar lo que ya viene preinstalado en el entorno; y cada solicitud crea un contenedor aislado nuevo, salvo que se reutilice explícitamente el mismo id de contenedor entre turnos de una conversación. El tamaño total de una skill personalizada, sumando todos sus archivos sin comprimir, no puede superar los 30 MB, y el nombre declarado en la cabecera YAML tiene un máximo de 64 caracteres, solo en minúsculas, números y guiones, sin poder usar palabras reservadas como anthropic o claude.

Por qué importa hoy

Para cualquier equipo que ya use la API de Claude para generar documentos, informes o modelos con una lógica propia repetida una y otra vez —una plantilla de marca, un cálculo financiero específico del sector, un formato de informe interno—, empaquetar esa lógica como una skill personalizada, en lugar de repetirla en cada prompt, reduce el tamaño de cada solicitud y hace el comportamiento de Claude más consistente entre llamadas. El paso que no conviene saltarse antes de escalarlo a producción es decidir, desde el principio, la estructura de workspaces que va a aislar los datos de cada cliente o equipo, porque cambiar esa estructura después de tener skills y datos reales ya en marcha es mucho más costoso que planificarla desde la primera llamada a client.skills.create.