Skills do Codex: como criar uma skill para tarefas repetitivas

Se explicar a mesma coisa ao Codex cinco vezes por semana — como formatar um relatório, tratar do correio eletrónico ou preparar textos ao seu estilo — pode escrever essas instruções uma vez numa skill. Depois disso, o agente pode encontrá-la pela descrição quando esta corresponder à tarefa, ou pode invocá-la explicitamente. Uma skill é uma pasta normal com um ficheiro de texto chamado SKILL.md; não é necessária programação para um caso de utilização básico.

A seguir, explicamos a estrutura de uma skill, onde o Codex a procura, como criar uma passo a passo e como escolher um modelo em função do custo. Os comandos e os preços baseiam-se na documentação oficial da OpenAI em 20 de setembro de 2026. Não repetimos aqui as instruções de instalação do Codex; estão no guia Codex da OpenAI: o que é, como instalar e executar.

Encontra informações práticas sobre a utilização do Ailoot na documentação.

O que é uma skill no Codex?#

Este formato chama-se Agent Skills. É uma norma aberta, originalmente desenvolvida pela Anthropic e publicada em agentskills.io. É suportada por vários agentes, incluindo o Codex, o Claude Code e outros clientes compatíveis. Uma skill simples, composta apenas por instruções em texto, pode ser transferida entre eles copiando a pasta. Se incluir scripts, dependências ou um ficheiro agents/openai.yaml, verifique a skill depois de a transferir: algumas definições são específicas de determinado cliente.

Este método de carregamento chama-se divulgação progressiva. O agente utiliza o nome e a descrição de uma skill para determinar quando é relevante. Quando uma tarefa corresponde à descrição, o agente lê o SKILL.md completo e segue as instruções. Assim, pode ter dezenas de skills no Codex sem carregar todas as instruções para o contexto: a lista inicial ocupa, no máximo, 2% da janela de contexto (ou 8 000 caracteres, se a dimensão da janela for desconhecida). Se houver muitas skills, o Codex encurta primeiro as respetivas descrições; com um conjunto muito grande, poderá omitir algumas da lista e notificá-lo.

É fácil confundir uma skill com o AGENTS.md. O Codex lê este ficheiro em todas as sessões de projeto. Contém regras permanentes: a stack tecnológica, as convenções e o estilo de programação. Uma skill é carregada a pedido, quando uma tarefa corresponde ao seu âmbito. Por isso, coloque as regras permanentes no AGENTS.md e os processos repetitivos com etapas numa skill.

As skills do Hermes Agent funcionam de forma semelhante, mas são guardadas em pastas diferentes e instaladas de outra maneira. São abordadas num guia separado: Skills do Hermes Agent: instalação e criação. Este artigo é apenas sobre o Codex.

Em que consiste uma skill?#

Uma pasta de skill tem esta estrutura:

my-skill/
  SKILL.md        - obrigatório: metadados e instruções
  scripts/        - opcional: código executável
  references/     - opcional: documentos a carregar conforme necessário
  assets/         - opcional: modelos e recursos
  agents/
    openai.yaml   - opcional: apresentação e dependências

O próprio ficheiro SKILL.md começa com um bloco de metadados entre três hífenes, seguido do texto das instruções em Markdown:

---
name: weekly-sales-report
description: Compile um relatório semanal de vendas a partir de uma exportação CSV. Use quando lhe pedirem um relatório semanal de vendas ou um resumo por gestor.
---

1. Leia o ficheiro de exportação no caminho indicado pelo utilizador.
2. Agrupe as linhas por gestor e calcule o total e o número de negócios.
3. Compare com a semana anterior, se o ficheiro da semana anterior estiver nas proximidades. Se não estiver, diga-o diretamente no relatório.
4. Guarde o resultado em report.md: uma tabela por gestor, o total e até três alterações importantes com valores, tantas quantas os dados permitirem.

Três regras das recomendações oficiais da OpenAI:

• Uma skill, uma tarefa. Em vez de «Trata de todo o meu marketing», escolha uma tarefa específica: «compila um relatório de vendas a partir desta exportação». Divida um processo maior em skills separadas que possam ser invocadas em sequência.
• Escreva as etapas de forma direta, com entradas e saídas explícitas: o que utilizar, o que fazer e onde colocar o resultado.
• Comece com instruções em texto. Utilize scripts em scripts/ quando uma etapa tiver de ser executada sempre exatamente da mesma forma — por exemplo, para converter um ficheiro ou contactar um sistema externo.

O Codex seleciona uma skill para uma tarefa com base no campo description, por isso comece a descrição pela tarefa e pelas palavras que costuma utilizar para a descrever.

Onde procura o Codex as skills?#

É prático guardar as skills do projeto no git juntamente com o código para que toda a equipa tenha o mesmo conjunto. As skills pessoais são úteis para os seus próprios processos, como o seu estilo de correio eletrónico. Se duas skills em níveis diferentes tiverem o mesmo nome, o Codex não as combina: ambas aparecem na lista, o que dificulta a escolha. Mantenha nomes únicos.

Para comparação, as skills do Claude Code são guardadas em .claude/skills, cada uma com o seu próprio SKILL.md, e utilizam a mesma norma aberta. Uma skill simples pode ser transferida para lá copiando a pasta; depois, execute-a e verifique se é invocada. Para uma comparação das extensões do Claude Code, consulte Skills, Subagents, MCP ou Plugins.

Como decide o Codex que skill deve invocar?#

A invocação explícita é mais fiável no início: na CLI do Codex, introduza $weekly-sales-report para selecionar esse processo específico. A invocação implícita é mais prática no trabalho quotidiano. Depois de escrever uma skill, teste-a com uma formulação normal: peça ao Codex que execute a tarefa pelas suas próprias palavras, sem $, e veja se seleciona a skill. Se não o fizer, verifique primeiro se o Codex consegue ver a skill em /skills, se está numa das pastas de carregamento e se a skill ou a respetiva invocação automática não está desativada. Se estiver disponível e as definições estiverem corretas, refine a description: indique a tarefa e as formas habituais de formular o pedido.

Se quiser que uma skill esteja disponível apenas através de um comando explícito, também pode configurar isso: em agents/openai.yaml, o parâmetro allow_implicit_invocation: false desativa a invocação automática, enquanto $name continua a funcionar. Pode desativar completamente uma skill sem a eliminar através de ~/.codex/config.toml:

[[skills.config]]
path = "/full/path/to/the/skill/SKILL.md"
enabled = false

Depois de editar config.toml, reinicie o Codex. O Codex deteta automaticamente as alterações nas pastas das skills, mas, se uma nova skill não aparecer, reinicie o Codex.

Como criar a sua própria skill: passo a passo#

1. Escolha uma tarefa

   Escolha um processo que repita regularmente e que tenha um resultado claro: um relatório, uma tabela, uma carta ou uma análise. Se nunca recebeu esse tipo de resultado, execute primeiro a tarefa manualmente com um agente. Utilize o resultado obtido como referência para as instruções.

2. Crie uma skill

   Para criar uma skill com o assistente integrado, introduza $skill-creator numa sessão do Codex. O assistente perguntará o que a skill faz, quando deve ser invocada e se são necessários scripts; depois, criará a estrutura por si. Para a criar manualmente, crie uma pasta .agents/skills no projeto, com uma subpasta para a skill, como .agents/skills/weekly-sales-report, e coloque lá um ficheiro SKILL.md utilizando o exemplo acima.

3. Escreva as instruções

   Escreva as etapas numa lista numerada com entradas e saídas explícitas. Se o processo exigir precisão (transferência de dados, mudança de nomes, cálculos), descreva cada etapa em pormenor. Para tarefas criativas (escrever textos, escolher argumentos), defina limites e critérios para um bom resultado, deixando espaço para o modelo trabalhar.

4. Teste a invocação

   Peça ao Codex que execute a tarefa pelas suas próprias palavras, sem mencionar o nome da skill. Se selecionar a skill certa, a descrição funcionou para essa formulação. Depois, teste a invocação explícita com $name. Se a skill não for invocada, verifique a pasta, se aparece em /skills e as definições de desativação descritas acima. Se uma nova skill não aparecer na lista, reinicie o Codex. Se a invocação explícita funcionar e a invocação automática estiver permitida, mas o Codex não responder a um pedido formulado pelas suas próprias palavras, refine o início da description: coloque primeiro a tarefa, seguida das formas habituais de a formular. Teste novamente.

5. Refine após as execuções

   Após cada execução, reveja o resultado e diga ao agente o que deve alterar na skill: «Da próxima vez, acrescenta uma coluna que mostre a proporção na tabela de resumo.» Refine uma skill para trabalho criativo com base no feedback se a primeira versão não produzir o resultado de que precisa.

As skills prontas da OpenAI e da comunidade são instaladas com $skill-installer e o nome da skill. Para partilhar as suas skills com outras pessoas, distribua-as como plugins — este é um método de empacotamento separado, que não é necessário para uso pessoal.

Como verificar o resultado de um agente#

As verificações podem ser objetivas ou subjetivas. As verificações objetivas podem ser medidas: «o relatório inclui os 12 gestores da exportação» ou «a soma da tabela corresponde ao total do CSV». Registe-as como requisitos firmes. As verificações subjetivas dizem respeito à qualidade: «o texto parece escrito por mim» ou «as conclusões são breves». Também pode formalizá-las: inclua na skill um exemplo de uma boa passagem e peça ao agente que compare o resultado com esse exemplo.

Uma técnica útil é um ciclo de revisão: depois de preparar o resultado, o agente percorre uma lista de critérios, corrige o que encontrar e só então lho mostra. A Anthropic utiliza um padrão semelhante chamado evaluator-optimizer: um agente executa o trabalho, um avaliador separado revê-o e devolve feedback, e o processo repete-se até à aceitação. Numa única skill, trata-se normalmente de uma versão simplificada — uma autoverificação final com base numa lista. Tenha presente a limitação: é mais fraca do que uma avaliação independente, porque o agente que fez o trabalho pode não detetar o próprio erro.

Exemplo de um bloco de verificação para o nosso relatório:

## Antes de entregar, verifique
- A tabela inclui todos os gestores da exportação; não ficou ninguém de fora.
- O total corresponde à soma do CSV até ao último cêntimo.
- Todas as alterações importantes são sustentadas por um valor; se não houver dados de comparação, o relatório diz isso diretamente.
- O ficheiro está guardado em report.md e o caminho foi partilhado com o utilizador.

Que modelo deve escolher para uma skill?#

A coluna da direita sugere tarefas para as primeiras verificações. Não é uma classificação nem o resultado de uma comparação: só poderá identificar o modelo certo para a sua skill depois de a executar e comparar com o resultado de referência.

Os preços da tabela são tarifas da API indicadas nas páginas dos modelos a 20 de setembro de 2026, e não preços das subscrições do ChatGPT. Ao utilizar uma subscrição, o consumo está sujeito aos respetivos limites. Nesta data, o Sol tem uma tarifa promocional de $4/$20 até, pelo menos, 21 de novembro de 2026; o preço normal é $5/$30. Antes de uma execução recorrente de grande dimensão, consulte a página de preços: as promoções da OpenAI mudam.

Execute a mesma skill no modelo seguinte, menos dispendioso, e compare o resultado com o de referência. Se a qualidade se mantiver, experimente o modelo seguinte, ainda menos dispendioso. Se a qualidade baixar, volte ao anterior. Os modelos também têm níveis de esforço: o Astra vai de low a max e a família 5.6 vai de none a max. Teste-os também com a mesma referência: primeiro escolha o modelo e depois o nível de esforço.

A utilização regular de uma skill implica custos recorrentes. O preço de entrada do Astra é 50 vezes superior ao do Luna, pelo que utilizar modelos diferentes para a mesma skill recorrente pode resultar em custos bastante diferentes. Para uma skill que analise capturas de ecrã e documentos, um modelo mais fraco pode custar mais devido ao retrabalho.

Erros comuns ao criar e utilizar uma skill#

• Uma skill «para tudo». Um processo, uma skill — esta é também a recomendação da OpenAI. É difícil descrever com precisão uma skill universal de dez páginas, e o Codex seleciona uma skill para uma tarefa com base na respetiva descrição.
• Uma descrição vaga. «Ajuda com relatórios» não deixa claro para que tipo de relatórios serve a skill. No início de description, indique a tarefa e as formas habituais de a formular.
• Instruções sem um resultado definido. Se não especificar o que deve ser produzido e onde o colocar, os resultados podem variar de execução para execução.
• Nenhuma verificação. Sem uma etapa final com critérios, o resultado pode ser um rascunho inacabado que terá de rever integralmente por si.
• O modelo mais capaz por predefinição. Verifique primeiro se um modelo menos dispendioso consegue executar a tarefa: execute a mesma skill e compare o resultado com o de referência. Só mude se a qualidade se mantiver.
• Os mesmos nomes em pastas diferentes. O Codex não combina skills com o mesmo nome, o que dificulta a escolha da skill certa.

Como começar e transferir uma skill para o Claude Code#

Se trabalhar com vários agentes, pode transferir para o Claude Code uma pasta que contenha apenas instruções em texto e um ficheiro SKILL.md. Aí, as skills são guardadas em .claude/skills e invocadas com /name. Verifique uma skill depois de a transferir se incluir scripts, dependências ou agents/openai.yaml. Para um guia da biblioteca de skills do Claude Code, consulte Skills do Claude Code: como criar o seu próprio conjunto; para uma comparação entre o Codex e o Claude Code, consulte Codex vs Claude Code.

Abrir o Ailoot.