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

1. ...
2. ...

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

Proposed new tests (N)

1. test_process_error_handling — covers 15 lines, catches silent failures
2. test_parse_edge_cases — covers 12 lines, validates empty/null inputs
3. ...

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 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.C
• pnpm 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:

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:

1. Lê o código fonte e comentários do exemplo
2. Infere o fluxo pretendido
3. Abre o log correspondente
4. Compara comportamento esperado com stdout/stderr real
5. 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:

1. Encontra a tag da release anterior
2. Faz diff contra a main atual
3. 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
4. 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

• OpenAI Agents SDK para Python
• OpenAI Agents SDK para JavaScript
• Skills no Codex (documentação)
• Custom instructions com AGENTS.md
• Codex GitHub Action
• Skills na API da OpenAI (cookbook)
• Especificação Agent Skills
• Skills na API da OpenAI: melhores práticas operacionais
• Codex for OSS

Resumo

O padrão que a OpenAI estabeleceu nos repositórios do Agents SDK é reproduzível por qualquer projeto open source:

1. AGENTS.md diz ao Codex quais workflows são obrigatórios
2. description nas skills diz quando rotear para cada workflow
3. scripts/ cuida das partes determinísticas
4. O modelo cuida das partes contextuais
5. 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.