Como criar sua própria skill de agente

Escreva a sua própria skill de agente a partir de uma falha real

A melhor forma de escrever a sua própria skill de agente é extraí-la de uma falha real. Encontre uma tarefa que o seu agente de programação tenha executado incorretamente duas vezes, anote a correção que introduziu nas duas ocasiões e guarde essa correção num ficheiro SKILL.md que o agente possa carregar automaticamente. Depois disso, tudo é mecânico: a estrutura dos ficheiros e a linha que determina se a skill será alguma vez ativada.

Essa ordem é importante. Uma skill escrita por imaginação documenta um problema que nunca teve e continua a consumir contexto em todas as sessões. Uma skill extraída de uma falha que observou já inclui o seu próprio teste: faça o mesmo pedido novamente e verifique se o agente o executa corretamente desta vez. Se o formato ainda lhe for desconhecido, leia primeiro o que são skills de agente e como um agente as carrega e depois volte para escrever uma.

Comece por uma tarefa que o agente executou mal duas vezes

Uma vez pode ser acaso. Duas vezes formam um padrão, e um padrão merece um ficheiro.

Eis uma falha que se repete em servidores reais. Pede ao agente para adicionar um bloco de reverse proxy ao nginx. Ele edita /etc/nginx/conf.d/app.conf e depois executa sudo systemctl restart nginx. A alteração contém um erro de digitação, por isso o nginx recusa arrancar e o site fica indisponível até corrigires o problema:

nginx: [emerg] unknown directive "proxy_pas" in /etc/nginx/conf.d/app.conf:12
Job for nginx.service failed because the control process exited with error code.

Corrige o problema no chat. Testa a configuração com sudo nginx -t antes de tocar no serviço e aplica-a depois com reload em vez de restart. Uma semana mais tarde, noutra tarefa, ocorre o mesmo erro. Essa segunda ocorrência é o sinal.

Regista duas coisas enquanto a falha ainda está visível: o pedido que escreveste e a correção que deste, usando as palavras que empregaste. Essas duas linhas tornam-se a skill. O pedido indica o que o trigger tem de detetar. A correção constitui todo o conteúdo.

As próprias orientações de autoria da Anthropic colocam este processo em primeiro lugar. Executa o agente em tarefas representativas sem uma skill, regista os pontos em que falha e escreve depois as instruções mínimas que corrigem essas falhas. As falhas são a especificação. Por isso, uma skill que não consigas associar a uma delas é normalmente uma skill de que ninguém precisava.

Para veres um exemplo prático da mesma destilação, Ponytail transforma uma falha repetida, um agente que reescreve muito mais do que pediste, numa skill pode ser lido do princípio ao fim antes de escreveres a tua.

A anatomia de uma skill

Uma skill é um diretório que contém um único ficheiro obrigatório.

.claude/skills/nginx-config-changes/
├── SKILL.md
├── reference/
│   └── proxy-headers.md
└── scripts/
    └── check-and-reload.sh

SKILL.md começa com um bloco de frontmatter, com algumas definições escritas em YAML (o mesmo formato de configuração usado pelos ficheiros do Docker Compose) entre os marcadores ---, seguido das instruções em markdown. Esta é a skill completa correspondente à falha anterior.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
---

## Rules

Run `sudo nginx -t` after every edit under `/etc/nginx`. Do not touch the service until it prints `test is successful`.

Apply the change with `sudo systemctl reload nginx`. Never use `restart`. A reload keeps the running workers serving traffic until the new config parses, so a broken config leaves the site up. A restart stops nginx first, so a broken config takes the site down.

If `nginx -t` fails, fix the file and test again. Never reload a config that failed the test.

For the proxy header defaults this project expects, see [reference/proxy-headers.md](reference/proxy-headers.md).

Esse ficheiro tem menos de 20 linhas e é uma skill completa. Componentes:

• name: até 64 caracteres, apenas letras minúsculas, dígitos e hífenes, e não pode conter as palavras claude ou anthropic. Numa skill pessoal ou de projeto, este é apenas o rótulo apresentado. O comando que escreve vem do nome do diretório, por isso esta responde a /nginx-config-changes.
• description: indica o que a skill faz e quando deve ser usada, até 1,024 caracteres. Esta linha é o elemento mais importante, e a secção seguinte trata exclusivamente deste assunto.
• O corpo: as instruções, carregadas apenas quando a skill é realmente acionada.
• reference/: ficheiros adicionais que o agente lê a pedido. Faça referência a eles a partir de SKILL.md e mantenha as referências com apenas um nível de profundidade, porque um ficheiro referenciado a partir de outro ficheiro referenciado muitas vezes é lido apenas parcialmente.
• scripts/: ficheiros que o agente executa em vez de ler. Apenas o resultado deles consome contexto, por isso um script com 300 linhas tem um custo reduzido.

Uma skill evolui para uma estrutura completa quando o comportamento que ela corrige é suficientemente persistente para exigir uma, e a skill unlazy usa esse espaço para uma Depth Tree, um conjunto de ficheiros de gates e um contrato PLAN.md para impedir que um agente anuncie que terminou enquanto ramos inteiros do trabalho continuam por tratar.

O local onde coloca o diretório determina quem tem acesso à skill.

• .claude/skills/<name>/SKILL.md no repositório: apenas este projeto, e a skill é disponibilizada a todos os que clonarem o repositório.
• ~/.claude/skills/<name>/SKILL.md: todos os projetos na sua máquina, e em nenhuma outra.
• <plugin>/skills/<name>/SKILL.md: incluída num plugin, disponível onde quer que esse plugin esteja ativado.

Crie uma com mkdir -p .claude/skills/nginx-config-changes e escreva o ficheiro. O Claude Code monitoriza estes diretórios, por isso editar uma skill existente produz efeitos na sessão em execução. Criar um diretório de skills no nível superior que não existia quando a sessão começou requer um reinício, porque não havia nada para monitorizar no início da sessão.

O campo de descrição é a linha de maior impacto no ficheiro

No arranque, o agente carrega name e description de cada skill disponível para o seu contexto. Não carrega os conteúdos. Quando o pedido chega, essa linha é a única base para decidir se esta skill é relevante. Por isso, um conteúdo perfeito atrás de uma descrição vaga nunca é lido.

Escreva a descrição na terceira pessoa. "Testa e recarrega o nginx com segurança" funciona. "Posso ajudar com o nginx" não funciona, porque o texto é injetado no system prompt, onde a primeira pessoa parece ser o modelo a falar de si próprio.

Inclua duas coisas: o que a skill faz e a condição em que se aplica. Coloque primeiro o caso de utilização mais importante, porque o Claude Code trunca a entrada da lista em 1,536 caracteres. Existe um campo when_to_use opcional para frases de acionamento adicionais e exemplos de pedidos. Esse campo é acrescentado à descrição dentro do mesmo limite.

Depois, use as palavras que realmente vai escrever. description: Helps with nginx não corresponde a nada, porque ninguém escreve "ajuda com". A versão acima inclui /etc/nginx, server block, reverse proxy e TLS (transport layer security) certificate path, que representam aproximadamente o vocabulário de qualquer pedido que deva acioná-la.

Eis o teste para uma descrição. Dê essa única linha a alguém que nunca viu o conteúdo, juntamente com o pedido que pretende escrever, e pergunte se a skill se aplica. Se essa pessoa não conseguir perceber, o modelo também não conseguirá.

Mantenha o corpo pequeno, porque ele permanece no contexto

Quando uma skill é invocada, o conteúdo renderizado entra na conversa como uma mensagem e permanece nela durante o restante da sessão. O Claude Code não volta a ler o ficheiro nos turnos seguintes. Cada linha escrita é um custo para toda a sessão, não apenas para uma resposta.

A Anthropic recomenda manter SKILL.md abaixo de 500 linhas e transferir os detalhes para ficheiros separados. A compactação mostra por que esse número não é arbitrário. Quando a conversa é resumida para libertar contexto, o Claude Code anexa novamente a invocação mais recente de cada skill, mantém apenas os primeiros 5,000 tokens de cada uma e preenche um orçamento combinado de 25,000 tokens, começando pela skill invocada mais recentemente. Uma skill longa é cortada a meio. Várias skills longas podem excluir-se umas às outras por completo.

Escreva apenas o que o modelo ainda não sabe. Ele sabe o que é o nginx e o que faz um reverse proxy. Não sabe a sua regra interna sobre reload acima de restart, e essa regra é a única razão para este ficheiro existir.

Se a skill instruir o agente a executar um script incluído, indique o caminho com ${CLAUDE_SKILL_DIR} para que ele seja resolvido independentemente do local onde a skill está instalada e autorize previamente o mesmo comando para que a execução não pare a pedir confirmação de permissões.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/check-and-reload.sh *)
---

A concessão abrange o turno que invocou a skill e é limpa quando envia a mensagem seguinte. Assim, não se transforma silenciosamente numa permissão permanente.

Como provar que o skill é acionado

Observar o carregamento de um skill confirma que o agente o encontrou. Isso não confirma que a resposta mudou. Verifique ambos os pontos e faça o teste numa sessão nova, porque a sessão onde escreveu o skill já contém tudo o que disse durante a criação. Esse contexto residual oculta as lacunas do ficheiro.

1. Inicie uma sessão nova com claude no projeto.
2. Escreva o pedido como faria num dia normal de trabalho, com as suas próprias palavras e sem mencionar o skill.
3. Observe se ocorre a invocação. Se o skill não for acionado, corrija a descrição. O corpo ainda não é o problema.
4. Invoque-o manualmente com /nginx-config-changes como controlo. Se o comportamento for correto na invocação manual e incorreto quando usa o pedido, isso confirma um problema no acionamento, não nas instruções.
5. Execute o mesmo pedido com o skill desativado e compare as duas respostas. No menu /skills, selecione o skill e prima Space para alternar o estado para off. Em seguida, prima Enter para guardar. Isso escreve uma entrada skillOverrides em .claude/settings.local.json. Ao premir Space novamente, o estado volta a on quando terminar.
6. Escreva alguns pedidos que não devem acionar o skill e confirme que ele permanece inativo.

Para automatizar este ciclo, instale o plugin skill-creator a partir do marketplace oficial.

/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@claude-plugins-official

Se o resultado da instalação indicar Run /reload-plugins to activate., execute esse comando. Em seguida, peça ao Claude para avaliar o seu skill pelo nome. O plugin armazena os casos de teste em evals/evals.json dentro do diretório do skill e executa cada caso no seu próprio subagente. Assim, cada execução começa com um contexto limpo. Depois, escreve uma comparação entre with-skill e without-skill. Esse é o valor correto: a melhoria da taxa de aprovação medida em relação aos tokens e ao tempo consumidos pelo skill.

Um skill também pode incluir a sua própria prova, em vez de a deixar para uma execução de avaliação separada. É isso que o skill Old Coder faz ao pedir ao agente que devolva um relatório de evidências que pode executar novamente.

Modo de falha: a skill nunca é ativada

Você escreve o pedido, o agente executa a ação errada antiga e nenhuma linha da skill aparece. Verifique os pontos seguintes pela ordem.

• A descrição explica o que a skill faz, mas nunca indica quando deve ser usada. Por isso, nada no seu pedido corresponde a ela.
• A descrição evita as palavras que você escreve. Se disser "nginx", a descrição também tem de dizer nginx.
• disable-model-invocation: true está definido no frontmatter. Isso remove a descrição inteiramente do contexto do modelo e deixa a skill invocável apenas por si com /name.
• Um glob paths no frontmatter limita a ativação aos ficheiros correspondentes, mas o ficheiro em que está a trabalhar não corresponde.
• A skill está num diretório .claude/skills/ aninhado abaixo do diretório inicial. Estas skills só são carregadas depois de o agente ler ou editar um ficheiro dentro desse subdiretório. Até lá, a skill não está disponível.

Modo de falha: a skill é acionada constantemente

O problema oposto ocorre quando a descrição é tão ampla que a skill é acionada durante tarefas não relacionadas. "Use when working on the server" corresponde a quase qualquer pedido num repositório de servidor. O corpo é então carregado em tarefas nas quais não pode ajudar e permanece no contexto durante o resto da sessão.

Restrinja a descrição à condição que realmente importa e indique os ficheiros ou comandos abrangidos. Adicione um glob paths quando a skill se aplicar apenas a determinados ficheiros. Para qualquer ação com efeitos secundários, como um deploy ou um commit, defina disable-model-invocation: true e invoque-a manualmente com /name, para que o agente nunca decida por si próprio que é um bom momento para fazer um deploy.

Modo de falha: a competência pertence ao ficheiro de regras

Um ficheiro de regras como CLAUDE.md ou AGENTS.md é carregado no início de cada sessão e aplica-se a todas as tarefas. O conteúdo de uma competência só é carregado quando essa competência é acionada. A frequência é o critério principal. Um facto válido para todas as tarefas do repositório, como o gestor de pacotes utilizado, pertence ao ficheiro de regras. Um procedimento aplicável a uma pequena parte das tarefas, como a regra do nginx acima, pertence a uma competência, onde não tem custo nos dias em que ninguém edita o nginx.

A falha real consiste em colocá-lo nos dois locais. As duas cópias divergem e, quando o agente faz algo incorreto, não é possível saber qual das cópias seguiu. Escolha um único local para cada instrução. Uma regra que já está exatamente num dos locais e continua a ser ignorada é um problema diferente. Vale a pena verificar os mecanismos por trás de uma instrução ignorada antes de a mover para uma competência e esperar que a mudança resolva o problema. A fronteira entre competências, servidores MCP e ficheiros de regras ajuda a tratar os casos mais complexos, incluindo as situações em que a resposta correta é um servidor MCP (model context protocol) que fornece ao agente uma nova ferramenta, e não uma nova instrução.

Compartilhe depois de provar o seu valor

Uma skill que se mantém útil depois de uma semana de trabalho real merece ser versionada. As skills de projeto em .claude/skills/ são revistas como código e acompanham o repositório. Assim, um colega que o clona recebe a sua correção sem precisar de configurar nada. Mover uma skill entre repositórios sem copiar e colar é outro problema, abordado em como partilhar skills de agentes entre repositórios.

Há uma questão de portabilidade. O Claude Code aceita uma lista extensa de campos de frontmatter, mas o padrão Agent Skills permite apenas seis: name, description, license, compatibility, metadata e allowed-tools. Se carregar uma skill no claude.ai ou a empacotar para a Skills API com outros campos no frontmatter, a operação falha diretamente em vez de ignorar o campo:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

Mantenha-se dentro desses seis campos. O mesmo ficheiro será então carregado pelo Claude Code e por qualquer outra ferramenta que leia o padrão. O ambiente onde o ficheiro é carregado continua a determinar o que ele pode fazer, porque o Cowork é executado numa sandbox da Anthropic, enquanto o Claude Code é executado na sua própria máquina ou VPS. Por isso, vale a pena levar a skill de nginx acima para o checkout de um colega, mas ela não serve numa sandbox que não consiga alcançar o servidor. Escrever as próprias instruções para que funcionem com um modelo diferente é uma tarefa separada. Escrever skills que funcionem com qualquer modelo aborda esse tema.

FAQ

Qual deve ser o tamanho de um ficheiro SKILL.md?

Mantenha-o abaixo de 500 linhas e espere que a maioria das skills úteis seja muito mais curta. O corpo entra na conversa quando a skill é invocada e permanece nela durante o resto da sessão. Por isso, cada linha representa um custo recorrente, não um custo único. Mova o material de referência extenso para ficheiros separados no diretório da skill e crie ligações para eles a partir de SKILL.md, com um nível de profundidade, para que o agente só os leia quando necessário. Os scripts incluídos são executados em vez de lidos, pelo que só o resultado deles representa um custo.

Porque é que a minha skill nunca é ativada?

A descrição é normalmente a causa, porque é a única parte da skill disponível no contexto quando o modelo decide. Certifique-se de que indica quando deve usar a skill, não apenas o que ela faz, e de que contém as palavras que escreve efetivamente nos seus pedidos. Se a descrição parecer correta, verifique o frontmatter em disable-model-invocation: true, que oculta completamente a skill do modelo, e procure um glob paths que a limite a ficheiros que não está a editar. Uma skill num diretório .claude/skills/ aninhado abaixo do diretório inicial é outra causa: só é carregada depois de o agente ler ou editar um ficheiro nesse subdiretório.

Deve ser uma skill ou uma linha no meu ficheiro de regras?

Avalie a quantas das suas tarefas isso se aplica. Um ficheiro de regras é carregado em todas as sessões. Por isso, deve conter factos verdadeiros para todas as tarefas, como o gestor de pacotes ou a convenção de nomes de branches. Uma skill só é carregada quando é ativada. Por isso, é o local adequado para um procedimento relevante apenas para uma pequena parte das tarefas. Nunca escreva a mesma instrução nos dois locais. As cópias podem divergir e deixa de ser possível saber qual delas o agente seguiu.

Como sei se uma skill ajudou realmente?

Compare-a com uma referência de base. Recolha alguns pedidos reais, execute cada um numa sessão nova com a skill disponível e execute-os novamente com a skill desativada no menu /skills. Depois, compare as duas respostas lado a lado. Uma sessão nova é importante porque a conversa em que escreveu a skill ainda contém as suas explicações. Isso pode fazer um ficheiro incompleto parecer completo. O plugin skill-creator faz esta comparação por si e apresenta a taxa de aprovação junto do custo em tokens.

Posso usar o mesmo SKILL.md com outro agente?

Sim, desde que se mantenha dentro dos campos definidos pela norma Agent Skills: name, description, license, compatibility, metadata e allowed-tools. O Claude Code aceita muitos outros campos e também suporta funcionalidades no corpo, como a injeção de comandos shell, que outras ferramentas não executam. Carregar uma skill com um campo fora da norma falha com um erro explícito que apresenta as propriedades permitidas. Por isso, decida desde o início se a skill deve permanecer no Claude Code ou ser transferida.