Cómo usar habilidades para agilizar el mantenimiento de proyectos de código abierto

Usamos Codex para cambiar la forma en que mantenemos los repositorios del OpenAI Agents SDK. Las habilidades que guardamos en cada repositorio, AGENTS.md y GitHub Actions nos permiten convertir tareas recurrentes de ingeniería en flujos de trabajo que podemos repetir. Entre esas tareas están la verificación, la preparación de versiones, las pruebas de integración de los ejemplos y la revisión de PR. Incluso con una configuración bastante sencilla, hemos mejorado el rendimiento del equipo de desarrollo en estos repositorios tan activos. Entre el 1 de diciembre de 2025 y el 28 de febrero de 2026, se fusionaron 457 Pull requests entre los dos repositorios, frente a 316 en los tres meses anteriores, del 1 de septiembre al 30 de noviembre de 2025 (Python pasó de 182 a 226 y TypeScript, de 134 a 231).

El SDK está disponible en Python y TypeScript. Proporciona los componentes esenciales para crear aplicaciones con agentes. También permite crear agentes de voz con poco código sobre la Realtime API, con varios agentes, herramientas y controles que permiten la intervención humana. El SDK se usa a gran escala. Según los datos disponibles al 6 de marzo de 2026 para períodos recientes de 30 días, el paquete de Python tuvo alrededor de 14,7 millones de descargas en PyPI y el de TypeScript, alrededor de 1,5 millones en npm.

La configuración es sencilla:

• las reglas del repositorio se guardan en AGENTS.md
• las habilidades propias del repositorio se guardan en .agents/skills/
• cada habilidad puede incluir scripts y referencias
• usamos GitHub Action de Codex cuando el mismo flujo de trabajo debe ejecutarse en integración continua (CI)

Esta configuración le da a Codex un contexto estable sobre el funcionamiento del repositorio, lo que le permite realizar las tareas recurrentes de ingeniería con mayor rapidez y precisión.

Guarda los flujos de trabajo en el repositorio

En estos repositorios usamos habilidades para documentar los flujos de trabajo propios de cada uno. Una habilidad reúne en un pequeño paquete lo que hay que saber para realizar una tarea. Incluye un archivo de manifiesto SKILL.md y, opcionalmente, scripts/, references/ y assets/. La documentación sobre la personalización de Codex explica por qué funciona este enfoque. Las habilidades se adaptan bien a los flujos de trabajo repetibles porque pueden incluir instrucciones más detalladas, scripts y referencias sin sobrecargar el contexto inicial del agente.

Así funciona el modelo de carga progresiva de las habilidades:

• el agente ve primero metadatos como name y description
• carga SKILL.md solo cuando selecciona la habilidad
• lee las referencias o ejecuta los scripts solo cuando los necesita

Ambos repositorios del SDK guardan estos flujos de trabajo junto al código:

• .agents/skills en openai-agents-python
• .agents/skills en openai-agents-js

El repositorio de Python sirve como punto de partida por su sencillez:

• code-change-verification ejecuta los pasos obligatorios de formato, lint, comprobación de tipos y pruebas cuando cambia el código o el comportamiento de la compilación.
• docs-sync contrasta la documentación con el código para detectar información faltante, incorrecta o desactualizada.
• examples-auto-run ejecuta los ejemplos en modo automático, registra los resultados y ofrece herramientas para volver a ejecutarlos.
• final-release-review compara la etiqueta de la versión anterior con la versión candidata actual y comprueba si está lista para publicarse.
• implementation-strategy determina qué compatibilidad se debe preservar y cómo implementar los cambios antes de modificar el código de ejecución o la API.
• openai-knowledge consulta la documentación vigente de la API y la plataforma de OpenAI mediante el flujo de trabajo oficial de Docs MCP.
• pr-draft-summary sugiere un nombre para la rama y prepara el título del PR y un borrador de su descripción cuando llega el momento de entregar el trabajo.
• test-coverage-improver mide la cobertura, identifica las áreas menos cubiertas y propone las pruebas que tendrían mayor impacto.

El repositorio de JavaScript sigue el mismo esquema y añade algunas habilidades específicas para su monorepositorio de npm y su proceso de publicación:

• changeset-validation comprueba que los changesets y el tipo de incremento de versión correspondan a los cambios reales del paquete.
• integration-tests publica los paquetes en un registro local de Verdaccio y comprueba que se instalen y ejecuten correctamente en los entornos de ejecución compatibles.
• pnpm-upgrade actualiza de forma coordinada las herramientas de pnpm y las versiones fijadas en CI.

Más que la lista exacta de habilidades, importa lo que tienen en común. Cada una tiene una función bien delimitada, una condición de activación clara y un resultado concreto.

Algunas de las habilidades más útiles no bloquean el avance del trabajo. docs-sync y test-coverage-improver primero presentan un informe. Inspeccionan el diff actual o los archivos de cobertura, ordenan los hallazgos por importancia y solicitan aprobación antes de hacer cambios. En el repositorio de Python, docs-sync también toma las docstrings y los comentarios del código fuente como referencia para la documentación que se genera automáticamente. Así se evita corregir a mano los archivos generados. La habilidad pnpm-upgrade, exclusiva de JavaScript, es otro buen ejemplo de un flujo de mantenimiento bien delimitado. Actualiza en conjunto la versión local de pnpm, packageManager y las versiones fijadas en los flujos de trabajo sin recurrir a una búsqueda y reemplazo generalizados.

Define cuándo son obligatorios los flujos de trabajo

Las habilidades resultan más útiles cuando el repositorio exige su uso en el momento adecuado. Para eso sirve AGENTS.md.

La guía de AGENTS.md explica que estos archivos contienen instrucciones del repositorio que acompañan al código y se aplican antes de que el agente empiece a trabajar. También recomienda que sean breves. En los repositorios del Agents SDK, reservamos ese espacio para las reglas que Codex debe seguir siempre y colocamos las más importantes al principio.

En la práctica, ambos repositorios usan reglas condicionales breves para indicar cuándo es obligatorio usar cada habilidad. Antes de modificar el código de ejecución o la API, invoca $implementation-strategy para decidir qué compatibilidad debes preservar y cómo implementar el cambio. Si el cambio afecta al código del SDK, las pruebas, los ejemplos o el comportamiento de la compilación, invoca $code-change-verification. Si un cambio en un paquete de JavaScript afecta a los metadatos de la versión, invoca $changeset-validation. Si el trabajo afecta a integraciones con la API o la plataforma de OpenAI, invoca $openai-knowledge. Cuando termines el trabajo y esté listo para entregarse, invoca $pr-draft-summary.

Esta estructura también sigue las recomendaciones de agents.md. Reúne en un solo lugar la descripción general del proyecto, los comandos de compilación y pruebas, el estilo del código, las pautas para las pruebas, las consideraciones de seguridad y otras reglas propias del repositorio. Los repositorios del Agents SDK siguen ese esquema, pero empiezan por las condiciones de activación más importantes para el trabajo diario. Así se ve una versión abreviada:

# AGENTS.md

## Project overview

- Core SDK code lives under `src/agents/` or `packages/*/src/`.
- Tests live under `tests/` or `packages/*/test/`.
- Sample apps and integration surfaces live under `examples/`.

## Mandatory skill usage

- Use `$implementation-strategy` before editing runtime or API changes that may affect compatibility boundaries.
- Run `$code-change-verification` when runtime code, tests, examples, or build/test behavior changes.
- Use `$openai-knowledge` for OpenAI API or platform work.
- Use `$pr-draft-summary` when substantial code work is ready for review.

## Build and test commands

- Python: `make format`, `make lint`, `make typecheck`, `make tests`
- TypeScript: `pnpm i`, `pnpm build`, `pnpm -r build-check`, `pnpm lint`, `pnpm test`

## Compatibility rules

- Preserve positional compatibility for public constructors and dataclass fields.

Los archivos que usamos amplían esa base con detalles propios de cada repositorio, como $changeset-validation en el de JavaScript. Ambos archivos también incluyen pautas más detalladas sobre el comportamiento en tiempo de ejecución, la documentación y la publicación de versiones. Para ver los ejemplos completos, consulta AGENTS.md en openai-agents-python y AGENTS.md en openai-agents-js.

AGENTS.md sirve para más que indicar cuándo se activa cada habilidad. El repositorio de Python también documenta allí una regla de compatibilidad de la API pública. Hay que conservar el significado que tienen, por su posición, los parámetros de los constructores exportados y los campos de las dataclasses, agregar los nuevos parámetros o campos opcionales al final cuando sea posible y añadir pruebas de compatibilidad si es inevitable cambiar el orden. Es otra práctica que puedes adoptar. Guarda las reglas de compatibilidad esenciales para publicar una versión junto a las condiciones que activan las habilidades.

Reglas de verificación

Un ejemplo claro es $code-change-verification.

En ninguno de los dos repositorios la regla es “ejecuta siempre una larga serie de validaciones”. La regla es “ejecútalas cuando cambien el código de ejecución, las pruebas, los ejemplos o el comportamiento de la compilación o de las pruebas, y da el trabajo por terminado solo cuando se superen todas”.

La condición evita comprobaciones innecesarias cuando solo cambia la documentación. La obligatoriedad garantiza que los cambios en el código del SDK pasen por las verificaciones habituales del repositorio.

Las propias habilidades especifican qué verificaciones hay que ejecutar.

En el repositorio de Python, la habilidad exige estos comandos:

make format
make lint
make typecheck
make tests

En el repositorio de JavaScript, la habilidad exige este orden exacto:

pnpm i
pnpm build
pnpm -r build-check
pnpm -r -F "@openai/*" dist:check
pnpm lint
pnpm test

La habilidad define qué significa “verificado” en el repositorio y AGENTS.md establece cuándo es obligatorio cumplir esa definición.

Validación de changesets

El repositorio de JavaScript tiene un paso obligatorio adicional para los cambios en paquetes. La habilidad $changeset-validation se basa en Changesets.

Cuando cambia algo en packages/ o en .changeset/, el modelo debe hacer algo más que ejecutar las pruebas. Tiene que crear o actualizar el changeset correspondiente, validar el tipo de incremento de versión y confirmar que el changeset refleje los cambios del diff.

La habilidad hace más que comprobar que existe un archivo. Le pide a Codex que evalúe el diff de Git y guarda las reglas de validación en un prompt compartido para que las ejecuciones locales y GitHub Actions usen la misma lógica. También incorpora reglas propias del repositorio, como las siguientes:

• reutiliza el changeset de la rama si ya existe, en lugar de crear otro
• escribe el resumen en una sola línea con el estilo de Conventional Commit para que también sirva como título del commit
• antes de la versión 1.0, evita incrementar la versión mayor al desarrollar funcionalidades habituales y trata como cambios de parche las adiciones marcadas expresamente como exclusivas de la versión preliminar si no alteran el comportamiento existente
• comprueba que el tipo de incremento de versión requerido corresponda a los cambios reales del paquete

Así, antes de dar el trabajo por terminado, Codex debe validar los metadatos de la versión que acaba de crear.

Usa la documentación vigente

Ambos repositorios también exigen usar $openai-knowledge cuando el trabajo afecta a integraciones con la API o la plataforma de OpenAI.

La habilidad ofrece acceso al MCP oficial de documentación de OpenAI con una capa mínima de instrucciones. En vez de dejar que el modelo responda de memoria, le indica a Codex que use el servidor MCP de documentación para desarrolladores de OpenAI para consultar información vigente sobre la API de Responses, las herramientas, el streaming, Realtime y MCP, entre otros temas.

Si el servidor MCP aún no está configurado en el entorno local de Codex, la habilidad dirige a quienes mantienen el repositorio a la guía de inicio rápido de Docs MCP y al punto de acceso oficial del servidor MCP.

Prepara el PR para su entrega

Al terminar un trabajo de cierta envergadura, ambos repositorios usan $pr-draft-summary.

La habilidad solo se activa cuando la tarea está prácticamente terminada o lista para revisión y se hicieron cambios relevantes en el código, las pruebas, los ejemplos, la documentación que afecta al comportamiento o la configuración de compilación o pruebas. Entonces recopila automáticamente el nombre de la rama, el estado del árbol de trabajo, la lista de archivos modificados, las estadísticas del diff y los commits recientes. Con esa información genera:

• una sugerencia de nombre para la rama
• un título para el PR
• un borrador de la descripción del PR

El formato de salida es rígido a propósito. Este es un resultado típico:

# Pull Request Draft

## Branch name suggestion

git checkout -b fix/tracing-lazy-init-fork-safety

## Title

fix: #2489 lazily initialize tracing globals to avoid import-time fork hazards

## Description

This pull request fixes import-time tracing side effects that could break fork-based process models by moving tracing bootstrap to lazy, first-use initialization.

It updates tracing setup so initialization happens once on first access while preserving the existing public tracing APIs.

It also adds regression tests for import-time behavior, one-time bootstrap, and custom provider handling.

This pull request resolves #2489.

Una vez que confías en que el modelo puede validar y resumir su propio trabajo, pedirle que prepare el borrador del PR es un último paso natural. Así, las entregas siguen un formato uniforme y se reduce la redacción repetitiva una vez terminado el trabajo de programación.

Escribe descripciones más precisas

El campo description de los metadatos iniciales de SKILL.md forma parte de las reglas que determinan cómo se selecciona una habilidad.

Es una cuestión de estructura. La especificación de Agent Skills establece que name y description son campos obligatorios de los metadatos iniciales de SKILL.md. Según su modelo de carga progresiva, al inicio se cargan esos campos para todas las habilidades. El contenido completo de SKILL.md y los recursos de scripts/, references/ o assets/ solo se cargan más adelante, cuando se activa la habilidad.

La documentación sobre las habilidades de Codex y la documentación sobre personalización describen el mismo comportamiento desde la perspectiva de Codex. Primero, Codex usa los metadatos para identificar las habilidades disponibles. Solo carga SKILL.md cuando selecciona la habilidad y solo lee referencias o ejecuta scripts cuando los necesita. La guía práctica sobre habilidades en la API de OpenAI es igual de explícita sobre lo que ocurre en la terminal alojada en la nube. OpenAI lee primero los campos name y description y la ruta de cada habilidad. El modelo usa esa información para decidir cuándo leer SKILL.md completo. La sección sobre los metadatos iniciales de SKILL.md lo expresa de forma más directa. Los campos name y description son importantes para identificar y seleccionar las habilidades.

Por eso, en los repositorios del Agents SDK, description es uno de los principales criterios que usa Codex para elegir una habilidad antes de leer el resto de su contenido.

Veamos un ejemplo de code-change-verification.

Una descripción demasiado vaga:

description: Run the mandatory verification stack in the OpenAI Agents JS monorepo.

Una descripción más precisa (la que usamos):

description: Run the mandatory verification stack when changes affect runtime code, tests, or build/test behavior in the OpenAI Agents JS monorepo.

La versión breve ya le dice a Codex qué hace la habilidad, pero no indica cuándo corresponde usarla, qué tipos de cambios deben activarla ni si es opcional ejecutar las comprobaciones en esos casos. La versión más específica le aclara los tres puntos al modelo.

El mismo patrón aparece en pr-draft-summary.

Una descripción demasiado vaga:

description: Create a PR title and draft description for a pull request.

Una descripción más precisa (la que usamos):

description: Create a PR title and draft description after substantive code changes are finished. Trigger when wrapping up a moderate-or-larger change (runtime code, tests, build config, docs with behavior impact) and you need the PR-ready summary block with change summary plus PR draft text.

También en este caso, la descripción que usamos contiene metadatos para seleccionar la habilidad. Le indica a Codex lo siguiente:

• la habilidad se usa al final de la tarea
• se aplica a cambios de cierta envergadura, no a cada turno del chat
• el resultado debe ser un bloque listo para usar en el PR y debe incluir más que un resumen en prosa

Una lección práctica de estos repositorios es que vale la pena dedicarle tiempo a description. Si Codex no selecciona las habilidades de forma confiable, corrige los metadatos antes de agregar más código.

Delega los pasos mecánicos a los scripts

Luego hay que decidir qué tareas conviene dejarle al modelo y cuáles conviene trasladar a un script.

Esta división nos ha dado resultados confiables:

• el modelo se encarga de interpretar, comparar y elaborar informes
• las tareas deterministas y repetitivas del shell se guardan en scripts/

La documentación pública recomienda lo mismo. La documentación sobre la personalización de Codex presenta las habilidades como una forma de proporcionar a Codex instrucciones más detalladas, scripts y referencias para flujos de trabajo repetibles sin sobrecargar su contexto inicial. Esto encaja con un enfoque centrado en el modelo. Deja que Codex se encargue de las tareas que dependen del contexto y recurre a los scripts para los pasos deterministas solo cuando haga falta. La guía práctica sobre habilidades en la API de OpenAI también recomienda diseñar los scripts de las habilidades como pequeñas CLI. Deben poder ejecutarse desde la línea de comandos, producir una salida estándar determinista, mostrar instrucciones de uso o mensajes de error claros cuando fallen y, si es necesario, escribir los resultados en rutas de archivo conocidas.

En los repositorios del Agents SDK procuramos usar el modelo donde su capacidad de razonamiento aporta valor, por ejemplo, para:

• leer el código fuente y deducir el comportamiento previsto
• comparar los registros con ese comportamiento
• decidir si el diff de una versión supone un riesgo real para la compatibilidad
• redactar una explicación que permita a quien mantiene el repositorio decidir qué hacer

Los scripts se encargan de los pasos mecánicos que acompañan ese trabajo, por ejemplo:

• ejecutar los comandos de verificación obligatorios del repositorio en un orden fijo
• iniciar la ejecución de los ejemplos, recopilar los registros de cada uno y generar archivos para volver a ejecutar los que fallen
• obtener la etiqueta de la versión anterior antes de revisar si la nueva versión está lista para publicarse
• ofrecer comandos auxiliares como start, stop, status, logs, tail, collect y rerun para que sea fácil repetir el mismo flujo de trabajo

Si el modelo tiene que volver a deducir la misma secuencia de comandos de shell cada vez, por lo general conviene guardarla en un script. Si la tarea depende del contexto, requiere sopesar alternativas o necesita una explicación, esa parte debe quedar a cargo del modelo.

Automatiza las pruebas de integración

Las pruebas de integración automatizadas son uno de los flujos de trabajo más útiles en ambos repositorios. Hay dos niveles de validación relacionados. En ambos repositorios validamos automáticamente los ejemplos que incluyen. En el de JavaScript también comprobamos por separado que los paquetes publicados sigan funcionando cuando se instalan como lo harían los usuarios.

Antes de adoptar esta configuración, validábamos los ejemplos en parte de forma manual. Podías ejecutarlos, pero a menudo el último paso consistía en revisar los registros a simple vista o inspeccionar la salida para decidir si parecía correcta. Eso es manejable para un solo ejemplo, pero resulta difícil de sostener a medida que crece el repositorio de un SDK.

El primer nivel es examples-auto-run, aunque creamos la habilidad después de la herramienta que ejecuta los ejemplos. Para automatizar la validación, primero tuvimos que habilitar la ejecución no interactiva en ambos repositorios. Esto implicó permitir que los scripts de ejemplo se ejecutaran en modo automático, incluso los que normalmente solicitan respuestas o aprobaciones.

Ese trabajo inicial incluyó:

• responder automáticamente a las solicitudes interactivas habituales
• aprobar automáticamente las acciones de HITL, MCP, apply_patch y shell cuando la herramienta de ejecución lo permita
• mantener una lista de ejemplos que se omiten automáticamente porque todavía no se prestan a la automatización, como los ejemplos en tiempo real o los de aplicaciones Next.js que requieren configuración adicional del entorno de ejecución
• escribir registros estructurados para cada ejecución de un ejemplo
• generar archivos que permitan volver a ejecutar los ejemplos que fallen sin tener que repetirlos todos

Con esa base, organizamos el flujo de trabajo como una habilidad para que fuera reutilizable y fácil de invocar. En el repositorio de Python, examples-auto-run ejecuta uv run examples/run_examples.py --auto-mode --write-rerun --main-log ... --logs-dir .... En el de JavaScript, la habilidad realiza las comprobaciones de compilación y luego ejecuta pnpm examples:start-all en modo automático, con registros individuales y la posibilidad de volver a ejecutar cada ejemplo.

Para mejorar la calidad de la validación, la herramienta ejecuta los ejemplos y conserva sus salidas stdout y stderr en registros individuales. Luego, la habilidad le indica a Codex que revise los registros uno por uno y los contraste con el código fuente:

• lee el código fuente del ejemplo y sus comentarios
• deduce la secuencia de pasos prevista
• abre el registro correspondiente
• compara el comportamiento previsto con lo que realmente aparece en stdout y stderr
• repite el proceso con cada ejemplo que se haya ejecutado correctamente, sin limitarte a una muestra

Este método es más preciso y flexible que intentar definir el comportamiento correcto con una aserción fija en un script. Un código de salida que indica éxito es útil, pero no basta para los ejemplos que interactúan con API reales, usan herramientas o generan resultados estructurados. Al registrar primero la salida real y contrastarla cuidadosamente con el código fuente, podemos validar cada ejemplo según lo que se propuso demostrar.

El repositorio de JavaScript tiene un segundo nivel de validación, a cargo de la habilidad independiente integration-tests. Este flujo va más allá de ejecutar los ejemplos desde el código fuente en el propio repositorio. Publica los paquetes en un registro local de Verdaccio y prueba su instalación y ejecución en varios entornos, entre ellos Node.js, Bun, Deno, Cloudflare Workers y una aplicación React con Vite. Esto permite detectar otro tipo de problemas. Además de preguntar “¿se ejecuta el ejemplo en el repositorio?”, podemos preguntar “¿sigue funcionando correctamente el paquete después de publicarlo, instalarlo e integrarlo en el entorno de ejecución?”.

En conjunto, estos flujos de trabajo muestran por qué resulta útil combinar habilidades, scripts y el criterio del modelo. Los scripts permiten repetir las ejecuciones, registran la evidencia y cubren procedimientos de instalación que sería tedioso comprobar a mano. Con esa evidencia, Codex puede hacer una comparación más minuciosa que un script que solo indica si la comprobación pasó o falló.

Agrega comprobaciones antes de publicar una versión

La preparación de versiones es otro ámbito en el que resulta útil este enfoque.

En ambos repositorios, el flujo de revisión de una versión empieza por buscar la etiqueta de la versión anterior y compararla con la última revisión de main. Luego le pide a Codex que inspeccione el diff en busca de:

• problemas de compatibilidad con versiones anteriores en las API públicas y en el comportamiento del SDK que perciben los usuarios
• regresiones, incluidos cambios menores en el comportamiento esperado
• notas de migración o actualizaciones de las notas de la versión que falten para cambios que las requieran

A partir de los hallazgos, la habilidad determina si, en conjunto, la versión está lista para publicarse.

Un ejemplo concreto es openai/openai-agents-python#2480. La revisión da luz verde a la publicación, pero señala que se deja de admitir Python 3.9 y que hay que reflejarlo en las notas de la versión:

Release readiness review (excerpt)

Release call:
🟢 GREEN LIGHT TO SHIP. Minor-version bump includes expected breaking change
(Python 3.9 drop) with no concrete regressions found.

Scope summary:

- 38 files changed (+1450/-789); key areas touched: `src/agents/tool.py`,
  `src/agents/extensions/`, `src/agents/realtime/`, `tests/`,
  `pyproject.toml`, `uv.lock`.

Python 3.9 support removed

- Risk: 🟡 MODERATE. Users pinned to Python 3.9 will be unable to install the
  0.9.0 release.
- Evidence: `pyproject.toml` now sets `requires-python = ">=3.10"` and drops
  the Python 3.9 classifier; CI skip logic for 3.9 was removed.
- Action: Ensure release notes clearly call out the Python 3.9 drop and that
  packaging metadata remains `>=3.10`.

La habilidad también define cómo se decide si la publicación puede seguir adelante. La revisión parte de que “es seguro publicar” y solo bloquea la publicación cuando el diff aporta evidencia concreta de un problema real. Cada decisión de bloqueo debe incluir una lista de pasos específicos para resolverlo. Así es mucho más fácil actuar según el resultado. La luz verde indica que en el diff no se encontró ningún problema que impida la publicación. Un bloqueo indica que existe un problema real y especifica el siguiente paso.

Esto es más útil que una petición genérica como “revisa la versión”. Obliga al modelo a razonar sobre un diff concreto y a explicar qué implica el resultado para la publicación. Si es seguro publicar la versión, dilo. Si no lo es, señala la evidencia exacta y las medidas concretas que hacen falta.

Ejecuta flujos de trabajo en CI

Cuando una habilidad ya resulta útil en el entorno local, GitHub Action de Codex facilita la automatización del mismo flujo de trabajo en CI. Funciona mejor cuando el flujo local ya es estable, porque es al ejecutarlo manualmente cuando puedes depurar las instrucciones, perfeccionar los scripts y descubrir los casos límite que ocurren en la práctica.

En los repositorios públicos, la forma de activar el flujo de trabajo importa tanto como la habilidad. La lista de comprobación de seguridad de GitHub Action recomienda limitar quién puede iniciar el flujo, dar preferencia a eventos de confianza o aprobaciones explícitas, sanear los datos de Pull requests, commits, incidencias o comentarios que se incorporan al prompt, proteger OPENAI_API_KEY con drop-sudo o con un usuario sin privilegios y ejecutar Codex como último paso del trabajo de CI.

Si un flujo de trabajo tiene permisos de escritura y recibe datos públicos que no son de confianza, el riesgo suele estar en cómo se activa, cómo procesa los datos y qué privilegios tiene el entorno donde se ejecuta la habilidad.

Usa Codex para revisar PR

Las habilidades explican parte de la mejora en productividad de estos repositorios. Otra parte se debe a la revisión automática de PR con Codex en GitHub.

Desde que se habilitó la revisión automática de PR en GitHub, Codex ha sido útil para revisar la mayoría de los cambios de código en estos repositorios. Lo usamos como parte habitual de la revisión, sin reservarlo para casos especiales.

Para errores de programación sencillos, regresiones y pruebas faltantes, en la práctica ya podemos confiar en Codex para realizar la revisión obligatoria. Aplica de manera uniforme los mismos criterios para comprobar que el código sea correcto. Así hemos eliminado una de las principales demoras en las correcciones pequeñas y las mejoras de rutina.

La revisión entre pares sigue siendo importante para otro tipo de cambios.

La revisión humana sigue siendo esencial cuando la pregunta principal deja de ser “¿es correcto este código?” y pasa a ser “¿cuál de estas opciones válidas conviene elegir y cómo deberíamos publicarla?”. Esto incluye:

• cambios en la API o la arquitectura para los que hay varios diseños razonables y quienes mantienen el repositorio deben elegir uno explícitamente
• cambios de comportamiento que afectan a lo que los usuarios esperan del producto, a los compromisos de compatibilidad con versiones anteriores o a las políticas de despliegue
• decisiones sobre nombres, migraciones y comunicación de versiones en las que lo difícil es elegir lo que resultará más claro para usuarios y colaboradores
• cambios que requieren acuerdos entre responsables del mantenimiento o entre equipos, por ejemplo, para definir el alcance del trabajo, ordenar las tareas o decidir qué publicar ahora y qué dejar para después

Codex puede hacer aportes útiles en todos esos casos, aunque sigue siendo valioso discutir las opciones directamente y dejar la decisión en manos de una persona.

AGENTS.md también puede recoger esa división de responsabilidades. El repositorio puede indicarle a Codex qué aspectos son importantes al revisar si el código es correcto, y Codex puede aplicar esos criterios de manera uniforme.

Este cambio también ha contribuido de forma importante al rendimiento del equipo. Las tareas repetitivas de revisión y validación ya no tienen que esperar a que alguien encuentre tiempo para revisar cada cambio de bajo riesgo. Quienes mantienen el repositorio pueden concentrarse en las revisiones que requieren más contexto y donde más cuenta su criterio. Esto nos ha permitido resolver errores pendientes e incorporar pequeñas mejoras de funcionalidad mucho más rápido.

Reflexiones finales

En los repositorios del OpenAI Agents SDK, las habilidades funcionan mejor cuando forman parte de la manera habitual de trabajar.

AGENTS.md le indica a Codex qué flujos de trabajo son obligatorios. El campo description le indica cuándo elegirlos. Los scripts de scripts/ se encargan de los pasos deterministas y el modelo, de los que dependen del contexto. Cuando un flujo de trabajo ya funciona bien en el entorno local, GitHub Action de Codex permite ejecutar el mismo proceso en CI.

Así, las tareas diarias de ingeniería en estos repositorios están mejor definidas y se realizan de manera más confiable. También nos resulta más fácil publicar pequeñas mejoras con rapidez, porque la verificación, la revisión de versiones y la entrega de PR ahora siguen un proceso que podemos repetir.

Recursos

• OpenAI Agents SDK para Python
• OpenAI Agents SDK para JS
• Habilidades en Codex
• Instrucciones personalizadas con AGENTS.md
• GitHub Action de Codex
• Usa Codex en GitHub
• Guía práctica sobre habilidades en la API de OpenAI
• Especificación de Agent Skills
• Buenas prácticas para usar habilidades en la API de OpenAI