🎯 Skills no Codex e o sidecar openai.yaml

Esta é a primeira coisa que confunde. Quem vem do Claude pensa: ".claude/skills/ no Claude → .codex/skills/ no Codex". Errado. Skill mora em .agents/skills/.

~/.agents/skills/<nome>/             ← global (suas skills)
./.agents/skills/<nome>/             ← projeto (skills do repo)

# NÃO existe:
.codex/skills/                       ← Codex não enxerga
.codex/agents/skills/                ← idem

O arquivo SKILL.md em si é praticamente o mesmo. Por isso a spec funciona: frontmatter YAML com name e description, corpo em markdown. Essas são as 4 coisas que sempre coincidem.

---
name: revisar-pr
description: Use when the user asks to review a PR or diff.
---

# Revisar PR

## Passo a passo

1. Identifica a PR
2. Lê diff completo
3. Verifica bugs/edge cases/security
4. Retorna findings categorizados

Aqui mora o detalhe que mais peculiariza o Codex: tudo que é específico do runtime (branding pra UI, MCP server dependencies, flags de comportamento) vai num arquivo separado — agents/openai.yaml dentro da pasta da skill.

.agents/skills/minha-skill/
├── SKILL.md                ← obrigatório (spec)
├── agents/
│   └── openai.yaml         ← SIDECAR do Codex
├── scripts/
├── references/
└── assets/

# Branding pra UI do Codex
branding:
  display_name: "Revisar PR"
  icon: "🔍"
  category: "code-review"

# MCP servers requeridos pela skill
mcp_servers:
  - name: github
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: "${GITHUB_TOKEN}"

# Flags de comportamento
hidden: false
require_confirmation: true

O Codex tem um limite não-documentado de cerca de 8.000 caracteres para a description quando indexada no catálogo. Acima disso, description é truncada — e sua skill perde os triggers que estão no fim.

// CERTO — triggers no topo
description: |
  Use when reviewing PRs.
  Triggers: "revisa PR", "review pull request", "code review".
  Examples: "revisa PR #123", "review da branch atual".

  More context (pode ser truncado): ...

// ERRADO — triggers no fim
description: |
  This skill specializes in deep technical code review with focus on
  correctness, security, and edge cases. It analyzes pull requests
  by reading the full diff and ... [muito mais texto] ...
  Triggers: "revisa PR" ← truncado, nunca alcança

Codex não interpreta `!cmd` (backtick-bang) como execução shell pré-prompt. Skill que depende disso pra injetar contexto dinâmico (status do git, log atual, branch) precisa adaptação.

Branch: `!git branch --show-current`

Último commit:
`!git log -1 --oneline`

Com base no acima, sugira...

Antes de começar, rode:
- `git branch --show-current`
- `git log -1 --oneline`

Com base nos resultados, sugira...

# scripts/context.sh
#!/bin/bash
echo "Branch: $(git branch --show-current)"
echo "Commit: $(git log -1 --oneline)"

# SKILL.md
Antes de começar, rode `./scripts/context.sh` e leia o output.

Mesma spec MCP. Mesmo server roda. Só a declaração muda — TOML em vez de JSON, dentro do config.toml ou no sidecar openai.yaml da skill (quando MCP é dependência específica).

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@mcp/github"],
      "env": {
        "TOKEN": "$GH_TOKEN"
      }
    }
  }
}

[mcp_servers.github]
command = "npx"
args = ["-y", "@mcp/github"]

[mcp_servers.github.env]
TOKEN = "${GH_TOKEN}"

Codex usa o cifrão pra invocação explícita de skill, deixando o slash reservado pra comandos built-in. $nome-skill em vez de /nome-skill. Pequeno detalhe que pega no primeiro dia.

/review             ← skill OU slash command
/plan               ← built-in
/output-style x     ← built-in

$review            ← skill
/help              ← built-in (Codex)
/model             ← built-in (Codex)