🌐 Subagentes no Codex e outros ambientes

Pense numa tomada elétrica. O aparelho é o mesmo; muda o adaptador conforme o país. O princípio (110/220 V, um plugue) não muda — muda o encaixe. Subagente é igual: o princípio — "delega para um contexto isolado, recebe um resumo" — é universal. O que muda de ambiente para ambiente é o encaixe: onde o arquivo mora, como se chama o frontmatter, os nomes das ferramentas. A meta deste módulo é escrever um único .md e plugá-lo em dois runtimes.

↑ Uma fonte .md; cada runtime aplica seu adaptador. A ideia é a mesma — o encaixe muda.

Tudo que você aprendeu até aqui — maestro que delega, janela própria, relatório limpo — descreve um padrão, não um produto. O padrão é: "tarefa grande vira um subprocesso com contexto próprio; só a conclusão volta". Qualquer ferramenta de agente sério precisa de algo assim, porque o problema (contexto que enche, trabalho que se repete) é universal. Por isso o conceito viaja.

O Codex CLI (o agente de terminal da OpenAI) tem as mesmas peças, só com vocabulário diferente. Onde o Claude Code fala "subagente" e "skill", o Codex fala em prompts e agentes markdown que você guarda numa pasta e invoca. O esqueleto bate: um arquivo de instruções + um gatilho + um conjunto de ferramentas permitidas.

Em vez de manter duas cópias (uma pro Claude, uma pro Codex) que divergem com o tempo, você escreve uma fonte só e "emite" a versão de cada runtime a partir dela. Essa é a ideia de um polyskill: um .md portável é o molde, e cada ambiente é um build daquele molde. Uma verdade, vários destinos — o oposto de copiar-e-colar.

As ferramentas têm nomes diferentes, mas as capacidades são as mesmas: ler arquivo, buscar em texto, listar caminhos, editar, rodar shell. Em vez de citar o nome exato da ferramenta no corpo do seu .md, descreva a capacidade ("leia os arquivos", "busque por padrão") — assim o mesmo texto funciona nos dois, porque cada runtime resolve qual ferramenta concreta usar.

Antes de portar, fixe a fronteira. O princípio — delegar para contexto isolado, um papel por agente, devolver resumo — atravessa qualquer ambiente intacto. O que muda é a casca: nomes de campo, pasta, sintaxe de invocação, ferramentas disponíveis. Saber o que fica firme evita reescrever o que já estava certo.

Portar é um procedimento de três tempos: extrair o miolo, trocar a casca, testar a paridade. Mas portabilidade tem teto: nem tudo cruza o limite. Coisas muito coladas a um runtime — uma MCP exclusiva, um nome de tool específico, um modelo só de um provedor — não viajam e viram uma nota de adaptação.

Aqui está um doc-summarizer.md escrito para ser portável: o frontmatter é a casca do Claude Code, e o corpo é o miolo agnóstico de ferramenta. Logo depois, a nota de adaptação mostra o que trocar para rodar o mesmo arquivo no Codex CLI.

--- # CASCA (Claude Code) — troca por runtime
name: doc-summarizer
description: Lê documentos longos e devolve um resumo
  curto com os pontos-chave. Use para condensar
  arquivos grandes sem encher o contexto.
tools: Read, Grep, Glob   # só leitura
model: haiku             # barato p/ escanear
---

# MIOLO (portável) — NÃO cita ferramenta por nome
You are a precise document summarizer.

When invoked:
1. Read the target documents and grasp the intent.
2. Search for the key claims, numbers and decisions.
3. Write a summary: 5 bullets, then the source paths.

Output: only the summary. Do not paste raw
content. Do not modify any file.

Três prompts para portar e cross-rodar. O padrão é sempre o mesmo: peça para preservar o miolo, adaptar a casca, e deixar uma nota onde a portabilidade acaba.

Pegue este subagente do Claude Code e adapte para o
Codex CLI. Mantenha o corpo (papel/passos/saída) intacto,
troque só a casca: pasta, frontmatter e invocação. No fim,
liste uma "nota de adaptação" com o que não é portável.

Reescreva esta skill como fonte portável: remova nomes
de ferramenta específicos do corpo e descreva a capacidade
("leia", "busque"). Depois emita dois builds — um para
Claude Code, um para Codex — a partir da mesma fonte.

Liste as ferramentas que este .md usa no Claude Code
(Read, Grep, Glob, Bash…) e me dê o equivalente de shell
para o Codex. Aponte quais não têm equivalente direto e
precisam virar nota de adaptação.

É assim que um build cross-runtime aparece no terminal: você roda o emissor uma vez sobre a fonte portável, e ele gera os arquivos de cada ambiente — adaptando a casca, mantendo o miolo. Repare nos dois destinos saindo do mesmo SKILL.md.

↑ Recriação ilustrativa do terminal (não é screenshot real). Uma fonte entra; dois builds saem com o mesmo miolo e cascas diferentes.