Scope summary:
– N files changed (+X/-Y); key areas touched: …
:
– Risk: 🔴/🟡/🟢
– Evidence:
– Action:
Unblock checklist (if blocked):
– [ ] …
Exemplo real do repositório Python da OpenAI (PR #2480):
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`.
Script auxiliar: .agents/skills/final-release-review/scripts/get-prev-tag.sh
#!/usr/bin/env bash
# Get the most recent semver tag before the current HEAD
git tag --sort=-v:refname | grep -E '^v?[0-9]+\.[0-9]+\.[0-9]+' | head -1
9. Skill 5: Estratégia de implementação
Antes de editar código de runtime ou API, o Codex deve decidir a fronteira de compatibilidade e a abordagem de implementação.
---
name: implementation-strategy
description: Decide the compatibility boundary and implementation approach before editing runtime or API changes. Use before modifying public APIs, constructors, or behavior.
---
# Implementation Strategy
## Trigger
- Before editing runtime code or public API
- Before changing constructor signatures or dataclass fields
- Before modifying behavior that users depend on
## Process
1. Identify the scope of the change:
- What public APIs are affected?
- What internal code paths are touched?
- What tests and examples will need updating?
2. Determine compatibility boundary:
- Can the change be purely additive?
- If breaking: is there a deprecation path?
- Are there positional parameter constraints?
3. Propose the implementation approach:
- Order of changes (internal first, then public)
- Migration strategy for existing users
- Test plan
4. Get confirmation before proceeding
## Compatibility rules
- Preserve positional meaning of exported constructor parameters and dataclass fields
- Append new optional ones at the end when possible
- Add compatibility tests if reordering is unavoidable
## Output format
Implementation Strategy
Scope
- Affected APIs: …
- Affected internals: …
- Tests to update: …
Compatibility
- Breaking change? yes/no
- Deprecation path: …
- Positional impact: …
Approach
- …
- …
Test plan
10. Skill 6: Validação de changesets (monorepo JS)
Esta skill é especÃfica para monorepos JavaScript que usam Changesets. Ela valida que os changesets e bump levels correspondem ao diff real dos pacotes.
---
name: changeset-validation
description: Validate that changesets and bump levels match the actual package diff. Create or update changesets when packages/ or .changeset/ changes. Enforce Conventional Commit summaries and bump-level policy.
---
# Changeset Validation
## Trigger
- Any change under `packages/`
- Any change in `.changeset/`
## Process
1. Check if a branch changeset already exists
2. If yes: update it instead of creating a new one
3. If no: create one
4. Write the changeset summary in Conventional Commit style (one line)
5. Determine the required bump level from the actual package diff
6. Validate the bump level against repo policy
## Repo-specific policy
- Keep the summary to one line in Conventional Commit style (doubles as commit title)
- Before 1.0: avoid major bumps for normal feature work
- Preview-only additions labeled explicitly: treat as patch if they don't change existing behavior
- Validate the required bump level against actual package changes
## Bump level rules
| Change type | Bump |
|------------|------|
| Bug fix | patch |
| New feature (backward compatible) | minor |
| Breaking change | major |
| Preview-only addition | patch |
| Docs only | no bump needed |
## Output format
Changeset Validation
Changeset:
- Summary:
feat: add streaming support to agent runner
- Bump: minor
- Packages affected: @openai/agents-core
Validation
- ✅ Bump level matches diff
- ✅ Summary follows Conventional Commit
- ✅ No duplicate changesets
11. Skill 7: Resumo de PR
Esta skill é acionada ao final de trabalho substantivo. Ela coleta automaticamente nome do branch, status da árvore de trabalho, arquivos alterados, diff stats e commits recentes, e produz um bloco pronto para PR.
---
name: pr-draft-summary
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.
---
# PR Draft Summary
## Trigger
- Substantive work is finished or ready for review
- Change touched: runtime code, tests, examples, docs with behavior impact, or build/test config
- NOT for: trivial typo fixes, formatting-only changes, single-line comment updates
## Process
1. Collect context automatically:
```bash
git rev-parse --abbrev-ref HEAD # branch name
git status --short # working tree status
git diff --stat origin/main...HEAD # changed files + stats
git log origin/main..HEAD --oneline # recent commits
```
2. Analyze the collected context
3. Produce the PR draft block
## Output format (rigid)
Pull Request Draft
Branch name suggestion
git checkout -b /
Title
:
Description
<2-4 paragraphs describing the change, rationale, and impact>
Exemplo real de saÃda do pr-draft-summary:
# 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.
12. Skill 8: Busca de documentação atualizada da API
Esta skill é um wrapper fino sobre o OpenAI Docs MCP oficial. Em vez de deixar o modelo responder de memória, ela instrui o Codex a buscar a documentação atualizada.
---
name: openai-knowledge
description: Pull current OpenAI API and platform documentation through the official Docs MCP. Use for any work touching OpenAI API, Responses API, tools, streaming, Realtime, or MCP integrations.
---
# OpenAI Knowledge
## Trigger
- Work touches OpenAI API or platform integrations
- Implementing or modifying API calls
- Working with Responses API, tools, streaming, Realtime, or MCP
## Process
1. Use the OpenAI Developer Documentation MCP server to look up current docs
2. Search for the relevant API surface
3. Verify parameter names, types, and behavior against current docs
4. Do NOT rely on model memory for API details
## MCP Server Setup
If the MCP server is not configured in your local Codex environment:
1. Follow the Docs MCP quickstart
2. Use the official MCP server endpoint
3. Configure in your Codex settings
## Covered surfaces
- Responses API
- Tools and function calling
- Streaming
- Realtime API
- MCP integrations
- All platform-level features
13. Skill 9: Melhoria de cobertura de testes
Esta skill é report-first: roda cobertura, encontra os maiores gaps e propõe testes de alto impacto. Não edita nada sem aprovação.
---
name: test-coverage-improver
description: Run coverage, find the biggest gaps, and propose high-impact tests. Report-first workflow: inspect coverage artifacts, prioritize what matters, and ask for approval before writing tests.
---
# Test Coverage Improver
## Trigger
- After adding new features
- Before release
- When asked to improve test coverage
## Process
1. Run coverage:
- Python: `pytest --cov=src --cov-report=term-missing`
- TypeScript: `pnpm test --coverage`
2. Parse coverage report
3. Identify the biggest gaps by:
- Lines uncovered (absolute count)
- Critical paths with no coverage
- Public API methods with 0% coverage
4. Prioritize: focus on high-impact, low-effort tests first
5. Present findings as a proposal
6. Ask for approval before writing tests
## Output format
Coverage Gap Report
Overall: XX% (was YY%)
Top gaps by impact
| File |
Uncovered lines |
Risk |
Proposed test |
| src/core.py |
45 |
🔴 High |
Test error path in process() |
| src/utils.py |
32 |
🟡 Medium |
Test edge cases in parse() |
Proposed new tests (N)
test_process_error_handling — covers 15 lines, catches silent failurestest_parse_edge_cases — covers 12 lines, validates empty/null inputs- …
Approval needed
Reply with which tests to implement, or “all” to proceed with all.
14. Skill 10: Atualização coordenada de toolchain (pnpm)
Skill especÃfica para monorepos JavaScript: atualiza a versão do pnpm, o campo packageManager e os pins de workflow juntos, de forma coordenada.
---
name: pnpm-upgrade
description: Update the pnpm toolchain, packageManager field, and CI workflow pins in a coordinated way. Avoid broad search-and-replace.
---
# pnpm Upgrade
## Trigger
- New pnpm version available
- CI workflow needs toolchain update
## Process
1. Check current pnpm version: `pnpm --version`
2. Check latest available: `npm view pnpm version`
3. Update in coordinated order:
a. Update local pnpm: `pnpm self-update` or `npm i -g pnpm@latest`
b. Update `packageManager` field in `package.json`:
```json
"packageManager": "pnpm@X.Y.Z"
```
c. Update CI workflow pins (`.github/workflows/*.yml`):
Find and update any `pnpm/action-setup` version pins
d. Update any other toolchain references
4. Run `pnpm i` to refresh lockfile with new version
5. Verify: `pnpm --version`
## Important
- Update ALL references together — never leave one behind
- Do NOT use broad search-and-replace — update each reference explicitly
- Verify the lockfile is compatible after the upgrade
## Output
pnpm Upgrade: X.Y.Z → A.B.C
Updated
- ✅ Local pnpm: A.B.C
- ✅ package.json:
"packageManager": "pnpm@A.B.C"
- ✅ CI workflow: pnpm/action-setup@vN
- ✅ Lockfile regenerated
Verification
pnpm --version → A.B.Cpnpm i → clean
15. Escrevendo descrições que funcionam como roteamento
O campo description no frontmatter do SKILL.md não é estilÃstico — é estrutural. O modelo de progressive disclosure do Codex carrega name e description de todas as skills na inicialização. O corpo completo do SKILL.md só é carregado quando a skill é ativada.
Isso faz da description um dos principais sinais de roteamento antes mesmo de o Codex ler o resto da skill.
Exemplo ruim vs. bom para code-change-verification
⌠Vago (ruim):
description: Run the mandatory verification stack in the OpenAI Agents JS monorepo.
Diz o que a skill faz, mas não diz quando aplicá-la, que tipos de mudanças devem acioná-la, nem se as verificações são opcionais.
✅ EspecÃfico (bom — a descrição real usada pela OpenAI):
description: Run the mandatory verification stack when changes affect runtime code, tests, or build/test behavior in the OpenAI Agents JS monorepo.
Exemplo ruim vs. bom para pr-draft-summary
⌠Vago:
description: Create a PR title and draft description for a pull request.
✅ EspecÃfico:
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.
A descrição boa funciona como metadado de roteamento. Ela diz ao Codex:
- Esta é uma skill de fim de tarefa
- É para mudanças substantivas, não para todo turno de chat
- A saÃda é um bloco pronto para PR, não apenas um resumo em prosa
âš ï¸ Lição prática da OpenAI: Se o roteamento das skills parecer não confiável, corrija os metadados antes de adicionar mais código. Gaste tempo na description.
16. Separando o que vai no modelo e o que vai nos scripts
Uma divisão confiável entre modelo e scripts:
| Fica com o modelo (Codex) |
Vai para scripts/ |
| Ler código fonte para inferir comportamento |
Rodar comandos de verificação em ordem fixa |
| Comparar logs com comportamento esperado |
Iniciar exemplos, coletar logs, gerar rerun |
| Decidir se um diff de release tem risco real |
Buscar tag da release anterior |
| Produzir explicações acionáveis |
Expor comandos helper (start, stop, status, logs) |
| Interpretação, comparação, report |
Trabalho de shell determinÃstico e repetitivo |
Regra prática: Se o modelo precisa redescobrir a mesma receita de shell toda vez, essa receita deveria ser um script. Se a tarefa depende de contexto, tradeoffs ou explicação, essa parte deve ficar com o modelo.
Exemplo de script helper para examples-auto-run
#!/usr/bin/env bash
# .agents/skills/examples-auto-run/scripts/run-examples.sh
# Usage: ./run-examples.sh [--retry-failed]
set -euo pipefail
MAIN_LOG="/tmp/examples-main.log"
LOGS_DIR="/tmp/example-logs"
RERUN_FILE="/tmp/examples-rerun.txt"
mkdir -p "$LOGS_DIR"
echo "🃠Running examples in auto mode..."
if [ "${1:-}" = "--retry-failed" ] && [ -f "$RERUN_FILE" ]; then
echo "📋 Retrying failed examples from $RERUN_FILE"
# Run only the failed examples
while IFS= read -r example; do
echo " ↳ $example"
done < "$RERUN_FILE"
else
# Full run
uv run examples/run_examples.py \
--auto-mode \
--write-rerun \
--main-log "$MAIN_LOG" \
--logs-dir "$LOGS_DIR"
fi
echo "📊 Main log: $MAIN_LOG"
echo "📠Per-example logs: $LOGS_DIR/"
echo "🔄 Rerun file: $RERUN_FILE"
17. Automatizando testes de integração
A OpenAI implementou testes de integração em duas camadas:
Camada 1: Validação de exemplos no repositório (examples-auto-run)
Antes dessa automação, validar exemplos era parcialmente manual — você rodava os exemplos mas a última milha dependia de inspeção visual. Isso não escala.
Para automatizar, primeiro foi necessário construir o suporte para execução não-interativa de exemplos:
- Auto-resposta para prompts interativos comuns
- Auto-aprovação de ações HITL, MCP,
apply_patch e shell
- Lista de skip para exemplos não adequados para automação (realtime, apps Next.js)
- Logs estruturados por exemplo
- Arquivos de rerun para reexecutar apenas falhas
Comando para Python:
uv run examples/run_examples.py --auto-mode --write-rerun \
--main-log /tmp/examples-main.log \
--logs-dir /tmp/example-logs/
Comando para TypeScript:
pnpm examples:start-all
O runner executa os exemplos e preserva stdout/stderr. O Codex então interpreta os logs:
- Lê o código fonte e comentários do exemplo
- Infere o fluxo pretendido
- Abre o log correspondente
- Compara comportamento esperado com stdout/stderr real
- Faz isso para todos os exemplos bem-sucedidos, não apenas uma amostra
Camada 2: Testes de integração pós-publicação (integration-tests, apenas JS)
Este workflow publica os pacotes em um registry Verdaccio local e testa instalação e execução em múltiplos ambientes:
- Node.js
- Bun
- Deno
- Cloudflare Workers
- Vite React app
Isso pega uma classe diferente de problemas: não “o exemplo roda no repositório?” mas “o pacote se comporta corretamente depois de publicado, instalado e integrado em runtime?”.
18. Adicionando verificações de release
O workflow de revisão de release em ambos os repositórios:
- Encontra a tag da release anterior
- Faz diff contra a
main atual
- Pede ao Codex para inspecionar o diff buscando:
РProblemas de compatibilidade retroativa em APIs p̼blicas
РRegress̵es, incluindo mudan̤as sutis de comportamento
РNotas de migra̤̣o ou release notes faltantes
- Emite um veredito de release readiness
Regra de decisão do gate: Começa de “seguro para publicar” e só muda para bloqueado quando o diff mostra evidência concreta de um problema real. Todo bloqueio deve vir com um checklist de desbloqueio especÃfico.
19. Rodando workflows no CI com GitHub Actions
Quando uma skill funciona bem localmente, o Codex GitHub Action facilita automatizar o mesmo workflow no CI.
Arquivo: .github/workflows/codex-ci.yml
name: Codex CI
on:
pull_request:
types: [opened, synchronize, reopened]
issue_comment:
types: [created]
jobs:
codex:
# Security: only run on trusted events or with explicit approval
if: |
github.event_name == 'pull_request' ||
(github.event_name == 'issue_comment' &&
github.event.comment.body == '/codex verify')
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- uses: actions/checkout@v4
- name: Setup environment
run: |
# Install your project dependencies here
# Example for Python:
pip install -e ".[dev]"
# Example for TypeScript:
# corepack enable
# pnpm i
- name: Run Codex
uses: openai/codex-action@v1
with:
openai_api_key: ${{ secrets.OPENAI_API_KEY }}
prompt: |
Run $code-change-verification on the changes in this PR.
Report the results as a PR comment.
Checklist de segurança para GitHub Actions público
A documentação oficial de segurança do Codex GitHub Action recomenda:
- ✅ Limitar quem pode iniciar o workflow
- ✅ Preferir eventos confiáveis ou aprovação explÃcita
- ✅ Sanitizar inputs de prompt vindos de PRs, commits, issues ou comentários
- ✅ Manter
OPENAI_API_KEY protegida com drop-sudo ou usuário não privilegiado
- ✅ Rodar o Codex como último passo do job
âš ï¸ Se um workflow tem capacidade de escrita e recebe input público não confiável, o risco está no design do trigger, no handling de input e nos privilégios de runtime em torno da skill — não na skill em si.
20. Codex na revisão de PRs
Desde que o Codex GitHub PR auto review foi disponibilizado, o Codex se tornou um revisor útil na maioria das mudanças de código nos repositórios da OpenAI.
O que o Codex faz bem (review automatizado)
- Bugs de programação simples
- Regressões
- Testes faltantes
- Padrões de correção repetitivos
Para esses casos, depender do Codex como caminho de revisão obrigatório já é seguro na prática.
O que ainda precisa de revisão humana
- Mudanças de API ou arquitetura com múltiplos designs razoáveis
- Mudanças de comportamento que afetam expectativas de produto ou promessas de compatibilidade
- Decisões de nomenclatura, migração e comunicação de release
- Mudanças que exigem alinhamento entre maintainers ou times
O AGENTS.md pode codificar essa divisão: o repositório diz ao Codex o que conta como importante para revisão de corretude, e o Codex aplica essa orientação de forma consistente.
21. Checklist final e próximos passos
✅ Checklist de implementação
- [ ] Criar
AGENTS.md na raiz com regras obrigatórias de skills
- [ ] Criar diretório
.agents/skills/
- [ ] Implementar
code-change-verification (formatação + lint + typecheck + testes)
- [ ] Implementar
implementation-strategy (antes de editar APIs públicas)
- [ ] Implementar
pr-draft-summary (handoff de PR padronizado)
- [ ] Implementar
docs-sync (auditoria de documentação)
- [ ] Implementar
examples-auto-run (execução automática de exemplos com logs)
- [ ] Implementar
final-release-review (revisão de release com diff)
- [ ] Implementar
test-coverage-improver (gaps de cobertura)
- [ ] (Monorepo JS) Implementar
changeset-validation
- [ ] (Monorepo JS) Implementar
pnpm-upgrade
- [ ] Revisar descrições de skills — são especÃficas o suficiente para roteamento?
- [ ] Extrair trabalho de shell determinÃstico para
scripts/
- [ ] Configurar Codex GitHub Action para CI
- [ ] Revisar checklist de segurança do GitHub Action
- [ ] Ativar Codex PR auto review
📊 Métricas para acompanhar
Depois de implementar as skills, monitore:
- Número de PRs mergeados por mês (antes/depois)
- Tempo médio de revisão (tempo até o primeiro review)
- Taxa de reprovação no CI (verificações que pegam problemas antes do merge)
- Cobertura de testes (tendência ao longo do tempo)
- Frequência de releases (ciclos mais curtos?)
🔗 Recursos oficiais
Resumo
O padrão que a OpenAI estabeleceu nos repositórios do Agents SDK é reproduzÃvel por qualquer projeto open source:
AGENTS.md diz ao Codex quais workflows são obrigatóriosdescription nas skills diz quando rotear para cada workflowscripts/ cuida das partes determinÃsticas- O modelo cuida das partes contextuais
- Codex GitHub Action leva o mesmo processo para o CI
O resultado: trabalho de engenharia do dia a dia mais explÃcito, mais confiável e com 44% mais PRs mergeados. Comece com code-change-verification e pr-draft-summary — são as skills de maior retorno imediato — e vá expandindo conforme sua confiança no sistema cresce.
