Codex Skills explicado: o que é o SKILL.md e como usar (2026)

- Os fatos e números abaixo foram conferidos com a documentação oficial no momento em que escrevi (08/2026); a terminologia de Codex Skills/Plugins muda rápido — verifique a documentação ao vivo antes de depender dela.

O que são as Codex Skills?

Uma Codex skill é uma pasta que empacota instruções — e, opcionalmente, scripts, referências e assets — em uma capacidade reutilizável que o Codex puxa só quando a tarefa pede. Em vez de reexplicar "é assim que fazemos migrações de banco de dados" a cada sessão, você escreve isso uma vez como um arquivo SKILL.md e o Codex carrega sob demanda.

Aqui vai a distinção que vale a pena deixar clara primeiro: Codex Skills não é um formato que a OpenAI inventou do zero. O SKILL.md é o padrão aberto Agent Skills — "originalmente desenvolvido pela Anthropic, lançado como padrão aberto e adotado por um número crescente de produtos de agentes", segundo o próprio site do padrão. A Anthropic lançou primeiro para o Claude Code (outubro de 2025); a OpenAI adotou o mesmo formato de arquivo para o Codex e o ChatGPT poucas semanas depois. Mesmo SKILL.md, dois ecossistemas.

Na prática, uma skill é: um nome mais uma description que funciona como gatilho (sempre visível ao Codex) e um corpo em Markdown (carregado só quando há match). Ela foi feita para trabalho repetível e em formato de tarefa — uma rotina de correção de lint, um checklist de migração, um formato de changelog — não para conhecimento geral ou contexto de projeto sempre ativo. Esse é o papel do AGENTS.md, que eu abordo mais adiante.

Um teste rápido de bom senso antes de escrever uma: você colaria isso numa sessão mais do que umas poucas vezes, e o conteúdo se mantém basicamente o mesmo toda vez? Se sim, tem cara de skill. Se os passos mudam conforme o arquivo ou a funcionalidade que você está mexendo, ou se é só conhecimento geral de "como este repositório funciona", provavelmente pertence a outro lugar — um doc, um comentário ou o AGENTS.md.

Anatomia de um arquivo SKILL.md

Uma skill é uma pasta nomeada a partir do seu slug, com um arquivo obrigatório e até quatro opcionais:

my-skill/
├── SKILL.md            (required)
├── scripts/            (optional - executable code)
├── references/         (optional - docs the skill can point to)
├── assets/             (optional - templates, static files)
└── agents/openai.yaml  (optional - Codex-specific UI + MCP metadata)

O SKILL.md em si é frontmatter YAML seguido de instruções em Markdown. Só dois campos são obrigatórios:

---
name: changelog-writer
description: Turn a git diff into a changelog entry. Use when the
  user asks for a changelog, release notes, or "what changed".
---

# Changelog writer

1. Run `git diff --stat` and `git log -5 --oneline`.
2. Group changes by type: Added, Changed, Fixed.
3. Write 3-6 bullet points in the project's changelog format.

name é o identificador; description é o gatilho — a única linha que o Codex lê para decidir se a skill se aplica, então escreva com precisão ("use quando...") em vez de algo vago ("ajuda com changelogs").

O opcional agents/openai.yaml é específico do Codex: ele não afeta o Claude Code nem nenhum outro cliente, só como a skill aparece e se comporta dentro do Codex/ChatGPT. Segundo a documentação atual, ele cobre três grupos de campos — interface (display_name, short_description, icon_small/icon_large, brand_color, default_prompt), política (allow_implicit_invocation, true por padrão) e uma lista de dependências de ferramentas (um servidor MCP de que a skill precisa, com seu transporte e URL). Os nomes dos campos deste arquivo mudam junto com o produto — confira a documentação ao vivo antes de contar com um deles em produção.

Como as Codex Skills funcionam (divulgação progressiva)

O mecanismo que torna as skills baratas de manter por perto se chama divulgação progressiva, e ele roda em três estágios, segundo a documentação oficial:

1. Descoberta — na inicialização, o Codex carrega apenas o name e a description de cada skill. Suficiente para saber que uma skill existe, mas não para usá-la ainda.
2. Ativação — quando o seu prompt dá match com a description de uma skill, o Codex lê o corpo completo do SKILL.md para o contexto.
3. Execução — o Codex segue as instruções, rodando scripts empacotados ou puxando arquivos de references/assets conforme a skill precisar.

O estágio de descoberta tem um orçamento rígido: a lista inicial de skills (o name mais a description de cada skill instalada, combinados) é limitada a 2% da janela de contexto do modelo, ou 8.000 caracteres quando o tamanho da janela de contexto é desconhecido — o que se aplicar. Esse é um teto real que os concorrentes raramente mencionam: instale skills verbosas demais e algumas simplesmente não vão entrar na lista.

Daí seguem duas consequências práticas. Primeiro, escreva descriptions enxutas — isso deixa espaço para outras skills, e uma vaga ("ajuda com código") não dispara de forma confiável, enquanto uma precisa ("use quando a pessoa pedir um changelog...") dispara. Segundo, não coloque nada sensível ao tempo só na description; se só importa quando a skill já está rodando, coloque no corpo, não na linha de gatilho.

Onde o Codex procura skills (escopo e precedência)

O Codex varre vários locais em busca de skills, do mais específico ao mais geral. Para um nome que dá match, o local mais específico vence:

Duas formas de acionar uma skill assim que o Codex consegue enxergá-la:

• Explícita — digite $skill-name no Codex CLI ou na IDE (ou /skills para navegar), @skill-name no ChatGPT.
• Implícita — é só descrever a tarefa em linguagem natural; o Codex compara com a description de cada skill visível e invoca automaticamente.

Faça o commit das skills com escopo de repositório em .agents/skills/ para que o time inteiro receba; mantenha os hábitos pessoais na pasta de escopo de usuário para que eles te acompanhem entre projetos.

Como instalar e criar uma Codex skill

Dois caminhos: instalar uma que outra pessoa escreveu, ou construir a sua própria.

Instalar uma skill já existente

Dentro de uma sessão do Codex, rode a skill instaladora nativa:

$skill-installer linear

Aponte para um nome do catálogo atual, ou uma URL do GitHub, e ela clona a skill para a sua pasta de skills (escopo de usuário por padrão; passe um caminho de projeto se você quiser com escopo de repositório). Uma observação sobre atualidade que vale conhecer: o catálogo de skills da OpenAI já mudou de lugar uma vez. O openai/skills no GitHub tem um aviso de descontinuação apontando para o openai/plugins — e, no momento em que escrevo, esse repositório sucessor também já foi arquivado (somente leitura, sem substituto listado). Nenhum dos dois repositórios do GitHub é um catálogo confiável e ativo agora. Trate a página da documentação oficial como o único link em que vale confiar, e espere que a lista de fontes padrão do $skill-installer continue mudando — verifique para o que ela realmente resolve antes de rodá-la dentro de um script.

Construa a sua própria com o criador interativo

$skill-creator

Ele te guia por nomear a skill, escrever a description que serve de gatilho e rascunhar o corpo de forma interativa, e então salva a pasta no seu caminho de skills. Para uma skill que você mesma vai reutilizar, três hábitos importam mais do que a ferramenta em si:

1. Escreva a description como um gatilho, não como um resumo — "use quando X" ganha de "ajuda com X".
2. Mantenha o corpo em formato de tarefa. Se você está documentando contexto de projeto sempre verdadeiro em vez de um trabalho específico, isso pertence ao AGENTS.md, não a uma skill.
3. Teste os dois caminhos de invocação — chame explicitamente com $your-skill primeiro para confirmar que o corpo funciona, depois acione implicitamente com linguagem natural para confirmar que a description realmente dispara.

Você também pode simplesmente criar a pasta e o arquivo na mão — mkdir -p .agents/skills/my-skill && touch .agents/skills/my-skill/SKILL.md — o criador interativo é uma conveniência, não um requisito.

Codex Skills vs AGENTS.md vs Plugins — de qual você precisa?

Três primitivas, três funções. Elas não competem — a maioria das configurações reais de Codex usa duas, ou as três, ao mesmo tempo.

A definição oficial, quase ao pé da letra: uma skill "empacota instruções e recursos de apoio para uma tarefa ou fluxo de trabalho específico", enquanto um plugin "é um pacote instalável que pode incluir skills, conectores, ou ambos". Então um plugin não é um quarto formato competindo com as skills — é uma camada de empacotamento que pode entregar uma ou várias skills juntas, além de coisas que não são skills, como conectores.

O AGENTS.md fica numa pista totalmente diferente: ele não é carregado sob demanda, está sempre no contexto — que é exatamente por que o conselho para ele vai no sentido oposto ao de uma skill. Mantenha-o curto (comandos, regras rígidas, caminhos-chave), não longo, porque cada linha custa tokens em cada turno. Para o guia completo sobre escrever um enxuto, veja AGENTS.md vs CLAUDE.md vs SKILL.md; para a ordem de busca do AGENTS.md do próprio Codex, veja o guia do AGENTS.md do Codex.

Na prática, os três se empilham, não se substituem. Um repositório típico pode manter um AGENTS.md curto para comandos de build/teste e regras rígidas, um punhado de skills para trabalhos repetíveis como notas de versão ou um padrão específico de refatoração, e instalar um pacote de plugin que entrega várias skills relacionadas mais um conector de uma vez. Nenhum dos três substitui os outros; cada um só responde a uma pergunta diferente sobre quando o Codex deve saber ou fazer algo.

As Codex Skills são iguais às Claude Code Skills?

No essencial, sim — e há uma fonte primária de verdade para isso, não só um achismo. O agentskills.io, o próprio site do padrão, lista "Claude Code" e "ChatGPT & Codex" lado a lado como clientes suportados, e afirma que o formato "foi originalmente desenvolvido pela Anthropic, lançado como padrão aberto e adotado por um número crescente de produtos de agentes".

Vale ser precisa aqui: nenhuma página única da OpenAI diz "compatível com Claude Code" com essas palavras exatas. A afirmação de compatibilidade cruzada se apoia na lista de clientes do próprio padrão mais análises independentes de terceiros, não em uma citação da OpenAI — então é assim que este artigo enquadra a coisa: mesmo padrão aberto, não um aval oficial da OpenAI ao Claude Code.

O que de fato viaja entre as duas ferramentas: o próprio arquivo SKILL.md — name, description, o corpo em Markdown e as pastas scripts//references/assets. Escreva uma skill em uma ferramenta e o arquivo central funciona na outra, com extras não lidos e tudo.

O que não viaja são os extras específicos de cada cliente, que a outra ferramenta simplesmente ignora:

• O Codex acrescenta agents/openai.yaml para metadados de UI do ChatGPT desktop e dependências de ferramentas MCP.
• O Claude Code acrescenta context: fork (roda a skill em um subagente isolado) e disable-model-invocation (bloqueia o disparo automático de skills com efeitos colaterais) — veja o detalhamento completo em Claude Code Skills explicado.

Conclusão prática: construa uma skill sem frontmatter específico de cliente e ela já é portável por padrão. Acrescente um campo só do Codex ou só do Claude e a outra ferramenta apenas o ignora — não quebra, só não faz nada ali.

Não quer escrever a sua? Kits prontos de skills e fluxos de trabalho

Escrever skills na mão é ótimo quando você quer um fluxo de trabalho exato e pessoal. Se você prefere começar de uma biblioteca curada em vez de um SKILL.md em branco, essa é a lacuna que o AgentKit honestamente preenche — veja como ele se encaixa no Codex especificamente em usando o AgentKit dentro do Codex, ou vá direto para o agentkit.best. Uma distinção rápida, já que os nomes se confundem: este é o AgentKit de afiliado (agentkit.best, CLI ak) — não o produto AgentKit/Agent Builder da própria OpenAI.

Para ser direta sobre o limite: o recurso nativo de Skills do Codex é gratuito, incluído no seu plano do ChatGPT — nada aqui exige uma compra. O AgentKit é um complemento à parte e pago: um kit curado de skills, subagentes e fluxos de trabalho prontos que se instala no Codex com ak kit init engineer --target codex --global e depois roda via $ak:cook em vez de você escrever cada SKILL.md na mão. É a opção "alguém já construiu e testou isto", não um requisito para as Skills funcionarem.

FAQ

As Codex Skills são gratuitas?

Sim. As Skills são um recurso nativo do Codex incluído no seu plano do ChatGPT — escrever, instalar e rodar seus próprios arquivos SKILL.md não custa nada a mais. Um custo só aparece se você escolher comprar um kit pronto de terceiros em vez de construir o seu.

Qual é a diferença entre uma Codex skill e o AGENTS.md?

Uma skill é sob demanda: ela carrega só quando uma tarefa dá match com a sua description. O AGENTS.md é sempre carregado: ele fica no contexto a cada turno. Use uma skill para um trabalho específico e repetível; use o AGENTS.md para comandos e regras que devem ser sempre conhecidos.

As Codex Skills funcionam no Claude Code?

O arquivo central SKILL.md funciona — as duas ferramentas leem o padrão aberto Agent Skills, e o agentskills.io lista as duas como clientes suportados. Os extras específicos de cada cliente não passam de uma para a outra: o agents/openai.yaml do Codex é ignorado pelo Claude Code, e os campos context: fork / disable-model-invocation do Claude Code são ignorados pelo Codex.

Onde eu coloco uma Codex skill personalizada?

Para todo o repositório: .agents/skills/ na raiz do repositório (faça o commit para que o time também receba). Pessoal, em todos os projetos: $HOME/.agents/skills. O Codex também verifica o diretório de trabalho atual e o seu pai, além de locais de admin e incluídos no sistema, nessa ordem.

Posso instalar a skill de outra pessoa?

Pode — rode o $skill-installer de dentro do Codex, apontando para um nome de catálogo ou uma URL do GitHub, e ele clona a skill para a sua pasta de skills. Revise o SKILL.md e os scripts de qualquer skill de terceiros antes de instalar, do mesmo jeito que você revisaria uma nova dependência.

O openai/skills ainda é o catálogo oficial de skills?

Não. O openai/skills no GitHub está descontinuado e aponta para o openai/plugins — e, no momento em que escrevo, o openai/plugins também já foi arquivado (somente leitura). Nenhum dos repositórios é um catálogo ativo; use a documentação oficial em learn.chatgpt.com/docs/build-skills.

Conclusão

Uma Codex skill é uma pasta, um arquivo SKILL.md e uma description que serve de gatilho — nada mais exótico que isso. Ela é sob demanda onde o AGENTS.md é sempre ativo, portável para o Claude Code porque os dois leem o mesmo padrão aberto Agent Skills, e gratuita porque vem dentro do próprio Codex. Comece pequeno: escolha uma tarefa que você vive reexplicando ao Codex, escreva uma description enxuta e deixe a divulgação progressiva mantê-la barata. Se você prefere não escrever uma biblioteca do zero, um kit curado como o AgentKit é o atalho pago — não um requisito. Veja como o AGENTS.md se encaixa ao lado das skills em o guia do AGENTS.md do Codex, ou comece por o que é o Codex se você ainda está se situando.