🎯 Skills in Codex and the openai.yaml sidecar

This is the first thing that causes confusion. People coming from Claude think: ".claude/skills/ in Claude → .codex/skills/ in Codex". Wrong. Skill lives in .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

The SKILL.md file itself is practically the same. That’s why the spec works: YAML frontmatter with name e description, Markdown body. These are the 4 things that always match.

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

This is where the detail that makes Codex most distinctive lives: everything that is runtime-specific (branding for the UI, MCP server dependencies, behavior flags) goes in a separate file — agents/openai.yaml inside the skill folder.

.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 has a undocumented limit of about 8,000 characters for the description when indexed in the catalog. Above that, the description is truncated — and your skill loses the triggers at the end.

// 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 doesn’t interpret `!cmd` (backtick-bang) as shell execution before the prompt. A skill that depends on this to inject dynamic context (git status, current log, branch) needs adaptation.

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

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

Com base no acima, sugira...

Before you start, run:
- `git branch --show-current`
- `git log -1 --oneline`

Based on the results, suggest...

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

Same MCP spec. Same server runs. Only the declaration changes — TOML instead of JSON, inside the config.toml or in the sidecar openai.yaml of the skill (when MCP is a specific dependency).

{
  "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 uses the dollar sign for explicit skill invocation, leaving slash for built-in commands. $nome-skill instead of /nome-skill. A small detail that catches you on day one.

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

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