Usar habilidades para acelerar el mantenimiento de OSS

Usamos Codex para cambiar la forma en que mantenemos los repositorios de OpenAI Agents SDK. Las habilidades locales del repositorio, AGENTS.md y GitHub Actions nos permiten convertir tareas recurrentes de ingeniería, como la verificación, la preparación de versiones, las pruebas de integración de ejemplos y la revisión de pull requests, en flujos de trabajo repetibles. Incluso con una configuración bastante sencilla, esto nos ha ayudado a aumentar la productividad del desarrollo en estos repositorios activos. Entre el 1 de diciembre de 2025 y el 28 de febrero de 2026, se fusionaron 457 pull requests en los dos repositorios, frente a 316 en los tres meses anteriores, del 1 de septiembre de 2025 al 30 de noviembre de 2025 (Python: 182 -> 226, TypeScript: 134 -> 231).

Como breve contexto, el SDK está disponible en Python y TypeScript. Proporciona los componentes fundamentales para crear aplicaciones con agentes y también ofrece una forma concisa de crear agentes de voz sobre la Realtime API con múltiples agentes, herramientas y controles con intervención humana. Se usa a gran escala: en períodos recientes de 30 días, según los datos al 6 de marzo de 2026, el paquete de Python registró alrededor de 14,7 millones de descargas en PyPI y el paquete de TypeScript, alrededor de 1,5 millones de descargas en npm.

La configuración es sencilla:

• políticas del repositorio en AGENTS.md
• habilidades locales del repositorio en .agents/skills/
• scripts y referencias opcionales dentro de esas habilidades
• Codex GitHub Action cuando el mismo flujo de trabajo deba ejecutarse en CI

Esta configuración le da a Codex un contexto estable sobre cómo funciona el repositorio, lo que mejora la velocidad y la precisión del trabajo recurrente de ingeniería.

Mantén los flujos de trabajo en el repositorio

En estos repositorios, usamos habilidades para documentar los flujos de trabajo específicos de cada repositorio. Una habilidad es un pequeño paquete de conocimiento operativo: un archivo de manifiesto SKILL.md, más scripts/, references/ y assets/ opcionales. La documentación de personalización de Codex explica por qué esto funciona bien: las habilidades son adecuadas para flujos de trabajo repetibles porque pueden incluir instrucciones más detalladas, scripts y referencias sin sobrecargar el contexto del agente desde el inicio.

Esto coincide con el modelo de presentación progresiva de información que usan las habilidades:

• primero ve metadatos como name y description
• carga SKILL.md solo cuando se selecciona la habilidad
• lee referencias o ejecuta scripts solo cuando es necesario

Ambos repositorios del SDK mantienen estos flujos de trabajo cerca del código:

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

El repositorio de Python es el punto de partida más sencillo:

• code-change-verification ejecuta el conjunto obligatorio de tareas de formato, lint, verificació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 base y detecta documentación faltante, incorrecta o desactualizada.
• examples-auto-run ejecuta ejemplos en modo automático con registros y herramientas auxiliares para volver a ejecutarlos.
• final-release-review compara la etiqueta de la versión anterior con la versión candidata actual y verifica si está lista para publicarse.
• implementation-strategy decide los límites de compatibilidad y el enfoque de implementación antes de realizar cambios en el entorno de ejecución o la API.
• openai-knowledge obtiene la documentación actual de la API y la plataforma de OpenAI mediante el flujo de trabajo oficial de Docs MCP.
• pr-draft-summary prepara una sugerencia de nombre de rama, el título del pull request y un borrador de su descripción al entregar el trabajo.
• test-coverage-improver mide la cobertura, identifica las mayores carencias y propone pruebas de alto impacto.

El repositorio de JavaScript sigue el mismo patrón general y agrega algunas habilidades específicas para su monorepositorio de npm y su proceso de publicación de versiones:

• changeset-validation comprueba que los changesets y los niveles de incremento de versión realmente correspondan al diff del paquete.
• integration-tests publica paquetes en un registro local de Verdaccio y verifica el comportamiento de instalación y ejecución en los entornos de ejecución compatibles.
• pnpm-upgrade actualiza de forma coordinada el conjunto de herramientas de pnpm y las versiones fijadas en CI.

Más que la lista exacta, lo que importa es el patrón. Cada habilidad tiene un contrato acotado, una condición clara de activación y un resultado concreto.

Algunas de las habilidades más útiles no son controles que bloqueen el avance. docs-sync y test-coverage-improver son flujos de trabajo que primero presentan un informe: inspeccionan el diff actual o los artefactos de cobertura, priorizan lo importante y solicitan aprobación antes de hacer modificaciones. En el repositorio de Python, docs-sync también trata los docstrings y los comentarios del código fuente como la fuente de verdad para la documentación de referencia generada, en lugar de modificar manualmente el resultado generado. La habilidad pnpm-upgrade, exclusiva de JavaScript, es otro buen ejemplo de un flujo de mantenimiento acotado: actualiza en conjunto la versión local de pnpm, packageManager y las versiones fijadas en los flujos de trabajo, en lugar de recurrir a una búsqueda y reemplazo generalizados.

Haz obligatorios los flujos de trabajo

Las habilidades resultan más útiles cuando el repositorio exige usarlas en el momento adecuado. Ahí entra AGENTS.md.

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

En la práctica, ambos repositorios usan reglas breves de tipo “si/entonces” para exigir el uso de habilidades. Antes de realizar cambios en el entorno de ejecución o la API, invoca $implementation-strategy para decidir primero los límites de compatibilidad y el enfoque de implementación. Si el cambio afecta el 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 los metadatos de publicación, invoca $changeset-validation. Si el trabajo involucra integraciones con la API o la plataforma de OpenAI, invoca $openai-knowledge. Cuando el trabajo esté terminado y listo para entregar, invoca $pr-draft-summary.

Esa estructura también coincide con las recomendaciones de agents.md: mantener en un solo lugar la descripción general del proyecto, los comandos de compilación y pruebas, el estilo del código, las pautas de pruebas, las consideraciones de seguridad y otras reglas específicas del repositorio. Los repositorios de Agents SDK siguen esa estructura, pero comienzan por las condiciones de activación más importantes para el trabajo diario. Una versión compacta se ve así:

# 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 reales agregan detalles específicos de cada repositorio sobre esa base, como $changeset-validation en el repositorio de JavaScript y pautas más detalladas sobre el entorno de ejecución, la documentación y la publicación de versiones en ambos archivos. Para ver ejemplos completos, consulta AGENTS.md en openai-agents-python y AGENTS.md en openai-agents-js.

AGENTS.md no solo sirve para definir las condiciones de activación de las habilidades. El repositorio de Python también registra allí una regla de compatibilidad de la API pública: conservar el significado posicional de los parámetros de constructores exportados y los campos de dataclasses, agregar los nuevos parámetros y campos opcionales al final cuando sea posible e incluir pruebas de compatibilidad si es inevitable cambiar el orden. Ese es otro buen patrón: mantener las reglas de compatibilidad esenciales para la publicación de versiones en el mismo lugar que las condiciones de activación de las habilidades.

Reglas de verificación

Un ejemplo claro es $code-change-verification.

En ambos repositorios, la regla no es “ejecuta siempre un conjunto extenso de validaciones”. La regla es “ejecútalo cuando cambien el código del entorno de ejecución, las pruebas, los ejemplos o el comportamiento de compilación o pruebas, y no marques el trabajo como terminado hasta que se superen todas las validaciones”.

La parte condicional mantiene ágil el trabajo que solo afecta a la documentación. La parte obligatoria garantiza que los cambios en el código del SDK pasen por los pasos de verificación estándar del repositorio.

Los conjuntos concretos de verificaciones están definidos en las propias habilidades.

En el repositorio de Python, la habilidad exige:

make format
make lint
make typecheck
make tests

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

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

La habilidad define lo que el repositorio considera “verificado”, y AGENTS.md permite exigir que se cumpla esa definición.

Validación de changesets

El repositorio de JavaScript tiene un paso obligatorio adicional para los cambios en paquetes: $changeset-validation, basado en Changesets.

Cuando cambia algo dentro de packages/, o cuando cambia .changeset/, el modelo debe hacer más que ejecutar pruebas. Tiene que crear o actualizar el changeset correspondiente, validar el nivel de incremento de versión y confirmar que el changeset realmente corresponda al diff.

Esta habilidad hace más que comprobar que exista un archivo. Le pide a Codex que evalúe el diff de git y mantiene las reglas de validación en un prompt compartido para que las ejecuciones locales y GitHub Actions usen la misma lógica. También define políticas específicas del repositorio, como las siguientes:

• usa el changeset existente de la rama en lugar de crear otro si ya hay uno
• mantén el resumen en una sola línea con el estilo de Conventional Commit para que también pueda usarse como título del commit
• antes de la versión 1.0, evita los incrementos de versión mayor para el desarrollo habitual de funcionalidades y trata las incorporaciones identificadas explícitamente como exclusivas de la versión preliminar como cambios de parche si no modifican el comportamiento existente
• valida el nivel de incremento de versión requerido frente a los cambios reales del paquete

Esto hace que Codex sea responsable de validar los metadatos de publicación que crea antes de poder afirmar que el trabajo está terminado.

Usa documentación actualizada

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

Esa habilidad es una capa ligera sobre el OpenAI Docs MCP oficial. En lugar 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 la documentación actual de interfaces y funciones como la API Responses, las herramientas, el streaming, Realtime y MCP.

Si el servidor MCP aún no está configurado en el entorno local de Codex, la habilidad remite a quienes mantienen el proyecto al 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 sustancial, ambos repositorios usan $pr-draft-summary.

Esa habilidad se activa solo cuando la tarea ya está terminada o lista para revisión y el cambio afectó código relevante, pruebas, ejemplos, documentación con impacto en el comportamiento o la configuración de compilación o pruebas. Luego recopila automáticamente el nombre de la rama, el estado del árbol de trabajo, los archivos modificados, las estadísticas del diff y los commits recientes, y 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. Un resultado típico se ve así:

# 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 el modelo para validar y resumir su propio trabajo, pedirle que genere el borrador del PR es un último paso natural. Esto mantiene la coherencia de la entrega y reduce la redacción repetitiva cuando el trabajo de programación ya está terminado.

Escribe mejores descripciones

El campo description del frontmatter del archivo SKILL.md de una habilidad forma parte del contrato de enrutamiento.

Esto es estructural, no estilístico. La especificación de Agent Skills establece que name y description son los campos obligatorios del frontmatter de SKILL.md, y su modelo de divulgación progresiva indica que esos campos se cargan al inicio para todas las habilidades. El cuerpo completo de SKILL.md y cualquier contenido de scripts/, references/ o assets/ se cargan después, solo cuando la habilidad se activa.

La documentación de habilidades de Codex y la documentación de personalización describen el mismo comportamiento desde la perspectiva de Codex: Codex comienza con los metadatos de cada habilidad para descubrirla, carga SKILL.md solo cuando la selecciona y lee referencias o ejecuta scripts solo cuando hace falta. El Cookbook de habilidades en la API de OpenAI describe con la misma claridad cómo funciona en la terminal alojada en la nube: OpenAI lee primero name, description y la ruta de cada habilidad, y el modelo usa esa información para decidir cuándo leer el archivo SKILL.md completo. Su sección sobre el frontmatter de SKILL.md lo expresa de forma más directa: name y description son importantes para el descubrimiento y el enrutamiento.

En los repositorios de Agents SDK, esto convierte a description en una de las principales señales de enrutamiento antes de que Codex haya leído el resto de la habilidad.

Este es un ejemplo concreto de code-change-verification.

Demasiado vaga:

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

Mejor (la descripción real):

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 más corta ya le dice a Codex qué hace la habilidad, pero todavía no indica cuándo se aplica, qué tipos de cambios deberían activarla ni si las verificaciones son opcionales. La versión más específica le comunica los tres puntos al modelo.

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

Demasiado vaga:

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

Mejor (la descripción real):

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.

De nuevo, la descripción real funciona como metadatos de enrutamiento. Le indica a Codex que:

• esta habilidad se usa al finalizar la tarea
• se aplica a cambios sustanciales, no a cada turno del chat
• el resultado es un bloque listo para un PR, no solo un resumen en prosa

Una lección práctica de estos repositorios es dedicarle tiempo a description. Si el enrutamiento no parece confiable, corrige los metadatos antes de agregar más código.

Deja las tareas mecánicas en scripts

Después, la siguiente pregunta es qué debe quedar a cargo del modelo y qué conviene trasladar a un script.

Una división confiable es:

• la interpretación, la comparación y la elaboración de informes quedan a cargo del modelo
• el trabajo determinista y repetitivo de shell va en scripts/

Esto coincide con las recomendaciones públicas. La documentación de personalización de Codex describe las habilidades como una forma de darle a Codex instrucciones más completas, scripts y referencias para flujos de trabajo repetibles sin sobrecargar el contexto desde el inicio. Esto encaja con una configuración centrada en el modelo: deja que Codex se encargue de las partes del trabajo que dependen del contexto e incorpora scripts para las partes deterministas solo cuando haga falta. El Cookbook de habilidades en la API de OpenAI también recomienda diseñar los scripts de las habilidades como pequeñas CLI: scripts que se ejecuten desde la línea de comandos, generen una salida determinista en stdout, señalen claramente los fallos con mensajes de uso o error y escriban los resultados en rutas de archivo conocidas cuando sea necesario.

En los repositorios de Agents SDK, intentamos usar el modelo donde su inteligencia resulta realmente útil, por ejemplo:

• leer el código fuente para inferir el comportamiento esperado
• comparar los registros con ese comportamiento esperado
• decidir si el diff de una versión contiene un riesgo real de compatibilidad
• generar una explicación que le permita a un mantenedor tomar medidas

Los scripts se encargan de las tareas mecánicas 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 ejemplos, recopilar registros de cada uno y escribir 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 facilitar la ejecución repetida del mismo flujo de trabajo

Si el modelo tiene que redescubrir la misma secuencia de comandos de shell cada vez, suele ser una señal de que esa secuencia debería convertirse en un script. Si la tarea depende del contexto, de evaluar ventajas y desventajas o de una explicación, esa parte debería quedar a cargo del modelo.

Automatiza las pruebas de integración

Las pruebas de integración automatizadas son una de las áreas donde los flujos de trabajo resultan más útiles en ambos repositorios. Aquí hay dos capas relacionadas: validar automáticamente los ejemplos incluidos en ambos repositorios y, en el de JavaScript, validar por separado que los paquetes publicados sigan funcionando cuando se instalan de la misma manera que lo hacen los usuarios.

Antes de esta configuración, la validación de ejemplos era en parte manual. Podías ejecutar los ejemplos, pero el paso final solía depender de revisar visualmente los registros o inspeccionar el resultado para decidir si parecía correcto. Eso es manejable para un solo ejemplo, pero no escala bien en un repositorio de SDK que sigue creciendo.

La primera capa es examples-auto-run, pero la habilidad llegó después del ejecutor. Para poder automatizar la validación de ejemplos, primero tuvimos que desarrollar en ambos repositorios el soporte necesario para ejecutarlos sin interacción. Eso implicó permitir que los scripts de ejemplo se ejecutaran en modo automático, incluidos los ejemplos que normalmente requieren prompts o aprobaciones.

Ese trabajo de base incluyó:

• responder automáticamente a los prompts interactivos habituales
• aprobar automáticamente las acciones de HITL, MCP, apply_patch y shell cuando el ejecutor las admite
• mantener en una lista de omisión automática los ejemplos que aún no son aptos para automatizarse, como los de tiempo real o de aplicaciones Next.js que requieren una configuración adicional del entorno de ejecución
• escribir registros estructurados para cada ejecución de un ejemplo
• generar archivos para volver a ejecutar los ejemplos fallidos sin tener que ejecutar todo de nuevo

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

Para mejorar la calidad de la validación, el ejecutor se encarga de ejecutar los ejemplos y conservar su stdout y stderr en registros individuales. Luego, la habilidad le indica a Codex que revise esos registros uno por uno y los compare con el código fuente:

• leer el código fuente y los comentarios del ejemplo
• inferir el flujo esperado
• abrir el registro correspondiente
• comparar el comportamiento esperado con la salida real de stdout y stderr
• hacerlo para cada ejemplo que se haya ejecutado correctamente, no solo para una muestra

Esto es más preciso y flexible que intentar expresar la corrección mediante una aserción fija en un script. Un código de salida que indica éxito es útil, pero no basta para los ejemplos que se comunican con API reales, usan herramientas o producen un resultado estructurado. Al registrar primero el resultado real y luego contrastarlo cuidadosamente con el código fuente, podemos validar cada ejemplo según su propósito real.

En el repositorio de JavaScript hay una segunda capa: la habilidad independiente integration-tests. Ese flujo de trabajo va más allá de ejecutar los ejemplos directamente desde el código fuente. Publica los paquetes en un registro local de Verdaccio y prueba su instalación y ejecución en varios entornos, incluidos Node.js, Bun, Deno, Cloudflare Workers y una aplicación React con Vite. Esto detecta otra clase de problemas: no se trata de “¿El ejemplo se ejecuta en el repositorio?”, sino de “¿El paquete sigue comportándose correctamente después de publicarlo, instalarlo e integrarlo en el entorno de ejecución?”.

En conjunto, estos flujos de trabajo muestran por qué conviene combinar habilidades, scripts y el criterio del modelo. Los scripts permiten repetir las ejecuciones, recopilan la evidencia y cubren escenarios de instalación que resulta tedioso verificar a mano. Codex usa esa evidencia para hacer una comparación más cuidadosa que una simple verificación de éxito o fallo programada en un script.

Agrega verificaciones de versiones

La preparación de versiones es otra área donde este patrón resulta útil.

El flujo de revisión de lanzamientos en ambos repositorios comienza por buscar la etiqueta de la versión anterior, compararla con el estado más reciente de main y luego pedirle a Codex que examine el diff en busca de:

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

A partir de esos hallazgos, la habilidad determina, en términos generales, si la versión está lista para lanzarse.

Un ejemplo concreto es openai/openai-agents-python#2480, donde la revisión del lanzamiento da un resultado favorable en general, pero señala que se elimina la compatibilidad con Python 3.9 y que esto requiere actualizar 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 el lanzamiento puede avanzar. La revisión parte de “es seguro lanzar la versión” y solo pasa a bloquear el lanzamiento cuando el diff muestra evidencia concreta de un problema real. Cada decisión de bloqueo debe incluir una lista específica de pasos para desbloquear el lanzamiento. Esto hace que el resultado sea mucho más fácil de usar: un resultado favorable significa que no se encontró en el diff ningún problema que impida el lanzamiento, y un resultado de bloqueo significa que hay un problema real con un siguiente paso claro.

Esto es más útil que un pedido genérico como “por favor, revisa el lanzamiento”. Obliga al modelo a razonar sobre un diff concreto y a explicar el resultado en términos operativos. Si es seguro lanzar la versión, indícalo. Si no lo es, señala la evidencia exacta y las acciones específicas que se necesitan.

Ejecutar flujos de trabajo en CI

Una vez que una habilidad resulta útil en el entorno local, Codex GitHub Action facilita la automatización del mismo flujo de trabajo en CI. Esto funciona mejor cuando el flujo de trabajo local ya es estable, porque el uso manual permite depurar las instrucciones, perfeccionar los scripts y descubrir los casos límite reales.

En los repositorios públicos, el diseño de los disparadores importa tanto como la habilidad. La lista de verificación de seguridad de GitHub Action recomienda limitar quién puede iniciar el flujo de trabajo, dar preferencia a eventos confiables o aprobaciones explícitas, sanear las entradas de los prompts que provengan de Pull requests, commits, issues o comentarios, mantener OPENAI_API_KEY protegida con drop-sudo o un usuario sin privilegios y ejecutar Codex como último paso del job.

Si un flujo de trabajo tiene capacidad de escritura y acepta entradas públicas no confiables, el riesgo suele estar en el diseño de los disparadores, el manejo de las entradas y los privilegios de ejecución con los que opera la habilidad.

Usar Codex en la revisión de PR

Las habilidades son uno de los factores que mejoran la productividad en estos repositorios. La revisión automática de PR de GitHub con Codex es otro.

Desde que se incorporó la revisión automática de PR de GitHub con Codex, Codex ha sido un revisor útil para la mayoría de los cambios de código en estos repositorios. Lo usamos como parte habitual de la revisión, no como una herramienta para casos especiales.

Para errores de programación sencillos, regresiones y pruebas faltantes, confiar en Codex como vía de revisión obligatoria ya es suficientemente seguro en la práctica. Aplica de forma consistente los mismos criterios para comprobar una y otra vez que el código sea correcto, y ha eliminado un importante cuello de botella para las correcciones pequeñas y las mejoras rutinarias.

La revisión por pares sigue siendo importante, pero para otro tipo de cambios.

La revisión humana sigue siendo esencial cuando la pregunta principal no es “¿este código es correcto?”, sino “¿cuál de las opciones válidas debemos elegir y cómo debemos lanzarla?”. Esto incluye:

• cambios de API o arquitectura para los que existen varios diseños razonables y los responsables del mantenimiento deben elegir uno explícitamente
• cambios de comportamiento que afectan las expectativas sobre el producto, los compromisos de compatibilidad con versiones anteriores o la política de despliegue
• decisiones sobre nombres, migraciones y comunicación de lanzamientos en las que lo difícil es elegir lo que resulte más claro para los usuarios y colaboradores
• cambios que requieren acuerdos entre los responsables del mantenimiento o los equipos, como definir el alcance del trabajo, ordenar su ejecución o decidir qué lanzar ahora y qué dejar para después

Codex puede seguir aportando de manera útil en todos esos casos, pero sigue siendo valioso contar con una persona que tome las decisiones y discutirlas directamente.

AGENTS.md también puede dejar establecida esa división: el repositorio puede indicarle a Codex qué aspectos son importantes al revisar si el código es correcto, y Codex puede aplicar esas pautas de manera consistente.

Esto también ha contribuido de forma significativa al rendimiento. El trabajo repetitivo de revisión y validación ya no tiene que esperar a que los revisores dispongan de tiempo para cada cambio de bajo riesgo, mientras que los responsables del mantenimiento pueden concentrarse en las revisiones que requieren más contexto y en las que su criterio tiene mayor peso. Ese cambio nos ha ayudado a resolver errores pendientes y a completar pequeñas mejoras de funcionalidades mucho más rápido.

Reflexiones finales

En los repositorios de OpenAI Agents SDK, las habilidades funcionan mejor cuando forman parte de la configuración habitual de trabajo del repositorio.

AGENTS.md le indica a Codex qué flujos de trabajo son obligatorios. description le indica cuándo recurrir a esos flujos. scripts/ se encarga de las partes deterministas. El modelo se encarga de las partes que dependen del contexto. Y una vez que un flujo de trabajo es sólido en el entorno local, Codex GitHub Action puede llevar ese mismo proceso a CI.

Esto ha hecho que el trabajo cotidiano de ingeniería en estos repositorios sea más explícito y confiable. También ha facilitado lanzar pequeñas mejoras con mayor rapidez, porque la verificación, la revisión de lanzamientos y la entrega de PR para revisión ahora siguen el mismo proceso repetible.

Recursos

• OpenAI Agents SDK para Python
• OpenAI Agents SDK para JS
• Habilidades en Codex
• Instrucciones personalizadas con AGENTS.md
• Codex GitHub Action
• Usar Codex en GitHub
• Habilidades en el Cookbook de la API de OpenAI
• Especificación de Agent Skills
• Habilidades en la API de OpenAI: prácticas operativas recomendadas