Agent Skills: Empacote um conjunto de tarefas e ensine o Codex a executá-las

📚 Navegação da série: O artigo anterior 21 · Subagents tratou de "dividir uma tarefa pesada e delegar para um assistente com contexto independente executá-la, recebendo o resultado de volta". Este artigo muda de perspectiva: em vez de dividir tarefas, o foco é encapsular capacidades — empacote um fluxo fixo que você repete diversas vezes em Agent Skills, e deixe o Codex chamá-los automaticamente quando necessário. O próximo artigo 23 · Plugins explica como empacotar e distribuir essas habilidades para outros instalarem.

Dei uma olhada no repositório oficial da OpenAI em github.com/openai/skills.

Dentro, uma Skill tem um esqueleto tão enxuto que precisa de apenas um arquivo SKILL.md para funcionar — duas linhas horizontais enquadram um bloco de metadados, e abaixo estão algumas linhas de instruções de "como fazer", pronto. Mesmo assim, esse diretório modesto tem um posicionamento oficial como "o formato de autoria para fluxos de trabalho reutilizáveis" (the authoring format for reusable workflows): você escreve um conjunto de tarefas nele, e depois o Codex pode chamá-lo quando necessário, sem você precisar reescrever as etapas a cada vez.

Muitas pessoas ao ouvirem "Skill" pela primeira vez reagem com "isso não é apenas um comando com barra com outra embalagem? O /review que aprendi no artigo 12 também roda com um clique". Sendo honesto, essa compreensão está uma camada aquém. Comandos com barra exigem que você os chame ativamente; Skills não precisam — o Codex vê que sua tarefa corresponde à descrição de uma Skill e a chama automaticamente, enquanto raramente ocupa seu contexto.

Neste artigo, vou explicar completamente o que são Skills, por que podem armazenar muito sem estourar o contexto, onde ficam, como são ativadas e como escrever as suas. Os fatos são sempre baseados na documentação oficial do Codex — alguns tutoriais mais antigos têm o caminho do diretório, nomes de campos das Skills errados, e vou apontar especificamente onde não tropeçar.

Ao terminar este artigo, você terá:

• O que são Skills — um SKILL.md com scripts e recursos opcionais, como isso vira uma habilidade do Codex
• O segredo de "divulgação progressiva": por que normalmente ocupa apenas uma frase de descrição e só expande o conteúdo completo quando usado, economizando contexto
• A diferença entre os dois modos de ativação (explícita com $ / implícita por correspondência de descrição) e como escrever descrições que correspondam com precisão
• Onde colocar Skills (o sistema .agents/skills, não ~/.codex/skills), e o que acontece em caso de nome duplicado
• Como usar $skill-creator para gerar uma em três a cinco frases, como usar $skill-installer para instalar existentes, e como desabilitar alguma

---

01 Entendendo o que é uma Skill

Conclusão direta: uma Skill é essencialmente um diretório com um arquivo SKILL.md, mais scripts e referências opcionais, empacotada como uma "habilidade especializada" para o Codex. Nas palavras oficiais — "uma Skill é um diretório com um arquivo SKILL.md mais scripts e materiais de referência opcionais".

Por que precisamos disso? Porque ao trabalhar com o Codex, há sempre alguns fluxos que você repete diversas vezes. Por exemplo, toda vez que peço ao Codex para commitar código, preciso lembrar "rode os testes primeiro, mensagem de commit em português, prefixo seguindo feat:/fix:" — a mesma instrução, estimei que digitei mais de trinta vezes no ano passado. Esse tipo de repetição de "nível de manual de instruções" é o que uma Skill deve assumir.

Analogia: "manual de montagem" do LEGO. Quando você compra uma caixa de LEGO, o manual dentro não monta por você, mas mostra passo a passo "primeiro monte a base, depois coloque as quatro rodas, finalmente encaixe o teto". Seguindo o manual, qualquer um consegue montar da mesma forma. Uma Skill é esse manual que você escreve para o Codex: escreva um conjunto de etapas fixas ("resumir alterações não commitadas e destacar riscos") em SKILL.md, e este fluxo se torna uma ação que o Codex pode executar de memória sem você precisar redesenhar o manual a cada vez.

Como é um SKILL.md? O esqueleto mínimo tem apenas duas partes — o template da documentação oficial é assim:

---
name: skill-name
description: Explique claramente quando esta skill deve ser ativada e quando não deve.
---

Instruções da skill para o Codex seguir ficam aqui.

A parte entre --- chama-se YAML frontmatter (metadados iniciais, a área de configuração entre os dois --- no início do arquivo), e a documentação oficial exige que contenha obrigatoriamente os campos name e description: name é o nome desta habilidade (também o nome que você usa ao chamá-la com $), e description informa ao Codex para que serve esta Skill e quando deve ser usada. O corpo em markdown abaixo são as instruções que o Codex segue quando realmente a usa.

⚠️ Aqui está o erro que iniciantes mais cometem por causa de tutoriais antigos: alguns materiais não oficiais escrevem um campo trigger: no frontmatter (dizendo ser "palavras-chave de ativação"), e colocam a Skill em ~/.codex/skills/. A documentação oficial não tem o campo trigger — a ativação é por correspondência semântica da description (detalhes abaixo); o diretório também não é ~/.codex/skills, mas sim o sistema .agents/skills (seção 04). Seguir tutoriais antigos resulta em Skills que não funcionam, ou que você não consegue chamar de jeito nenhum. Sempre siga a documentação oficial.

Uma Skill não é apenas o arquivo SKILL.md — é um diretório. Além do SKILL.md obrigatório, pode conter scripts e materiais de referência:

my-skill/
├── SKILL.md          # Instruções principais (obrigatório, contém name + description)
├── scripts/          # Opcional: scripts executáveis (use quando precisar de comportamento determinístico ou chamar ferramentas externas)
└── references/       # Opcional: documentação de referência, consultada pelo Codex conforme necessário durante a execução

Apenas SKILL.md é obrigatório, o restante é opcional. Isso também leva a uma consideração prática da documentação oficial — se as instruções em linguagem natural são suficientes, não escreva scripts; apenas quando você precisar de "comportamento determinístico" ou chamar ferramentas externas. Em outras palavras: deixar o Codex seguir etapas em linguagem natural é mais flexível do que injetar scripts; apenas para aquelas situações de "este passo deve ser executado com precisão milimétrica" ou "precisa chamar uma ferramenta de linha de comando" vale a pena incluir scripts.

Três cenários reais onde você imediatamente consegue imaginar o que a Skill pode fazer:

• Toda vez que você pede ao Codex para commitar código, precisa lembrar "rode testes primeiro, commit em português, prefixo por convenção" — escreva em uma Skill commit, e resolva com uma frase da próxima vez.
• Sua equipe definiu um padrão de escrita de API (nomenclatura RESTful, formato de erro unificado, validação de parâmetros obrigatória) — escreva como Skill api-conventions, e ela seguirá automaticamente ao escrever endpoints.
• Você tem uma "checklist de pré-lançamento" fixa (atualizar changelog, criar tag, rodar testes de fumaça) — escreva como Skill, e no dia do lançamento inicie o fluxo com uma frase.

💡 Resumo em uma frase: Skill é "diretório com SKILL.md (name + description + como fazer) + scripts / referências opcionais" empacotado como uma habilidade — escreva uma vez, o Codex pode chamar quando necessário; se as instruções em linguagem natural são suficientes, não se apresse em escrever scripts.

---

02 O segredo: divulgação progressiva, economizando contexto

Esta é a seção mais importante do artigo. Por que você pode adicionar muitas Skills sem estourar seu contexto? A resposta é uma palavra: divulgação progressiva (progressive disclosure, que significa "expandir gradualmente conforme necessário" — não carregar o conteúdo completo quando não relevante).

Primeiro, por que isso importa. Lembre-se da janela de contexto mencionada no artigo 02 — a "área de trabalho" do Codex tem um tamanho fixo; cada palavra colocada ali gasta orçamento e espreme o espaço de raciocínio. Se o conteúdo completo de cada Skill fosse carregado no início de cada sessão, adicionar oito ou dez Skills inutilizaria metade da sua área de trabalho.

Analogia: "placas de cardápio" e cozinha no restaurante self-service. Você caminha pelo balcão de pratos, e cada prato tem apenas uma plaquinha na frente — nome do prato mais uma frase ("Mapo Tofu · Levemente Apimentado"). Você vê o que tem com uma olhada, mas a panela e os ingredientes por trás da plaquinha você não tem acesso enquanto não pedir aquele prato. Quando você pega o Mapo Tofu, as instruções detalhadas de preparo "aparecem" naquele lado. É exatamente assim que as Skills funcionam — a documentação oficial descreve claramente estas duas fases:

Quando o Codex inicia, ele carrega apenas o nome, a descrição e o caminho do arquivo de cada skill. Apenas quando decide usar uma skill específica, carrega as instruções completas do SKILL.md dessa skill.

Em linguagem simples:

• Normalmente: cada Skill no contexto ocupa apenas "nome + uma frase de descrição + caminho do arquivo" (a plaquinha do cardápio).
• Quando selecionada: o Codex determina que uma Skill corresponde à tarefa atual, e apenas então carrega o conteúdo completo do SKILL.md dessa Skill (as instruções detalhadas do prato escolhido).

É por isso que você pode escrever longas checklists de verificação e referências detalhadas no corpo da Skill — antes de ser usada, praticamente não tem custo.

Duas colunas lado a lado: à esquerda fase 1, onde cada Skill ocupa apenas "nome + uma frase de descrição + caminho do arquivo" no início; à direita fase 2, onde apenas a Skill correspondente à tarefa tem seu SKILL.md completo expandido e carregado, as demais continuam ocupando apenas uma linha.

Porém, esta "lista inicial" não é ilimitada — a documentação oficial dá a ela um orçamento de caracteres, e muitas pessoas não sabem disso:

Para não ocupar muito espaço do restante do prompt, esta lista inicial é limitada a aproximadamente 2% da janela de contexto do modelo, ou 8.000 caracteres quando a janela de contexto é desconhecida. Se muitas skills estiverem instaladas, o Codex primeiro encurtará as descrições; para conjuntos de skills muito grandes, algumas skills podem ser omitidas da lista inicial e o Codex emitirá um aviso.

Note que este orçamento apenas afeta a lista inicial — depois que o Codex seleciona uma Skill, ainda carrega seu SKILL.md completo. Esta regra tem uma implicação prática importante: coloque os casos de uso principais e palavras-chave de ativação no início da sua description. Se a lista inicial for comprimida por ter muitas Skills, as palavras-chave iniciais ainda serão preservadas para correspondência precisa; se as palavras-chave estiverem no final da descrição, serão cortadas durante a compressão — o mesmo problema do artigo 11 com AGENTS.md de "colocar a única regra importante na linha 140": informações importantes devem vir primeiro.

💡 Resumo em uma frase: divulgação progressiva = normalmente apenas expõe "nome + uma frase de descrição", expandindo o SKILL.md completo apenas quando usado, portanto adicionar muitos não estourará o contexto; mas a lista inicial tem orçamento de caracteres (~2% ou 8.000 caracteres), a descrição deve colocar palavras-chave de ativação principais no início para evitar que sejam cortadas durante compressão.

---

03 Dois modos de ativação: chamar explicitamente por nome vs correspondência automática implícita

Sabendo como as Skills economizam contexto, como elas são "chamadas"? A documentação oficial oferece dois caminhos, e entender a diferença entre eles é fundamental para usar Skills bem.

Analogia: duas formas de pedir delivery. Uma é você pedir um restaurante específico — "quero o restaurante de frango ali embaixo", e o app entrega direto sem precisar adivinhar. A outra é você só descrever a necessidade — "algo acompanhante, apimentado" e o app busca o mais adequado. Os dois modos de ativação das Skills correspondem exatamente a essas duas formas.

Ativação explícita: você chama pelo nome

O primeiro modo é ativação explícita — você aponta diretamente esta Skill no seu prompt. A operação oficial: no CLI ou IDE, execute o comando /skills, ou digitando $ para mencionar uma skill.

$commit

Digitar $ abre uma lista de Skills disponíveis para seleção; selecionar (ou digitar o nome completo) é apontar e pedir que ela tome conta. Na ativação explícita, o Codex não faz nenhum julgamento de correspondência — carrega diretamente o SKILL.md completo e segue — você disse qual, é aquela.

⚠️ Outro erro de tutoriais antigos: alguns materiais escrevem que ativação explícita é @skill-name. A sintaxe oficial é $ (junto com /skills), não @. Não confunda.

Ativação implícita: ela corresponde automaticamente pela descrição

O segundo modo é ativação implícita — você não menciona o nome da Skill, fala naturalmente, e o Codex compara sua mensagem com a description de cada Skill, ativando automaticamente a que corresponder. Nas palavras oficiais: "Quando sua tarefa corresponde à descrição de uma skill, o Codex pode selecionar aquela skill automaticamente."

Este é o aspecto mais confortável das Skills: você não precisa lembrar $isso e $aquilo — se a descrição estiver bem escrita, basta descrever a necessidade e ela será atendida automaticamente. Mas isso também coloca tudo na description — a documentação é direta:

Como a correspondência implícita depende da description, escreva descrições concisas, com escopo claro e limites bem definidos. Coloque casos de uso principais e palavras-chave de ativação no início, para que o Codex ainda consiga corresponder à skill mesmo que a descrição seja encurtada.

Aprendi isso na prática ao escrever minha primeira Skill: escrevi a descrição como "ajuda com tarefas relacionadas a código" — muito genérica — e ela ora tentava corresponder em tudo, ora não aparecia quando deveria. Depois mudei para "resume alterações não commitadas e destaca riscos. Use quando o usuário disser 'o que mudou', 'quero uma mensagem de commit', 'me ajuda a ver o diff'" — colocando as frases que os usuários realmente dizem diretamente, e a correspondência ficou imediatamente precisa. description não é uma sinopse para humanos, é um gancho para o algoritmo de correspondência.

Comparação dos dois modos:

Dimensão	Ativação explícita ($ / /skills)	Ativação implícita (por correspondência de descrição)
Como ativar	Você digita $ e aponta pelo nome, ou executa /skills para selecionar	Fala naturalmente, o Codex corresponde sozinho
Codex faz julgamento?	Não — aponte e use	Sim — compara sua mensagem com a description
Precisão depende de	Se você apontou corretamente	Se a description está bem escrita
Melhor para	Quando você quer controle preciso sobre qual usar e quando	Deixar o Codex "usar quando necessário" sem precisar lembrar os nomes
Pode desativar?	Não pode (apontar sempre funciona)	Pode (veja allow_implicit_invocation na seção 05)

💡 Resumo em uma frase: ativação explícita via $ ou /skills é a mais segura; ativação implícita por correspondência de descrição é a mais conveniente — e a precisão da implícita depende inteiramente da description — escreva palavras-chave de ativação como "frases que o usuário realmente vai dizer" e coloque-as primeiro.

---

04 Onde colocar determina quem pode usar: o sistema de diretórios .agents/skills

Sabendo o que é e como ativar, onde colocar a Skill que você escreveu? Esta seção é o lugar mais fácil de ser induzido ao erro por tutoriais antigos — copie da tabela oficial, não vá de memória.

A documentação oficial diz que o Codex lê skills de quatro níveis: repository (REPO), user (USER), admin (ADMIN) e system (SYSTEM). O nível de repositório tem uma particularidade: o Codex varre do diretório atual até a raiz do repositório, lendo .agents/skills em cada nível ao longo do caminho. A tabela completa de locais:

Escopo	Onde colocar	Quem / onde pode usar
REPO (diretório atual)	$CWD/.agents/skills	O diretório onde você iniciou o Codex — ideal para skills específicas de um módulo / microsserviço
REPO (diretório acima)	$CWD/../.agents/skills	Um nível acima do diretório atual — ideal para uma área compartilhada em estruturas aninhadas
REPO (raiz do repositório)	$REPO_ROOT/.agents/skills	Topo do repositório — skills básicas que todos os subdiretórios do repositório podem usar
USER (pessoal)	$HOME/.agents/skills	Este usuário pode usar em qualquer repositório
ADMIN (nível de máquina)	/etc/codex/skills	Compartilhado por todos os usuários nesta máquina / container (scripts SDK, automação, skills padrão de administrador)
SYSTEM (integrado)	Incluído com o Codex pela OpenAI	Todos têm ao iniciar o Codex (como skill-creator, skills de plano)

⚠️ Ponto crítico para não tropeçar: o diretório de skills do Codex é .agents/skills (nível de repositório) e $HOME/.agents/skills (nível de usuário), não ~/.codex/skills/. ~/.codex/ é onde ficam config.toml e outros arquivos de configuração (que você usará na seção 05) — não crie a pasta de skills lá. Criando errado, o Codex não encontra, e você vai achar que a Skill está quebrada. Isso também é diferente do sistema de descoberta de AGENTS.md do artigo 11 — não confunda os dois.

A lógica é bastante intuitiva: skills de uso pessoal que você quer em qualquer projeto (como seus hábitos pessoais de commit), coloque no nível de usuário $HOME/.agents/skills; skills específicas do repositório que você quer que toda a equipe use (como o fluxo de lançamento deste projeto), coloque no nível de repositório .agents/skills e comite — quando os colegas fizerem pull, terão automaticamente. No Mac / Linux $HOME é o seu diretório home; usuários Windows, a documentação oficial usa convenções tipo Unix — use o caminho que o Codex realmente lê na sua máquina.

E se duas Skills tiverem o mesmo nome? A documentação é clara — o Codex não as mescla; as duas aparecem no seletor de skills. Diferente de AGENTS.md do artigo 11, que usa "a mais próxima prevalece" — Skills com nomes duplicados coexistem, ambas listadas para você escolher. Portanto, a documentação recomenda: não use o mesmo nome de skill em escopos diferentes para evitar confusão ao escolher.

Há também um detalhe conveniente: o Codex detecta automaticamente alterações nos arquivos de skills — modificar um SKILL.md geralmente entra em vigor imediatamente. Se após modificar nada acontecer, a dica oficial é apenas uma: reinicie o Codex.

💡 Resumo em uma frase: skills ficam em .agents/skills (nível de repositório, varrendo do diretório atual até a raiz) ou $HOME/.agents/skills (nível de usuário), não em ~/.codex/skills; nomes duplicados não são mesclados, ambos aparecem listados — portanto não use o mesmo nome entre escopos; modificações geralmente entram em vigor automaticamente, caso contrário reinicie.

---

05 Prática: gerar com $skill-creator, instalar com $skill-installer, desabilitar conforme necessário

Apenas entender a teoria não é suficiente — esta seção cobre as três coisas mais práticas: como criar rapidamente uma Skill, como instalar uma pronta e como desligar temporariamente alguma.

Criar: use o criador integrado $skill-creator primeiro

A recomendação da documentação oficial é direta — use o criador integrado primeiro, não comece do zero. No CLI ou IDE, digite:

$skill-creator

Ele fará um breve questionário — a documentação diz que são apenas três perguntas: o que esta skill faz? quando deve ser ativada? apenas instruções são suficientes ou precisa de scripts? (A última recomenda instruções puras por padrão — simples e fácil de manter — ecoando a regra da seção 01 "se as instruções são suficientes, não escreva scripts".) Após responder, ele gera a estrutura do diretório e o SKILL.md para você. Este é meu ponto de partida padrão ao escrever novas Skills: deixar ele criar o esqueleto, depois eu ajusto os detalhes — muito mais eficiente do que digitar um SKILL.md do zero seguindo a documentação.

Claro, você também pode criar manualmente — seguindo o template da seção 01, crie um diretório e escreva um SKILL.md com name + description, é essencialmente a mesma coisa que o criador produz.

Instalar: usar $skill-installer para puxar skills prontas

Não quer escrever você mesmo e prefere usar as de outros? A documentação oficial oferece $skill-installer para instalar skills selecionadas além das integradas. Por exemplo, instalar a skill do Linear (uma ferramenta de gerenciamento de projetos):

$skill-installer linear

Você também pode fazer o instalador baixar skills de outros repositórios. Após a instalação, o Codex geralmente detecta automaticamente; se não aparecer, reinicie.

ℹ️ O posicionamento oficial do $skill-installer é "experimentação e testes locais". Se você quer distribuir seriamente suas próprias skills para outros, ou empacotar várias skills juntas, a documentação oficial recomenda usar Plugins (plugins) — exatamente o tema do próximo artigo [23 · Plugins]. Uma frase para memorizar: Skill é o "formato de autoria", Plugin é o "formato de distribuição"; projete o fluxo de trabalho com Skill primeiro, depois empacote como plugin quando quiser distribuir para outros.

Desabilitar: não exclua o arquivo, apenas desligue

Uma skill (talvez instalada, talvez integrada ao sistema) que você temporariamente não quer que apareça sem querer excluir — como fazer? A solução da documentação oficial é adicionar uma seção em ~/.codex/config.toml (o arquivo de configuração no nível de usuário do Codex, note que é .codex não .agents):

# Caminho do arquivo: ~/.codex/config.toml
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

Coloque o caminho real do SKILL.md dessa skill em path, e enabled = false a desativa. Lembre de reiniciar o Codex após modificar config.toml para entrar em vigor. Isso é especialmente útil quando "você instalou muitas skills e o orçamento de caracteres da lista inicial estourou" — como a seção 02 mencionou, o orçamento é limitado; desativar temporariamente as skills não utilizadas no momento libera espaço para as frequentemente usadas.

Avançado: desativar ativação implícita (agents/openai.yaml)

Se você quer configurar atributos avançados para uma Skill — como nome de exibição / ícone no Codex App, declarar ferramentas dependentes, ou desativar sua ativação implícita — a documentação oficial suporta colocar um agents/openai.yaml no diretório da skill. O item mais comum é este:

# Caminho do arquivo: <diretório da skill>/agents/openai.yaml
policy:
  allow_implicit_invocation: false

allow_implicit_invocation é true por padrão (ou seja, por padrão permite correspondência implícita); definir como false faz com que o Codex não mais ative implicitamente esta skill com base nos seus prompts, mas ativação explícita via $nome-da-skill ainda funciona. Este é exatamente o interruptor da tabela da seção 03 de "implícita pode ser desligada, explícita não". Quando usar? Por exemplo, uma skill com efeitos colaterais onde você quer controlar o momento pessoalmente (como "publicar em produção") — você definitivamente não quer que o Codex "veja que o código parece pronto" e ative implicitamente por conta própria — dê a ela allow_implicit_invocation: false e bloqueie para ativação apenas via $.

Uma tabela resumindo as ações desta seção e seus "endereços", para não colocar no lugar errado:

O que você quer fazer	Usar o quê	Arquivo / Comando
Criar rapidamente uma nova Skill	$skill-creator	Digite diretamente no CLI / IDE
Instalar Skill pronta de outros	$skill-installer <nome>	Digite diretamente no CLI / IDE
Desabilitar temporariamente uma Skill	[[skills.config]]	~/.codex/config.toml
Desativar ativação implícita de uma Skill	allow_implicit_invocation: false	agents/openai.yaml no diretório da skill
Colocar arquivos da Skill que você escreveu	Crie diretório + SKILL.md	.agents/skills ou $HOME/.agents/skills

💡 Resumo em uma frase: criar usa $skill-creator (padrão instruções puras), instalar usa $skill-installer, desabilitar escreve [[skills.config]] em ~/.codex/config.toml, desativar implícita coloca agents/openai.yaml com allow_implicit_invocation: false — cuidado: configuração em .codex, arquivos de skill em .agents — não misture os dois diretórios.

---

06 Prática: criar uma Skill em 3 minutos e vê-la "ser chamada sozinha"

Apenas ler sem praticar não cria memória. Este conjunto de operações mínimas, sem escrever nenhum script, te faz ver pessoalmente duas coisas: como uma Skill é ativada implicitamente por uma frase natural e como usar $ para chamar explicitamente. Funciona em qualquer diretório vazio.

Diferença de plataforma: os comandos mkdir abaixo funcionam diretamente no Mac / Linux; no Windows PowerShell substitua mkdir -p por mkdir, ou crie as pastas manualmente no explorador de arquivos. ~ refere-se ao diretório home do usuário, no Windows corresponde a C:\Users\seu-nome\. Se ainda não instalou o Codex, volte ao artigo 03 primeiro. Todos os comandos e diretórios desta seção seguem a documentação oficial; algumas interfaces interativas podem variar com as versões — use o que seu ambiente local realmente mostra.

Passo 1: criar o diretório de skills no nível de usuário

mkdir -p ~/.agents/skills/explain-self

Esperado: um diretório vazio explain-self criado sob ~/.agents/skills/. Note que é .agents não .codex — este é exatamente o erro que a seção 04 enfatizou repetidamente; criar corretamente uma vez é a melhor memória.

Passo 2: escrever um SKILL.md mínimo

No seu editor favorito, salve o conteúdo abaixo em ~/.agents/skills/explain-self/SKILL.md:

---
name: explain-self
description: Explica um trecho de código ou mensagem de erro em linguagem simples. Use quando o usuário disser "o que este código faz", "o que é esse erro", "me ajuda a ler isso".
---

Explique o código ou erro dado pelo usuário em linguagem simples que um iniciante entenderia:

1. O que esta coisa faz no geral (em uma frase)
2. Explicação linha por linha / parte por parte
3. Se for um erro, identifique a causa mais provável e como corrigir

Evite acumular jargões técnicos — use analogias com a vida real quando possível.

Note que a description desta Skill tem especificamente frases como "o que este código faz", "o que é esse erro" — frases que você realmente vai dizer — este é o "gancho de correspondência implícita" da seção 03.

Esperado: o diretório explain-self tem um SKILL.md.

Passo 3: iniciar o Codex e confirmar que ele reconhece esta Skill

codex

Após entrar, execute:

/skills

Esperado: o seletor de skills exibe explain-self com a descrição que você escreveu. Vê-la na lista = Skill foi descoberta corretamente. Este passo também demonstra a divulgação progressiva: o contexto atual tem apenas uma frase de descrição + nome + caminho desta Skill — as instruções não foram carregadas ainda.

Passo 4: sem chamar pelo nome, ative-a implicitamente com "linguagem natural"

Deliberadamente não digite $explain-self, mas sim uma frase que corresponda à descrição:

O que este código faz: print(sum([1,2,3]) / len([1,2,3]))

Esperado: o Codex corresponde implicitamente à Skill explain-self (você nem mencionou seu nome — ela correspondeu sozinha com base na descrição), depois segue as suas três etapas — primeiro diz o que faz no geral (calcula a média dos três números, resultado 2.0), depois explica parte por parte, usando poucos termos técnicos. Ela foi chamada sem você pedir — este é exatamente o funcionamento da ativação implícita.

Passo 5: comparar com chamada explícita via $

Experimente uma vez com ativação explícita — digite $ para chamá-la:

$explain-self o que é esse erro: ZeroDivisionError: division by zero

Esperado: mesma Skill é ativada, com o mesmo efeito da quarta etapa — a diferença é que desta vez você chamou explicitamente pelo nome, o Codex não faz julgamento de correspondência e aceita diretamente. Os dois caminhos levam à mesma habilidade, confirmando exatamente a tabela da seção 03.

Completando esses cinco passos, você verificou pessoalmente as coisas mais essenciais das Skills — colocar no diretório correto (.agents não .codex), ativação implícita por correspondência de descrição, chamada explícita com $, normalmente ocupa apenas uma linha de descrição — muito mais eficaz do que memorizar dez itens da documentação.

💡 Resumo em uma frase: escreva uma skill mínima em ~/.agents/skills/explain-self/SKILL.md, confirme a descoberta com /skills, depois acione com "linguagem natural" e com $nome — ver pessoalmente como implícita e explícita levam à mesma habilidade, e evitar o erro mais comum de "criar diretório em .codex".

---

07 Resumo

Este artigo cobriu as Agent Skills de "o que são" até "como começar" — elas fazem o Codex deixar de ser uma folha em branco e se tornar um profissional com habilidades especializadas que pode ser chamado conforme necessário.

Revisão dos pontos-chave:

Tópico	Resposta	Ponto-chave
O que é uma Skill	Diretório com SKILL.md + scripts / referências opcionais	Frontmatter deve ter name + description
Por que não estoura o contexto	Divulgação progressiva	Normalmente expõe apenas nome + descrição, expande o conteúdo completo quando usado; lista inicial tem orçamento de ~2% / 8.000 caracteres
Como ativar	Explícita / Implícita (dois modos)	$ ou /skills para apontar; ou correspondência automática via description
Onde colocar	Sistema .agents/skills	Nível de repositório / nível de usuário $HOME/.agents/skills, não ~/.codex/skills
Como começar	Criar / Instalar / Desabilitar	$skill-creator, $skill-installer, [[skills.config]]

Você agora deve ser capaz de: explicar do que uma Skill é feita e o princípio de "divulgação progressiva" que economiza contexto; distinguir entre ativação explícita via $ e correspondência implícita por descrição, sabendo que a precisão da implícita depende inteiramente da description; lembrar que skills ficam em .agents/skills (não em ~/.codex/skills) e que nomes duplicados ficam listados separadamente sem mesclar; e saber como criar com $skill-creator em três a cinco frases e desabilitar temporariamente com [[skills.config]]. Essa habilidade de "empacotar tarefas repetitivas em capacidades" é um passo fundamental para transformar o Codex de "assistente de propósito geral" em "especialista que entende o seu fluxo de trabalho".

Três erros mais comuns para reforçar antes de terminar: o diretório é .agents não .codex, o campo não é trigger, a chamada explícita é $ não @ — se qualquer um desses difere dos tutoriais que você leu, siga a documentação oficial.

---

O próximo artigo 23 · Plugins — neste artigo você aprendeu a empacotar um conjunto de tarefas em uma Skill, mas por padrão ela só está na sua própria máquina, no seu próprio repositório. E se você quisesse empacotar isso e deixar colegas ou a comunidade instalarem com um clique? A resposta oficial é Plugins — "Skill é o formato de autoria, Plugin é o formato de distribuição". O próximo artigo explica como reunir uma ou mais Skills com configurações e empacotá-las como um plugin para distribuição. Pequena reflexão: a explain-self que você escreveu neste artigo — para toda a equipe usar, basta commitar no repositório, ou ainda falta um passo?

---

Leitura recomendada

• Quatro tipos de fluxo de trabalho diário: exploração, correção de bugs, refatoração, escrita de testes
• Extensões IDE (VS Code etc.)
• Plugins: instale um conjunto completo de capacidades com um clique