🎯 Skills en Codex y el sidecar openai.yaml

Esto es lo primero que confunde. Quien viene de Claude piensa: «.claude/skills/ en Claude → .codex/skills/ en Codex». Incorrecto. La skill está en .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

El archivo SKILL.md en sí es prácticamente lo mismo. Por eso funciona la spec: frontmatter YAML con name e description, cuerpo en Markdown. Estas son las 4 cosas que siempre coinciden.

---
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

Aquí está el detalle que más distingue a Codex: todo lo que es específico del runtime (branding para la UI, dependencias del MCP server, flags de comportamiento) va en un archivo separado — agents/openai.yaml dentro de la carpeta de la 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

Codex tiene un límite no documentado de unos 8.000 caracteres para la description cuando se indexa en el catálogo. Por encima de eso, la description se trunca, y tu skill pierde los triggers que están al final.

// 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 no interpreta `!cmd` (backtick-bang) como ejecución de shell previa al prompt. La skill que dependa de esto para inyectar contexto dinámico (estado de git, registro actual, branch) necesita una adaptación.

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

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

Com base no acima, sugira...

Antes de empezar, ejecuta:
- `git branch --show-current`
- `git log -1 --oneline`

Con base en los resultados, sugiere...

# 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.

La misma especificación de MCP. Se ejecuta el mismo server. Solo cambia la declaración — TOML en lugar de JSON, dentro del config.toml o en el sidecar openai.yaml de la skill (cuando MCP es una dependencia 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 el signo de dólar para invocar una skill explícitamente y reservar slash para los comandos integrados. $nome-skill en lugar de /nome-skill. Un pequeño detalle que te afecta desde el primer día.

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

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