🟣 Anatomia do Codex

Arquivo markdown na raiz do projeto que o Codex injeta no system prompt no início da sessão. Função idêntica ao CLAUDE.md — só o nome muda.

Quem migra de Claude Code copia o CLAUDE.md e renomeia. Funciona em 90% dos casos. Os 10% restantes são gotchas: sintaxe backtick-bang (injeção dinâmica) não vai funcionar, e descrições muito longas podem ser truncadas.

Hierarquia global (~/.codex/AGENTS.md) vs projeto, ausência de injeção dinâmica nativa, tamanho ideal mais conservador que Claude.

Codex separa o que é seu específico (.codex/ — config.toml, agents/) do que é spec aberta (.agents/skills/ — segue Agent Skills standard). Convenção que respeita a separação config × extensão.

Quem espera "tudo numa pasta só" como no Claude se confunde. Skills no Codex ficam em ~/.agents/skills/ globalmente e em ./.agents/skills/ por projeto.

Padrão "config no .codex, extensões no .agents", interoperabilidade com outras tools que usam .agents/, separação responsabilidades.

Arquivo em ~/.codex/config.toml ou ./.codex/config.toml: modelo padrão, profile de aprovação, sandbox mode, MCP servers, model providers, network access.

Codex usa TOML em vez de JSON. Sintaxe diferente — chaves em [section], arrays em [[array.section]]. Não é mais difícil, mas é DIFERENTE.

Sintaxe TOML básica, profiles ([profiles.work]), sandbox levels, model provider override, env interpolation.

Sub-agents no Codex são arquivos .toml em .codex/agents/. Têm campos como name, description, model, tools e instructions (string multiline com o system prompt).

Quem chega do Claude espera markdown. O agente do Codex é estrutura — você não escreve "system prompt em prosa", você preenche campos de uma struct.

Multiline string em TOML ("""..."""), invocação EXPLÍCITA (não auto-dispatch), namespace por arquivo, paralelismo manual.

No Codex, sub-agents NÃO são auto-disparados pela descrição. Você precisa chamar pelo nome: "use o agent code-reviewer para revisar X". Sem isso, o agent simplesmente não roda.

É o erro #1 de quem migra. "Por que meu agent não é chamado?" — porque você não chamou. Você escreve a descrição achando que ela dispara, e não dispara. Trade-off: previsibilidade vs conveniência.

Invocação por nome, vantagem de controle (sem surpresa), desvantagem de ergonomia, padrão "menciono o agent no prompt".

Codex tem sandbox configurável em config.toml: read-only (só lê), workspace-write (escreve no projeto), full (livre). E approval modes que controlam quando pedir confirmação.

É a granularidade de segurança do Codex. Mais explícita que a do Claude Code, e configurada via toml. Confuso no início, mas robusto depois de entender.

Sandbox por sessão vs global, escopo de filesystem write, network gating, profiles que combinam (danger-full-access, safe-readonly).

Codex também suporta slash commands customizados, geralmente como arquivos em .codex/commands/ ou via skills com prefixo. Sintaxe de argumentos e namespacing diferem do Claude.

Pra portar seus slash favoritos. A maioria converte 1:1, alguns precisam de adaptação (especialmente se usam injeção dinâmica do Claude).

Convenção de pasta, frontmatter mínimo, ausência de backtick-bang, alternativas pra injeção dinâmica (script + prompt).

Skills do Codex moram em ~/.agents/skills/<nome>/ (global) ou ./.agents/skills/<nome>/ (projeto). Por quê? Porque .agents/ é a convenção da spec aberta — funciona em qualquer tool compatível.

Quem espera .codex/skills/ coloca a skill lá e não funciona. Detalhe pequeno, consequência grande: skill invisível ao agente.

Convenção aberta vs proprietária, portabilidade automática pra outras tools, reload manual (Plugins → refresh).

O arquivo SKILL.md em si é praticamente idêntico: frontmatter YAML com name e description, corpo em markdown. A spec Agent Skills define exatamente esses 4 elementos como comuns.

Saber EXATAMENTE o que é comum permite escrever a maior parte da skill uma vez. Tudo fora desses 4 elementos exige adapter.

Os 4 pilares (SKILL.md, name, description, body + scripts/references/assets), tudo fora disso é runtime-specific.

Arquivo opcional agents/openai.yaml dentro da pasta da skill. Carrega metadata específica de UI (branding, ícone), declarações de MCP server requeridos, e flags de comportamento.

Sem o sidecar, sua skill funciona, mas perde refinamentos: aparece sem ícone, sem branding, e dependências de MCP precisam ser instaladas à mão. Com sidecar, instalação fica turn-key.

Estrutura YAML do sidecar, campos suportados (mcp_servers, branding, hidden), opt-in (não bloqueia funcionamento básico).

O Codex tem um limite não-documentado (~8K caracteres) para o tamanho da description da skill quando ela é indexada no catálogo. Acima disso, description é truncada — e a skill perde gatilhos.

Skill grande importada do Claude pode ter description longa que funciona bem lá e morre no Codex. O polyskill antecipa isso e reescreve.

Limite oculto, comportamento silencioso (não dá erro), técnica de "front-loading" (mover gatilhos pro topo), polyskill como solução automática.

Codex não interpreta backtick-bang como execução shell pré-prompt. Skills do Claude que dependem disso precisam adaptação: virar instrução em prosa ("rode `git status` e analise") ou script chamado.

É a diferença que mais quebra portabilidade de skills do Claude. Polyskill faz a tradução automática como prosa de fallback.

Build-time vs runtime injection, prosa de fallback, script delegado, idempotência.

MCP servers declarados em [mcp_servers.<nome>] dentro do config.toml, ou em sidecar openai.yaml da skill. Mesma spec MCP, mesmo protocolo, declaração diferente.

Pra ligar Slack, Gmail, GitHub etc. no Codex. Comando, args e env vars são iguais ao Claude — só o formato do arquivo muda (TOML/YAML em vez de JSON).

Mapping JSON↔TOML pra MCP, sidecar como local recomendado pra deps de skill, env interpolation no TOML.

Codex usa $nome-skill em vez de /nome-skill pra invocar skill explicitamente. Mesma ideia, sigla diferente. Slash continua existindo pra comandos built-in.

Reflexo de digitar / no Codex resulta em comando interno, não skill. Pequena fonte de atrito que some depois de 1 dia de uso.

Separação slash (built-in) × dollar (skill), nomenclatura kebab-case, auto-completar disponível, alias possível.