Como escrever a descrição de uma skill do Codex

O que é cada coisa

1. Skill: uma pasta com instruções que ensina o Codex a fazer uma tarefa do jeito que você quer. Dentro dela fica o arquivo SKILL.md.
2. SKILL.md: o arquivo principal da skill. Ele precisa ter dois campos no topo: name (o nome da skill) e description (a descrição). Esses dois campos ficam entre duas linhas com ---.
3. Descrição: uma frase que diz para que a skill serve e quando usar. É por ela que o Codex decide se a skill combina com o seu pedido.
4. Consulta SQL: um pedido escrito na linguagem SQL para buscar dados numa tabela, como "some o valor das vendas de cada cliente".
5. Chamada automática: o Codex escolhe a skill sozinho quando o seu pedido combina com a descrição.
6. Chamada direta: você chama a skill pelo nome. No Codex CLI e na extensão da IDE, digite $ e o nome da skill.
7. Codex CLI e extensão da IDE: o Codex CLI é o Codex usado pelo terminal, o programa onde você digita comandos. A extensão da IDE é o Codex dentro de um editor de código, como o VS Code.
8. Repositório e $HOME: repositório é a pasta de um projeto de código. $HOME é a sua pasta de usuário no computador; o ~ dos comandos é a mesma coisa.

Como o Codex escolhe

Primeiro o Codex lê só o nome e a descrição de cada skill. O SKILL.md inteiro, com o passo a passo, só entra quando ele decide usar aquela skill. Por isso a descrição precisa ter um escopo claro: dizer o que a skill faz e quando ela não deve entrar. Se você tem muitas skills instaladas, o Codex pode encurtar as descrições. Coloque o caso principal e as palavras importantes logo no começo.

• Descrição vaga: ajuda com dados. Cabe em quase qualquer pedido sobre dados: gráfico, planilha, relatório ou SQL.
• Descrição clara: Use para revisar consultas SQL, procurar erros e sugerir melhorias. Diz o assunto e o que a skill faz.

O exemplo pronto

1. Crie a pasta da skill. A pasta $HOME/.agents/skills vale para todos os seus projetos. Para uma skill de um projeto só, use .agents/skills dentro do repositório. No terminal do Mac ou do Linux, o comando mkdir -p cria a pasta (e as pastas acima dela, se faltarem):

mkdir -p ~/.agents/skills/revisar-sql

2. Dentro dessa pasta, crie o arquivo SKILL.md com este conteúdo:

---
name: revisar-sql
description: Use para revisar consultas SQL, procurar erros e sugerir melhorias. Não use para criar gráficos nem para escrever consultas novas do zero.
---

# Revisar consulta SQL

1. Leia a consulta que a pessoa enviou.
2. Procure erros: comandos escritos errado, tabelas ligadas de um jeito que duplica linhas, filtros de data incompletos e colunas que não existem.
3. Explique cada problema em linguagem simples.
4. Mostre a consulta corrigida e diga o que mudou.

3. O Codex percebe a skill nova sozinho. Se ela não aparecer, reinicie o Codex.

Como testar

1. Peça a revisão de uma consulta. Este pedido combina com a descrição, então a skill tem boa chance de entrar:

revisa esta consulta:
SELECT cliente, SUM(valor)
FROM pedidos
WHERE data >= '2026-01-01'
GROUP BY cliente;

2. Depois peça uma coisa fora do escopo. A descrição diz que a skill não serve para gráficos, então ela provavelmente não entra:

faz um gráfico com esses dados

3. Compare as duas respostas. Na primeira, procure sinais de que o Codex seguiu os passos da skill (leu, procurou erros, explicou, corrigiu). Isso é um indício, não uma confirmação. Se o resultado não for o esperado, ajuste a descrição e teste de novo.
4. Para chamar a skill direto, sem depender da escolha automática, no Codex CLI ou na extensão da IDE:

$revisar-sql revisa esta consulta

Opcional: só chamada direta

Se você quer que a skill entre apenas quando for chamada pelo nome, crie o arquivo agents/openai.yaml (um arquivo de configuração em texto simples) dentro da pasta da skill (revisar-sql/agents/openai.yaml) com:

policy:
  allow_implicit_invocation: false

O padrão é true (ligado: o Codex pode escolher a skill sozinho). Com false (desligado), ele não escolhe a skill sozinho, e a chamada com $revisar-sql continua funcionando.

Resumo para guardar

1. A descrição é o que o Codex lê para escolher a skill.
2. Diga o assunto, o que a skill faz e quando ela não deve entrar.
3. Coloque o caso principal no começo da frase.
4. Teste com um pedido que deve acionar a skill e outro que não deve.
5. Para chamar direto: $nome-da-skill no CLI ou na IDE.

Fonte

OpenAI, Build skills, documentação do Codex, lida em 13/11/2026: learn.chatgpt.com/codex/build-skills.

Conteúdo educativo e independente, sem afiliação com a OpenAI.