Skills de IA no Codex: transforme fluxos repetidos em playbooks reutilizáveis

Na semana passada você fez programação com IA e mandou bem. Descreveu o que queria, o agente construiu, funcionou, você subiu para produção. Aí, na segunda-feira, você precisou da mesma coisa de novo — o mesmo ritual de release, os mesmos passos de onboarding — e digitou o parágrafo inteiro de novo, do zero. Mais uma vez.

Esse buraco é exatamente o que as skills de IA do Codex fecham. Uma skill é um playbook reutilizável que o agente só lê quando uma tarefa combina com ela, então aquilo que você descobriu uma única vez vira um gatilho de uma linha para sempre. A OpenAI lançou as agent skills para o Codex: são pacotes reutilizáveis de instruções — mais scripts e recursos opcionais — que ajudam o Codex a concluir tarefas específicas de forma confiável. Este guia cobre o que são e como escrever a sua primeira — árvore de pastas e frontmatter inclusos — escreva você código ou não.

O que são, de fato, as skills de agentes de IA

Uma skill é uma pasta. Dentro dela mora um arquivo, o SKILL.md, escrito em Markdown puro. Esse é o piso mínimo:

release/
  SKILL.md

E o arquivo em si:

---
name: release
description: Use when cutting a new release. Bumps the version,
  updates the changelog, runs the test suite, drafts release
  notes, and tags the commit. Trigger on "ship a release" or
  "cut version".
---

# Release playbook

1. Bump the version in package.json (patch unless told otherwise).
2. Move everything under "## Unreleased" in CHANGELOG.md into a
   new dated version heading.
3. Run `npm test`. If anything fails, stop and report. Do not tag.
4. Draft release notes from the changelog entries, grouped by
   Added / Fixed / Changed.
5. Create an annotated git tag matching the new version.

O frontmatter YAML exige exatamente dois campos: name e description. O corpo são só instruções, na ordem em que você as daria a um funcionário novo e cuidadoso. Sem schema JSON, sem SDK, sem passo de build. Um fundador não-técnico escreve isso em cinco minutos.

Quando uma skill cresce além de um único fluxo, você adiciona subpastas opcionais: scripts/ para código auxiliar que ela pode rodar, references/ para documentos mais longos que ela puxa quando precisa, assets/ para templates, e um agents/openai.yaml para configuração específica do Codex. Nada disso é obrigatório para começar.

Como skills diferem de prompts (e do AGENTS.md)

Um prompt é uma instrução de tiro único. Você digita, o agente age, as palavras evaporam. Da próxima vez que precisar do mesmo resultado, você reconstrói o prompt de memória — e acerta levemente errado, porque você sempre acerta.

Uma skill é o prompt tornado durável e auto-selecionável. A diferença está naquele campo description. O Codex lê o nome e a descrição de toda skill instalada logo de cara; quando você descreve um objetivo, ele compara seu pedido com essas descrições e carrega o playbook certo sozinho. Você diz "sobe um release", o Codex percebe que a descrição da skill de release menciona exatamente isso, e a tira da prateleira. Você nunca precisa lembrar que a skill existe.

Skills não são AGENTS.md, embora muita gente que constrói com IA confunda isso o tempo todo. O AGENTS.md é contexto de projeto sempre ativo — as regras da casa que o Codex lê em toda tarefa ("a gente usa pnpm, nunca npm; os testes ficam em __tests__; nunca encoste em /legacy"). Skills carregam sob demanda, só quando uma tarefa combina.

AGENTS.md = as regras que o agente sempre conhece.
Skills = os playbooks que ele tira da prateleira quando o trabalho pede um.

Coloque regras sempre necessárias numa skill que raramente dispara e o agente não vai segui-las. Coloque um ritual de release de nicho no AGENTS.md e você inflou o contexto que toda tarefa paga. Coisa certa, camada certa.

Como o Codex dispara uma skill

Há duas formas de disparar uma skill, e a segunda é a interessante.

Invocação explícita. Você chama pelo nome — o comando /skills ou a sintaxe $nome-da-skill, ex. $release. Útil quando você sabe exatamente qual playbook quer.
Invocação implícita. Você descreve o objetivo em português claro e o Codex seleciona automaticamente a skill que combina, a partir das descrições. Nenhum comando para decorar: você diz o que quer feito, e o playbook certo se carrega sozinho.

A razão pela qual você pode instalar dezenas de skills sem o agente ficar lento é a revelação progressiva (progressive disclosure). De início, o Codex lê apenas o nome, a descrição e o caminho do arquivo de cada skill — não o corpo inteiro. Ele carrega o SKILL.md completo só quando decide usar aquela skill. A Anthropic chama a revelação progressiva o princípio de design central que torna as Agent Skills escaláveis. Em bom português: cem playbooks na prateleira custam quase nada até um deles ser puxado.

Skills vivem em escopos que mapeiam para quem o playbook serve:

Nível de repositório — .agents/skills no seu projeto. Playbooks do time, versionados no repo, compartilhados com todo mundo que clona.
Pessoal — $HOME/.agents/skills. Seus próprios playbooks, disponíveis em todos os projetos.
Admin / sistema — /etc/codex/skills. Playbooks padrão da empresa que um admin define para uma máquina ou frota inteira.
Embutidas — skills que já vêm com o próprio Codex, incluindo auxiliares que montam e instalam skills para você.

Codex e Claude Code compartilham o mesmo padrão

O formato SKILL.md é um padrão aberto e multiplataforma, não a invenção de um único fornecedor. A Anthropic o criou com as Agent Skills do Claude Code e o publicou abertamente para portabilidade entre plataformas, e o Codex se apoia nesse mesmo padrão. O frontmatter, o modelo de revelação progressiva e a estrutura de pastas são compartilhados, então um playbook de release é em grande parte portátil entre OpenAI Codex e Claude Code. Você está aprendendo um padrão, não apostando num fornecedor. E skills não são coisa só de programador: skills prontas para documentos e planilhas rodam direto de uma janela de chat, sem terminal nenhum.

Uma biblioteca de skills de exemplo

Alguns playbooks que vale a pena roubar, cada um ancorado em algo que as ferramentas genuinamente fazem:

release/ — o ritual de subir versão, testar e taggear lá de cima. O Codex já lê seu repo, edita arquivos, roda testes e faz commit — então essa skill só transforma esse loop em tiro único.
onboarding/ — instala e configura as ferramentas do time para que o agente de cada pessoa se comporte igual, ensinando ao Codex como vocês lidam com tickets e setup.
branch-review/ — um playbook que orquestra um time de subagents. Uma frase espalha o trabalho entre três especialistas: "Review this branch against main. Have pr_explorer map code paths, reviewer find risks, and docs_researcher verify APIs."

Esse último mostra como skills se compõem com subagents — agentes especializados que o Codex pode disparar em paralelo e consolidar numa única resposta. Uma nota de honestidade que pega muita gente: o Codex só dispara um subagent quando você pede explicitamente. Eles não se acionam sozinhos.

Casos de uso de negócio para fundadores não-técnicos

Você não precisa ler código para nenhum destes.

Respostas consistentes ao cliente. Uma skill support-triage que classifica uma mensagem recebida, redige uma resposta na voz da sua marca e sinaliza tudo que precisa de um humano. Escrita inteiramente em Markdown. Pense num e-commerce que responde dúvidas de frete e troca o dia inteiro — esse é o caso clássico.
Update semanal para investidores. Uma skill investor-update que puxa suas seções padrão, pergunta os três números da semana e redige o e-mail no seu formato.
Setup de novo contratado. Uma skill onboarding para que o primeiro dia rode idêntico toda vez, em vez de viver só na cabeça de uma pessoa.

O padrão: qualquer coisa que você explica do mesmo jeito duas vezes é candidata a virar skill. Para uma agência de automação com IA, isso é praticamente o catálogo de serviços virando código reutilizável.

Checklist de segurança e revisão

Skills adicionam repetibilidade; elas não adicionam julgamento. Rode este checklist antes de confiar em uma:

Escreva uma description que diga quando, não só o quê. A invocação implícita depende inteiramente disso. Uma descrição vaga faz a skill nunca disparar — ou disparar na tarefa errada.
Não jogue tudo num único SKILL.md gigante. Isso anula a revelação progressiva. Quando ficar grande demais, divida o conteúdo em arquivos referenciados que a skill puxa só quando precisa.
Mantenha skills e AGENTS.md em suas camadas certas. Regras sempre ativas no AGENTS.md, playbooks sob demanda nas skills.
Não espere que subagents se autodisparem. Eles não fazem isso — você pede. Atente também aos padrões de número de threads e profundidade.
Embuta o passo de verificação na skill. A repetibilidade de uma skill não remove o risco de aceitar saída de IA sem revisão. Coloque o comando de teste e uma instrução de "pare em caso de falha" diretamente no playbook.
Não assuma aprisionamento ao fornecedor. O SKILL.md é um padrão aberto e portátil. Escreva uma vez; rode em várias ferramentas.

Skills são o passo de maturidade depois do vibe coding. A vibe te dá a primeira versão; a skill a torna confiável, com um portão de verificação embutido.

Guarde os playbooks

Salve suas skills que funcionam como um conjunto versionado no Command Center, para que o fluxo que você descobriu uma vez vire um ativo que o time inteiro reutiliza.

Fontes e leitura adicional

FAQ

Preciso saber programar para escrever uma skill no Codex? Não. As partes obrigatórias de um SKILL.md são Markdown puro — um name, uma description e instruções numeradas. Scripts são opcionais. Se você consegue escrever um passo a passo claro para um colega, consegue escrever uma skill.

Qual a diferença entre uma skill e o AGENTS.md? O AGENTS.md é contexto sempre ativo que o Codex lê em toda tarefa — as regras permanentes do seu projeto. Uma skill carrega só quando uma tarefa combina com a descrição dela. Regras permanentes vão no AGENTS.md; fluxos repetíveis e específicos vão nas skills.

Uma skill que eu escrever para o Codex vai funcionar no Claude Code? Em grande parte, sim. O SKILL.md é um padrão aberto que a Anthropic criou e publicou visando portabilidade entre plataformas, e o Codex se apoia nesse mesmo padrão. O formato, o frontmatter e o modelo de revelação progressiva são compartilhados, então um playbook bem escrito migra entre eles com pouca ou nenhuma mudança.

Por que o Codex não usa minha skill mesmo ela estando instalada? Quase sempre a description. O Codex escolhe skills implicitamente comparando seu pedido com as descrições, então uma vaga ("ajuda com releases") perde para uma precisa ("Use ao cortar um release; sobe a versão, roda testes, taggeia"). Diga quando disparar, não só o que a skill faz.