# Skills do Codex: como criar uma skill para tarefas repetitivas > Estrutura do SKILL.md, caminhos de carregamento, invocação explícita e automática, critérios de resultado e transferência de uma skill para o Claude Code. Source: https://ailoot.ai/blog/pt-pt/codex-skills/ Canonical: https://ailoot.ai/blog/pt-pt/codex-skills/ Language: pt-PT Publisher: Ailoot (https://ailoot.ai/) Translation: guide-084 Revision: sha256-30b205f2773fc753d53132c99a0ba3313c2359219952320e7b8df93786056fd3 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](https://ailoot.ai/blog/pt-pt/openai-codex-install/). [Encontra informações práticas sobre a utilização do Ailoot na documentação](https://ailoot.ai/docs/). ## O que é uma skill no Codex?
Ideia principal Uma skill do Codex é uma pasta com um ficheiro `SKILL.md` que descreve um processo: o que fazer, em que se basear e como é um bom resultado. Inicialmente, o Codex mantém no contexto apenas os nomes e as descrições das skills e carrega as instruções completas quando decide utilizar uma.
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](https://ailoot.ai/blog/pt-pt/hermes-agent-skills/). Este artigo é apenas sobre o Codex. ## Em que consiste uma skill?
Ideia principal No mínimo, uma skill tem um ficheiro `SKILL.md` com dois campos obrigatórios: `name` e `description`. Opcionalmente, pode acrescentar as pastas `scripts/`, `references/` e `assets/`, bem como um ficheiro `agents/openai.yaml` com definições.
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: ```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?
Ideia principal O Codex procura skills em quatro níveis: na pasta `.agents/skills` do projeto (verificando a pasta atual e cada pasta superior até à raiz do repositório), na pasta pessoal `$HOME/.agents/skills`, na pasta do sistema `/etc/codex/skills` e entre as skills integradas da OpenAI.
| Nível | Caminho | Finalidade | |----|----|----| | Projeto | `.agents/skills` na pasta atual e nas pastas superiores até à raiz do repositório | Skills para um projeto específico, que podem ser guardadas no git juntamente com o código | | Utilizador | `$HOME/.agents/skills` | Skills pessoais, disponíveis em todos os projetos da máquina | | Sistema | `/etc/codex/skills` | Skills partilhadas por todos os utilizadores da máquina ou do contentor | | Integradas | Incluídas no Codex | Skills básicas da OpenAI, como o criador de 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](https://ailoot.ai/blog/pt-pt/skills-subagents-mcp-plugins-claude-code/). ## Como decide o Codex que skill deve invocar?
Ideia principal Pode invocar uma skill explicitamente: na CLI ou na extensão IDE do Codex, introduza `$skill-name` no pedido ou selecione-a através de `/skills`. Na invocação implícita, o Codex seleciona automaticamente uma skill se a sua tarefa corresponder à descrição. A skill tem de estar disponível e a invocação automática tem de ser permitida.
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`: ```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
Ideia principal Escolha uma tarefa repetitiva, crie uma skill com o assistente integrado `$skill-creator` ou manualmente, escreva instruções com um resultado claramente especificado, teste a invocação com uma formulação normal e refine a skill após cada execução.
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
Ideia principal Inclua os critérios de aceitação diretamente na skill: o que o resultado tem de conter e como o agente deve verificar o seu trabalho antes de o entregar. Isto não garante que esteja correto; continua a ter de verificar o resultado por si.
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: ```markdown ## 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?
Ideia principal Comece pelo modelo em que a skill funcionou e, em seguida, experimente modelos menos dispendiosos: se a qualidade se mantiver, fique com o mais barato. Seguem-se os preços da API e as opções iniciais para as primeiras execuções, a 20 de setembro de 2026.
| Modelo | Entrada, $/milhão de tokens | Saída, $/milhão de tokens | Em que experimentar primeiro | |----|----|----|----| | GPT-6 Astra | 10 | 50 | Skills que envolvem raciocínio prolongado, imagens e utilização do browser | | GPT-5.6 Sol | 4 | 20 | Skills de texto de complexidade média | | GPT-5.6 Terra | 2.50 | 15 | Processos simples com um resultado claro | | GPT-5.6 Luna | 0.20 | 1.20 | Tarefas mecânicas: reformatar, calcular, compilar uma lista | 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
Ideia principal Escolha um processo repetitivo, crie uma skill com `$skill-creator`, teste a invocação com as suas próprias palavras e acrescente uma etapa final com critérios de aceitação. Após algumas execuções, refine a descrição e as instruções com base nos erros que encontrar.
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](https://ailoot.ai/blog/pt-pt/claude-code-skills-library/); para uma comparação entre o Codex e o Claude Code, consulte [Codex vs Claude Code](https://ailoot.ai/blog/pt-pt/codex-vs-claude-code-choice/).
### Fontes - [OpenAI Developers: criar skills — documentação do Codex](https://developers.openai.com/codex/skills) - [OpenAI Developers: visão geral do Codex](https://developers.openai.com/codex/) - [OpenAI Platform: modelos e tarifas da API](https://platform.openai.com/docs/models) - [Agent Skills: norma aberta e especificação](https://agentskills.io) - [Documentação da Anthropic: expandir o Claude com skills](https://docs.claude.com/en/docs/claude-code/skills) - [Anthropic Engineering: criar agentes eficazes](https://www.anthropic.com/engineering/building-effective-agents) - [OpenAI Developers: criar plugins](https://developers.openai.com/plugins/build/plugins)
[Abrir o Ailoot](https://ailoot.ai/). ## Perguntas frequentes ### Porque funciona a invocação explícita, mas falha a seleção automática da skill? Verifique se a skill aparece em /skills e se a invocação implícita está ativa. Se ambas estiverem corretas, refine a descrição para começar pela tarefa e incluir as palavras que costuma usar; teste depois o mesmo pedido normal. ### O que verifico no resultado de uma skill de relatórios de vendas? Confirme que todos os gestores da exportação estão representados, o total coincide com a origem, cada variação afirmada tem números de suporte e o ficheiro pedido está guardado. Se faltar o período anterior, o relatório deve indicá-lo. ## Ailoot · A empresa e a sua carteira de projetos A Ailoot assenta numa experiência operacional consolidada, numa ampla base de clientes, num serviço estável e no acompanhamento contínuo dos KPI. A empresa e a sua carteira de projetos: milhões de clientes; vendas mensais na ordem dos milhares de milhões. A Ailoot aplica essa experiência operacional ao acesso por API a funcionalidades de IA nos produtos dos clientes, agentes, aplicações e automatizações.