Skills OpenAI API: crea capacidades reutilizables para agentes
Skills OpenAI API permite crear capacidades reutilizables que pueden incorporarse a entornos de agentes y modelos compatibles de OpenAI. Una Skill puede agrupar archivos, instrucciones y recursos relacionados con una tarea concreta, disponer de versiones independientes y utilizar una versión predeterminada para mantener workflows consistentes y reutilizables.
¿Qué es Skills OpenAI API?
Skills OpenAI API es una API para crear y administrar paquetes reutilizables de capacidades. Las Skills pueden contener archivos, disponer de versiones y utilizarse como referencias dentro de entornos de agentes. Esto permite separar conocimientos operativos, instrucciones y recursos específicos del prompt principal de una aplicación.
Qué permite hacer Skills OpenAI API
Skills introduce una capa reutilizable para organizar capacidades utilizadas por agentes.
Crear Skills
Crear un recurso reutilizable asociado al proyecto.
Adjuntar archivos
Subir un directorio o un bundle ZIP con el contenido de la Skill.
Versionar
Crear versiones inmutables de una Skill a medida que evoluciona.
Versión por defecto
Seleccionar qué versión debe utilizarse como referencia principal.
Descargar contenido
Recuperar el bundle ZIP asociado a una Skill o versión concreta.
Reutilizar en agentes
Referenciar Skills dentro de configuraciones de entornos agentic.
Cómo funciona Skills en OpenAI API
Una Skill puede crearse, versionarse y posteriormente incorporarse a un entorno utilizado por un agente.
Preparas la Skill
Organizas instrucciones, archivos y recursos necesarios para la capacidad.
Publicas una versión
El contenido se almacena como una versión identificable e inmutable.
La reutilizas
El entorno del agente puede referenciar esa Skill y su versión.
Skills OpenAI API dispone de endpoints propios
Skills no es únicamente una propiedad de Responses API. OpenAI dispone de recursos específicos para administrar Skills.
| Operación | Endpoint |
|---|---|
| Crear Skill | POST /v1/skills |
| Listar Skills | GET /v1/skills |
| Obtener Skill | GET /v1/skills/{skill_id} |
| Actualizar versión por defecto | POST /v1/skills/{skill_id} |
| Eliminar Skill | DELETE /v1/skills/{skill_id} |
| Descargar contenido | GET /v1/skills/{skill_id}/content |
Cómo crear una Skill en OpenAI API
La API permite crear una Skill cargando archivos desde un directorio o mediante un archivo ZIP.
Crear una Skill
from openai import OpenAI
client = OpenAI()
skill = client.skills.create(
files=["./mi-skill"]
)
print(skill.id)La referencia actual permite proporcionar archivos de un directorio o un único bundle ZIP al crear una Skill.
Qué información contiene una Skill
Una Skill tiene su propia identidad, descripción y referencias a sus versiones.
| Campo | Significado |
|---|---|
id |
Identificador único de la Skill |
name |
Nombre de la Skill |
description |
Descripción de su finalidad |
default_version |
Versión utilizada como predeterminada |
latest_version |
Versión más reciente disponible |
created_at |
Momento de creación del recurso |
Versiones de Skills OpenAI API
Una de las capacidades más importantes de Skills es el versionado.
Las versiones son inmutables
La documentación define cada Skill Version como una versión inmutable. Cuando necesitas cambiar el contenido, puedes crear una nueva versión en lugar de modificar la anterior.
Una versión inmutable permite conservar exactamente la capacidad que estaba utilizando un agente en un momento determinado.
Endpoints para versiones de una Skill
Las versiones tienen recursos propios dentro de Skills API.
| Operación | Endpoint |
|---|---|
| Crear versión | POST /skills/{skill_id}/versions |
| Listar versiones | GET /skills/{skill_id}/versions |
| Obtener versión | GET /skills/{skill_id}/versions/{version} |
| Eliminar versión | DELETE /skills/{skill_id}/versions/{version} |
| Descargar contenido | GET /skills/{skill_id}/versions/{version}/content |
Cómo publicar una nueva versión de una Skill
Cuando cambian los archivos o instrucciones, puedes publicar una nueva versión manteniendo la anterior.
Crear una versión
openai skills:versions create \
--skill-id skill_123 \
--files ./mi-skillAl crear una versión, la API contempla una opción para establecerla como versión predeterminada.
Qué diferencia hay entre latest_version y default_version
No necesariamente la versión más reciente debe utilizarse automáticamente en producción.
| Campo | Función |
|---|---|
latest_version |
Indica la versión más nueva disponible |
default_version |
Indica la versión elegida como predeterminada |
Puedes publicar
una nueva versión,
probarla
y cambiar posteriormente
el puntero
default_version.
Cambiar la versión predeterminada de una Skill
Skills API permite actualizar el puntero de versión predeterminada sin modificar las versiones existentes.
Actualizar default_version
POST /v1/skills/skill_123
{
"default_version": "3"
}Cómo referenciar una Skill en un agente
Las configuraciones de agentes pueden incluir referencias a Skills existentes.
ID de Skill + versión
{
"skill_id": "skill_123",
"type": "skill_reference",
"version": "3"
}Fijar explícitamente una versión ayuda a evitar que un cambio posterior modifique inesperadamente el comportamiento de un workflow.
Skills almacenadas vs Skills inline
La referencia de Responses API también contempla estructuras de Skill inline.
| Opción | Uso general |
|---|---|
| Skill almacenada | Reutilización y versionado mediante Skills API |
| Skill reference | Referencia una Skill y una versión existente |
| Inline Skill | Define una Skill directamente dentro de la configuración compatible |
El contenido de una Skill puede descargarse como ZIP
Skills API dispone de endpoints específicos para recuperar el contenido almacenado.
Descargar el bundle
GET /v1/skills/{skill_id}/contentPuedes recuperar el contenido de una versión específica para conservar o inspeccionar exactamente ese bundle.
Skills OpenAI API vs prompts
Una Skill no debería entenderse simplemente como un prompt largo.
| Aspecto | Skills | Prompt |
|---|---|---|
| Reutilización | Diseñadas para reutilizarse | Puede repetirse manualmente |
| Archivos | Puede agrupar contenido | No necesariamente |
| Versionado | API de versiones propia | Depende de tu aplicación |
| Identificador | skill_id | No necesariamente |
| Uso en agentes | Puede referenciarse | Se incorpora como instrucciones |
Skills vs Function Calling
Skills y Function Calling resuelven capas diferentes de un agente.
| Aspecto | Skills | Function Calling |
|---|---|---|
| Objetivo | Empaquetar capacidades y recursos | Solicitar una función externa |
| Ejecución backend | No es necesariamente su objetivo | Sí |
| Versionado | Nativo en Skills API | Gestionado por tu aplicación |
| Uso | Comportamiento reutilizable | Acciones estructuradas |
Una Skill puede enseñar o estructurar cómo realizar una tarea, mientras una función permite ejecutar una operación concreta del backend.
Ver Function Calling →Skills vs Tool Search
Tool Search ayuda a localizar herramientas, mientras Skills empaqueta capacidades reutilizables.
| Aspecto | Skills | Tool Search |
|---|---|---|
| Objetivo | Reutilizar una capacidad | Encontrar herramientas relevantes |
| Versionado | Sí | No es su objetivo principal |
| Archivos | Puede contener bundles | Trabaja con catálogos de tools |
| Uso típico | Procedimientos reutilizables | Catálogos grandes de herramientas |
Un agente avanzado puede disponer de Skills y además utilizar Tool Search para descubrir herramientas externas.
Ver Tool Search →Casos de uso de Skills OpenAI API
Skills resulta útil cuando una organización necesita reutilizar procedimientos o capacidades especializadas.
Desarrollo: convenciones de código, procesos de revisión y workflows técnicos.
Documentos: reglas para crear determinados tipos de entregables.
Empresas: procedimientos internos reutilizables.
Datos: metodologías específicas para analizar información.
Agentes: capacidades especializadas que pueden incorporarse a distintos entornos.
Equipos: estandarizar cómo diferentes agentes realizan una tarea.
Por qué versionar Skills es importante
Los agentes pueden formar parte de procesos empresariales importantes.
Puedes conservar una versión estable.
Crear una nueva sin sobrescribir la anterior.
Probarla antes de convertirla en predeterminada.
Volver a una versión conocida si una actualización no funciona como esperabas.
Auditar qué versión utilizaba un agente.
Modelos OpenAI compatibles con Skills
Skills aparece entre las herramientas soportadas por varios modelos actuales de OpenAI.
| Modelo | Skills | Orientación |
|---|---|---|
| GPT-5.6 Sol | Compatible | Trabajo profesional y agentes complejos |
| GPT-5.6 Terra | Compatible | Equilibrio capacidad/costo |
| GPT-5.6 Luna | Compatible | Alto volumen y costo optimizado |
| Chat Latest | No compatible | Chat general |
OpenAI publica explícitamente qué herramientas soporta cada modelo mediante Responses API.
Comparar modelos →Skills con GPT-5.6 Sol
GPT-5.6 Sol soporta Skills junto a un conjunto amplio de herramientas de Responses API.
Un stack especialmente completo para agentes
Entre las herramientas soportadas por Sol se encuentran Web Search, File Search, Code Interpreter, Hosted Shell, Apply Patch, Skills, Computer Use, MCP y Tool Search.
Ver GPT-5.6 Sol →Buenas prácticas con Skills OpenAI API
Una Skill puede afectar cómo se comporta un agente, por lo que debe gestionarse como código o configuración de producción.
Mantén las Skills bajo control de versiones.
No incorpores secretos innecesarios en los bundles.
Revisa los archivos antes de publicar una versión.
Prueba versiones nuevas antes de convertirlas en default.
Fija versiones cuando necesites comportamiento reproducible.
Elimina versiones o Skills antiguas solo cuando estés seguro de que ya no se utilizan.
Cuándo conviene utilizar Skills
Skills aporta especialmente valor cuando una capacidad debe reutilizarse varias veces.
Cuando varias tareas comparten el mismo procedimiento.
Cuando necesitas archivos especializados junto a instrucciones.
Cuando quieres mantener versiones de una capacidad.
Cuando múltiples agentes deben utilizar la misma metodología.
Cuando necesitas separar una capacidad del prompt principal.
Cuándo una Skill puede ser innecesaria
No todas las instrucciones necesitan convertirse en un recurso versionado.
Instrucción muy pequeña
Una regla breve que solo se utiliza una vez puede mantenerse directamente en el prompt.
Acción estructurada
Si únicamente necesitas llamar una operación de tu backend, Function Calling puede ser la herramienta adecuada.
Costos de Skills OpenAI API
El costo de un workflow depende principalmente del modelo, herramientas y recursos utilizados durante la ejecución.
Revisa el pricing vigente
La API de Skills y los modelos compatibles pueden evolucionar. Para una aplicación en producción, comprueba siempre la página oficial de precios y las herramientas adicionales utilizadas.
Una Skill puede formar parte de una tarea que también utilice shell, File Search, Web Search, MCP u otras herramientas.
Ver precios OpenAI API →Skills y los límites de OpenAI API
Los modelos que utilizan Skills siguen sujetos a los límites de solicitudes y tokens del proyecto.
Controla el modelo que ejecuta la Skill
Los rate limits dependen del modelo y usage tier. El versionado de Skills no elimina esas restricciones.
Ver límites OpenAI API →Documentación oficial de Skills OpenAI API
Skills dispone actualmente de recursos propios dentro de OpenAI API para creación, versionado y recuperación.
Skills API
Consulta creación de Skills, versiones, bundles, default versions y referencias disponibles.
Consultar documentación oficial →Guías relacionadas con Skills OpenAI API
Continúa explorando herramientas, agentes y Responses API.
FAQ sobre Skills OpenAI API
Respuestas sobre Skills, versiones, bundles, agentes y modelos compatibles.
Skills OpenAI API permite crear y administrar capacidades reutilizables que pueden incluir archivos y disponer de versiones.
Sí. Skills API permite crear, listar, recuperar y eliminar versiones de una Skill.
Sí. La documentación define las nuevas Skill Versions como versiones inmutables.
Es la versión configurada como predeterminada para una Skill.
Es la versión más reciente disponible para una Skill.
Sí. Skills API permite descargar el bundle ZIP de una Skill o de una versión específica.
Sí. Una referencia de Skill puede incluir el skill_id y la versión que debe utilizarse.
Sí. OpenAI publica Skills entre las herramientas compatibles con GPT-5.6 Sol.
Sí. Skills figura actualmente entre las herramientas compatibles con GPT-5.6 Terra y GPT-5.6 Luna.
No. Skills permite empaquetar capacidades reutilizables, mientras Function Calling permite solicitar funciones estructuradas ejecutadas por una aplicación.
Continúa con Structured Outputs en OpenAI API
Ya sabes cómo crear y versionar capacidades reutilizables. El siguiente paso es aprender cómo obtener respuestas que respeten una estructura JSON definida por tu aplicación.
Ver Structured Outputs →