Cómo usar las habilidades de OpenAI de forma segura

Un flujo de trabajo reutilizable para agentes puede comenzar como un prompt, pero el trabajo repetido pronto revela los límites de copiar instrucciones entre conversaciones. Se omiten pasos importantes, los formatos de salida se desvían y el razonamiento que sustenta un proceso se vuelve difícil de revisar. Una habilidad de OpenAI resuelve ese problema al colocar las instrucciones operativas y los materiales de apoyo en una carpeta estructurada que puede someterse a control de versiones e inspección.

Esa comodidad no debe confundirse con un límite de seguridad. Una habilidad puede influir en las herramientas que selecciona un agente, los archivos que lee, los scripts que ejecuta y los servicios externos con los que contacta. Por tanto, una adopción segura exige dos tipos de revisión: evaluar el flujo como conocimiento legible y evaluar sus posibles acciones como una entrada de la cadena de suministro de software.

Esta guía explica el formato, su lugar dentro de los plugins de OpenAI, los límites reales de la portabilidad y un proceso práctico para decidir si una habilidad pertenece a la experimentación personal o a un entorno de producción aprobado.

Comprenda la unidad que está instalando

La especificación abierta de Habilidades de Agentes define una habilidad como un directorio centrado en un archivo SKILL.md. Ese archivo utiliza metadatos YAML para campos como el nombre y la descripción de la habilidad, seguidos de instrucciones en Markdown. Los directorios opcionales pueden contener scripts, referencias, recursos, plantillas, esquemas u otros elementos necesarios para el flujo de trabajo.

Esta estructura es deliberadamente modesta. El nombre y la descripción ayudan a un agente compatible a descubrir cuándo puede resultar pertinente la habilidad. Las instrucciones completas pueden cargarse cuando se activa el flujo, mientras que los recursos de apoyo más extensos permanecen disponibles hasta que se necesiten. Esta carga progresiva permite mantener accesibles muchos procedimientos especializados sin insertar cada instrucción en todas las conversaciones.

Por tanto, una habilidad es más que un prompt guardado. Puede definir entradas, pasos ordenados, pruebas obligatorias, restricciones de salida, condiciones de fallo y comprobaciones de aceptación. Una habilidad de revisión podría exigir la detección del framework, la ejecución de pruebas, comprobaciones de seguridad y un informe fijo. Una habilidad de publicación podría exigir metadatos completos, fuentes verificadas, procedencia de imágenes y validación antes de publicar.

El formato también separa la capacidad general del modelo del procedimiento local. Los expertos en la materia pueden expresar su criterio mediante instrucciones legibles, mientras que los ingenieros pueden añadir scripts deterministas allí donde importe el comportamiento exacto. Ambas partes pueden revisarse en el control de versiones. La guía de la OpenAI Academy sobre habilidades presenta esta reutilización como una forma de dejar de explicar desde cero el mismo proceso recurrente.

Trate los metadatos de descubrimiento como enrutamiento ejecutable

La descripción de SKILL.md no es un texto decorativo. A menudo ayuda al agente a decidir si la habilidad coincide con la tarea actual. Una descripción demasiado amplia puede dirigir trabajos no relacionados hacia el flujo; una que sea vaga puede impedir la activación cuando se necesita la habilidad. Cualquiera de los dos fallos puede cambiar el comportamiento del agente antes de que una persona vea las instrucciones detalladas.

Revise el nombre y la descripción con tanto cuidado como los pasos. Deben indicar qué hace la habilidad, las situaciones que la activan y las exclusiones relevantes. Si un flujo edita hojas de cálculo pero no debe controlar una sesión activa de Excel, ese límite debe figurar en el lenguaje de descubrimiento. Si solo puede publicar contenido después de una aprobación explícita, esa condición debe ser inequívoca.

Después, examine la jerarquía de instrucciones. Una habilidad no obtiene autoridad simplemente porque se active. La intención del usuario, las políticas de la plataforma, las restricciones del entorno aislado, las reglas del proyecto y los requisitos de aprobación siguen siendo aplicables. Las instrucciones que ordenen al agente ignorar esos controles son una razón para rechazar el paquete, no un atajo para eludirlos.

Separe una habilidad de su contenedor de plugin

El catálogo de habilidades original de OpenAI está obsoleto y dirige a los desarrolladores hacia los ejemplos y las guías actuales de plugins. Se trata de un cambio de distribución, no de una prueba de que el formato subyacente de las habilidades haya desaparecido. La unidad de instrucciones principal puede seguir siendo una carpeta con SKILL.md, mientras que el producto instalable pasa a ser un plugin.

Según la guía de empaquetado de plugins de OpenAI, un plugin debe tener en su raíz un manifiesto obligatorio .codex-plugin/plugin.json. El paquete puede incluir habilidades junto con definiciones de servidores MCP, aplicaciones, comandos, ganchos, metadatos de agentes y recursos. Un plugin compuesto solo por una habilidad sigue siendo posible cuando bastan las instrucciones y los recursos incluidos.

La distinción resulta útil al definir el alcance. Una habilidad describe un procedimiento repetible. Un plugin puede proporcionar la capacidad más amplia necesaria para distribuir y operar ese procedimiento, incluidas herramientas externas, requisitos de autenticación, elementos de interfaz y metadatos del paquete. El plugin es el límite de instalación; la habilidad continúa siendo un componente en su interior.

Para las nuevas distribuciones centradas en OpenAI, siga la ruta actual de los plugins en lugar de crear un proceso de instalación alrededor del catálogo obsoleto. Siempre que resulte práctico, conserve el propio flujo en una habilidad compatible con estándares. Así se mantienen las instrucciones duraderas separadas de la integración específica del entorno y se facilitan las revisiones o migraciones posteriores.

Sea preciso sobre la portabilidad

El Markdown sencillo, un esquema obligatorio pequeño y las carpetas opcionales de recursos facilitan el traslado de habilidades entre agentes compatibles. La especificación proporciona una estructura común y los archivos legibles funcionan bien con las prácticas conocidas de control de versiones y revisión de código. Esa es una portabilidad significativa en la capa de instrucciones.

No garantiza que la misma carpeta se comporte de forma idéntica en todas partes. Los entornos pueden interpretar de modo diferente los metadatos opcionales. Los nombres de herramientas, sistemas operativos, dependencias, rutas del sistema de archivos, conectores, límites de contexto y procesos de aprobación pueden variar. Un flujo que invoque un comando local no funcionará automáticamente en un entorno limitado al navegador. Un flujo que necesite datos privados fallará sin un conector disponible y una autorización adecuada.

Evalúe la portabilidad por capas:

1. Procedimiento principal: ¿Puede otro entorno compatible comprender los objetivos, la secuencia, las entradas y el contrato de salida?
2. Recursos incluidos: ¿Las referencias a archivos son relativas, están documentadas y se encuentran disponibles con la habilidad?
3. Supuestos de ejecución: ¿Los comandos, paquetes, requisitos del sistema operativo y mensajes de error son explícitos?
4. Acciones conectadas: ¿Qué herramientas, métodos de autenticación e interfaces son específicos de un entorno o plugin?
5. Resultados de comportamiento: ¿El flujo se activa y completa tareas representativas de forma coherente en cada entorno previsto?

Un buen diseño mantiene el procedimiento duradero en la habilidad y coloca en el paquete circundante los conectores específicos del producto, los metadatos de interfaz, los permisos y el comportamiento de instalación. Esto no vuelve portátiles todas las acciones, pero evita que los detalles accesorios de integración oculten el conocimiento reutilizable.

Revise los permisos por sus consecuencias, no por el tipo de archivo

El Markdown legible es más fácil de inspeccionar que un binario opaco, pero las instrucciones aún pueden provocar un uso de herramientas con consecuencias. La pregunta pertinente no es simplemente si el paquete contiene código. Pregunte qué puede persuadir u ordenar al agente que haga.

Asigne cada capacidad solicitada a un paso concreto. El acceso de lectura a archivos puede ser necesario para analizar documentos, pero el acceso amplio de escritura no. El acceso a la red puede estar justificado para un flujo de investigación, mientras que el acceso a credenciales o servicios no relacionados no lo está. Una herramienta capaz de enviar mensajes, publicar contenido, cambiar sistemas de producción o eliminar datos merece un límite explícito de confirmación.

Los scripts necesitan una inspección directa. Compruebe todos los archivos ejecutables y de apoyo, no solo SKILL.md. Identifique comandos, dependencias, variables de entorno, destinos de red, rutas de archivos y cualquier operación que cambie el estado externo. Prefiera el menor conjunto de permisos que permita completar la tarea prevista y pruebe con datos desechables o en un entorno aislado antes de permitir el acceso a sistemas valiosos.

Examine también las entradas indirectas. Las referencias, las páginas obtenidas y los datos conectados pueden contener sus propias instrucciones. Un flujo seguro debe tratar esos materiales como contenido que se analiza, no como una autoridad de mayor prioridad. Las instrucciones del paquete deben indicar por dónde entra el contenido no fiable y cómo debe manejarlo el agente.

Gestione las habilidades como dependencias de la cadena de suministro

La popularidad de un repositorio público no demuestra una revisión de seguridad, fiabilidad en producción ni una adopción satisfactoria. Una habilidad maliciosa o comprometida puede intentar obtener secretos, alterar archivos, contactar con un servicio inesperado o ampliar su alcance mediante scripts y referencias. Un flujo benigno puede volverse arriesgado después de una actualización o quedar obsoleto cuando cambia una API, una interfaz de producto o una norma de cumplimiento.

Registre la procedencia antes de la instalación: editor, repositorio, revisión o versión exacta, licencia, fecha de revisión y archivos aprobados. Fije la revisión examinada cuando el método de instalación lo permita. No acepte una actualización solo porque sea más reciente; inspeccione las diferencias, vuelva a ejecutar los casos de evaluación y reevalúe cualquier cambio en los permisos.

Las señales del ciclo de vida también importan. El antiguo repositorio de habilidades de OpenAI sigue accesible aunque su aviso indique que está obsoleto. Los resultados de búsqueda y los enlaces guardados pueden sobrevivir a la ruta de instalación preferida. Compruebe el aviso del repositorio y la documentación actual en lugar de suponer que un paquete accesible todavía recibe mantenimiento. Defina cómo desactivará, sustituirá o revertirá una habilidad el equipo si su fuente se ve comprometida o cambia su comportamiento.

Para el uso organizativo, la responsabilidad debe ser explícita. Alguien debe hacerse cargo de las actualizaciones, la compatibilidad, los casos de prueba y la retirada. Almacene el paquete aprobado en una ubicación controlada, conserve un registro de auditoría y separe los experimentos del conjunto que los agentes pueden activar en el trabajo de producción.

Realice una evaluación por etapas antes de aprobar

Un directorio válido solo demuestra que los archivos están organizados correctamente. No demuestra que la activación sea fiable, las instrucciones sean seguras ni los resultados útiles. Utilice una evaluación por etapas con tareas representativas y condiciones claras de aprobación.

1. Establezca el propósito y los límites

Anote la tarea recurrente, los usuarios previstos, las entradas aceptadas, las salidas esperadas y las acciones que deben permanecer fuera del alcance. Decida si bastan mejores instrucciones o si el flujo necesita realmente un plugin con herramientas y servicios conectados. Empiece con la capacidad mínima que resuelva el problema.

2. Audite todos los componentes del paquete

Lea el manifiesto, SKILL.md, los scripts, las referencias, los recursos y la configuración. Verifique que los enlaces y las dependencias coincidan con el propósito declarado. Busque accesos a secretos, comandos destructivos, llamadas de red inesperadas, rutas locales absolutas, descargas ocultas e instrucciones que eludan la aprobación o las políticas.

3. Elabore un mapa explícito de permisos

Enumere cada herramienta y fuente de datos, la operación que permite, si el acceso es de solo lectura o permite modificaciones y cuándo se requiere confirmación humana. Elimine las capacidades que no correspondan a ningún paso del flujo. Utilice credenciales limitadas y recursos aislados durante la evaluación.

4. Pruebe el enrutamiento y el comportamiento normal

Cree tareas representativas que deberían activar la habilidad y tareas cercanas que no deberían hacerlo. Compruebe si la descripción dirige el trabajo correctamente. En los casos positivos, verifique los pasos obligatorios, las pruebas, el formato de salida y las comprobaciones de aceptación en lugar de juzgar solo si la respuesta final parece plausible.

5. Pruebe el comportamiento ante fallos y negativas

Pruebe entradas ausentes, herramientas no disponibles, archivos no válidos, instrucciones contradictorias y solicitudes fuera del alcance. La habilidad debe detenerse con claridad, conservar los datos y solicitar la decisión necesaria en lugar de improvisar autoridad. Confirme que el contenido no fiable no pueda redefinir silenciosamente el flujo.

6. Pruebe la portabilidad allí donde se afirme

Ejecute los mismos casos en todos los entornos previstos. Registre qué partes de las instrucciones principales se transfieren y qué integraciones requieren adaptación. No califique un plugin completo como portátil cuando solo su habilidad interna sea compatible con estándares.

7. Apruebe una revisión y supervise los cambios

Fije la versión evaluada, registre los resultados y las limitaciones conocidas, nombre a un responsable y establezca un intervalo de revisión. Vuelva a evaluar después de cambios en instrucciones, scripts, permisos, dependencias, herramientas o comportamiento del entorno. Mantenga una vía de reversión y un proceso claro de retirada.

Use la capa de confianza más pequeña

Las habilidades son valiosas porque hacen visible, reutilizable y revisable el conocimiento operativo recurrente. Los plugins añaden una capa práctica de distribución cuando el flujo necesita metadatos de instalación, herramientas, autenticación, interfaces o controles organizativos. Ninguna capa es segura de forma predeterminada y ninguna elimina la necesidad de permisos impuestos por el entorno.

El enfoque duradero consiste en mantener legible el procedimiento principal, aislar las integraciones específicas de productos, conceder solo el acceso que requiere cada paso y probar el comportamiento en lugar de limitarse a la sintaxis. Cuando la procedencia, los permisos, los casos de evaluación, la responsabilidad y la reversión se documentan juntos, una habilidad se convierte en un flujo gobernado en vez de un paquete de instrucciones sin examinar.