Uma skill é uma pasta que contém um arquivo SKILL.md. Esse arquivo informa o nome e a descrição da skill e traz as instruções que o Codex deve seguir. A pasta pode incluir scripts, referências e modelos se forem necessários para o trabalho.
O Codex pode escolher uma skill quando a tarefa combina com sua descrição. Também é possível chamá-la explicitamente no CLI ou na extensão de IDE pelo nome, com $. Uma skill não garante um resultado: ela orienta o agente, enquanto as ações possíveis dependem das ferramentas e permissões do ambiente.
Onde o Codex encontra skills?
Para uma skill de um repositório, a documentação do Codex indica a pasta .agents/skills/. No escopo pessoal, o caminho é ~/.agents/skills/. O Codex procura skills do repositório a partir da pasta de trabalho e de suas pastas superiores até a raiz do repositório.
meu-projeto/
└── .agents/
└── skills/
└── minha-skill/
└── SKILL.mdO que escrever no SKILL.md?
Use um nome curto e uma descrição específica. Explique em quais pedidos a skill deve ser usada, quais passos seguir e o que fazer quando faltar informação. O Codex também pode carregar arquivos de referência ou scripts da pasta quando o fluxo precisar deles.
Como conferir se funcionou?
Peça ao Codex uma tarefa que corresponda claramente à descrição ou chame a skill de forma explícita com $nome-da-skill. Compare a resposta com o resultado esperado. Se a skill não aparecer após uma mudança, reinicie o Codex e verifique a pasta e o SKILL.md.
Skills do Codex e Claude Code usam uma estrutura semelhante baseada em SKILL.md, mas os locais, recursos e regras de cada ferramenta podem variar. Não presuma que uma configuração específica de uma ferramenta vale automaticamente para a outra.
Fonte oficial
Consulte o guia oficial da OpenAI para criar, organizar e usar skills no Codex.