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, registe a correção que introduziu nas duas ocasiões e guarde essa correção como um ficheiro SKILL.md que o agente possa carregar sozinho. Depois disso, tudo é mecânico: a estrutura dos ficheiros e a única 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 for novo para si, 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.

Isto acontece repetidamente em servidores reais. Pede ao agente para adicionar um bloco de reverse proxy ao nginx. Ele edita /etc/nginx/conf.d/app.conf e executa sudo systemctl restart nginx. A edição contém um erro, por isso o nginx recusa arrancar e o site fica indisponível até corrigir 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.

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

Registe duas coisas enquanto a falha ainda está à sua frente: o pedido que escreveu e a correção que deu, usando as palavras que utilizou. Essas duas linhas tornam-se a skill. O pedido indica o que o acionador tem de corresponder. A correção constitui todo o conteúdo.

As orientações de autoria da Anthropic colocam este passo em primeiro lugar. Execute o agente em tarefas representativas sem uma skill, registe onde falha e escreva depois apenas as instruções mínimas que corrigem essas falhas. As falhas são a especificação. Por isso, uma skill que não consiga associar a uma falha específica é normalmente uma skill de que ninguém precisava.

Para ver um exemplo trabalhado do mesmo processo de destilação, Ponytail transforma uma falha repetida, em que um agente reescreve muito mais do que foi pedido, numa skill pode ler o artigo completo antes de escrever a sua própria.

Anatomia de uma skill

Uma skill é um diretório com um 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 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. Os elementos são:

• 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 principal, e a secção seguinte trata apenas deste assunto.
• O corpo: as instruções, carregadas apenas quando a skill é efetivamente acionada.
• reference/: ficheiros adicionais que o agente lê quando necessário. 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 é frequentemente lido apenas em parte.
• scripts/: ficheiros que o agente executa em vez de ler. Apenas a saída consome contexto, por isso um script com 300 linhas tem um custo reduzido.

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 todas as pessoas que clonarem o repositório.
• ~/.claude/skills/<name>/SKILL.md: todos os projetos na sua máquina, mas não os projetos de outras pessoas.
• <plugin>/skills/<name>/SKILL.md: incluída num plugin e 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 efeito na sessão em execução. Criar um diretório 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 seu 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 é inserido no prompt do sistema, onde a primeira pessoa parece ser o modelo a falar sobre 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 nomeia /etc/nginx, server block, reverse proxy e TLS (transport layer security) certificate path, que correspondem aproximadamente ao vocabulário de qualquer pedido que deva acioná-la.

Este é o teste para uma descrição. Dê essa linha isolada a alguém que nunca tenha visto o conteúdo, juntamente com o pedido que está prestes a 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 resto da sessão. O Claude Code não relê o ficheiro nas mensagens seguintes. Cada linha que escrever é um custo para toda a sessão, não apenas para uma resposta.

A Anthropic recomenda manter SKILL.md com menos de 500 linhas e mover 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 volta a anexar 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 é truncada a meio. Várias skills longas podem excluir-se mutuamente por completo.

Por isso, 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 é o único motivo pelo qual este ficheiro existe.

Se a skill indicar ao agente que execute um script incluído, especifique o caminho com ${CLAUDE_SKILL_DIR} para que ele seja resolvido independentemente do local onde a skill está instalada e pré-aprove o mesmo comando para que a execução não seja interrompida por um pedido de permissão.

---
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 a mensagem que invocou a skill e é eliminada quando enviar a mensagem seguinte. Assim, não se transforma silenciosamente numa permissão permanente.

Como comprovar que a skill é acionada

Observar o carregamento de uma skill confirma que o agente a encontrou. Isso não confirma que a resposta foi alterada. Verifique os dois aspetos e faça o teste numa sessão nova, porque a sessão onde escreveu a skill já contém tudo o que disse durante a criação. Esse contexto residual pode ocultar lacunas no 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 a skill.
3. Observe se ocorre a invocação. Se a skill não for acionada, corrija a descrição. O corpo ainda não é o problema.
4. Invoque-a manualmente com /nginx-config-changes como controlo. Um comportamento correto quando é invocada manualmente e incorreto quando é invocada pelo pedido confirma um problema no acionamento, não nas instruções.
5. Execute o mesmo pedido com a skill desativada e compare as duas respostas. No menu /skills, selecione a 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. Prima Space novamente para alternar o estado de volta para on quando terminar.
6. Escreva alguns pedidos que não devem acionar a skill e confirme que ela permanece inativa.

Para automatizar esse 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 a saída da instalação indicar Run /reload-plugins to activate., execute esse comando. Em seguida, peça ao Claude para avaliar a sua skill pelo nome. O plugin armazena os casos de teste em evals/evals.json dentro do diretório da skill e executa cada caso no seu próprio subagente, para que cada execução comece com um contexto limpo. Depois, gera uma comparação entre o resultado com a skill e o resultado sem a skill. Esse é o valor real: a melhoria da taxa de aprovação medida em relação aos tokens e ao tempo consumidos pela skill.

Modo de falha: a skill nunca é acionada

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

• A descrição informa o que a skill faz, mas nunca diz quando deve ser usada. Por isso, nada no seu pedido corresponde a ela.
• A descrição evita as palavras que você usa. Se você disser "nginx", a descrição também deverá conter "nginx".
• disable-model-invocation: true está definido no frontmatter. Isso mantém a descrição completamente fora do contexto do modelo e deixa a skill invocável apenas por você com /name.
• Um padrão paths no frontmatter limita a ativação aos ficheiros correspondentes, e o ficheiro em que está a trabalhar não corresponde ao padrão.
• A skill está num diretório .claude/skills/ aninhado abaixo do diretório inicial. Essas 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 é uma descrição tão ampla que a skill é acionada durante trabalhos não relacionados. “Use ao trabalhar no servidor” 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 só se aplicar a determinados ficheiros. Para qualquer operação com efeitos secundários, como um deploy ou um commit, defina disable-model-invocation: true e invoque-a diretamente com /name, para que o agente nunca decida por si próprio que chegou o momento adequado para fazer o deploy.

Modo de falha: a competência pertence ao seu 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 é ativada. 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 apenas 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.

O verdadeiro problema é colocá-lo nos dois locais. As duas cópias ficam diferentes 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. a fronteira entre competências, servidores MCP e ficheiros de regras trata dos 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, em vez de uma nova instrução.

Compartilhe depois de comprovar o valor

Uma skill que se mantém útil durante uma semana de trabalho real merece ser versionada. As skills do projeto em .claude/skills/ são revistas como código e ficam disponíveis com o repositório. Assim, quem fizer clone do repositório recebe a correção sem precisar de nenhuma configuração adicional. Transferir uma skill entre repositórios sem copiar e colar é outro problema, abordado em como compartilhar 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 por completo 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 para que o mesmo ficheiro seja carregado no Claude Code e em qualquer outro sistema que leia o padrão. Escrever as instruções de forma que continuem a funcionar com outro modelo é uma tarefa separada, abordada em como escrever skills compatíveis com qualquer modelo.

FAQ

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

Mantenha-o abaixo de 500 linhas e considere que a maioria das skills úteis será 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 apenas um nível de profundidade. Assim, o agente só os lê quando precisa deles. Os scripts incluídos são executados em vez de serem lidos, por isso o custo corresponde apenas à respetiva saída.

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 utilizar a skill, e não apenas o que ela faz, e de que inclui as palavras que escreve efetivamente nos seus pedidos. Se a descrição parecer correta, verifique o frontmatter para disable-model-invocation: true, que oculta completamente a skill do modelo, e para um glob paths que a limita a ficheiros que não está a utilizar. Uma skill num diretório .claude/skills/ aninhado abaixo do diretório inicial é outra possível causa: só é carregada depois de o agente ler ou editar um ficheiro nesse subdiretório.

Devo criar uma skill ou adicionar uma linha ao 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, porque as cópias divergem e deixa de ser possível saber qual delas o agente seguiu.

Como sei se uma skill foi realmente útil?

Compare-a com uma referência. 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, leia as duas respostas lado a lado. Uma sessão nova é importante porque a conversa onde escreveu a skill ainda contém as suas explicações, fazendo com que um ficheiro incompleto pareça completo. O plugin skill-creator executa esta comparação por si e apresenta a taxa de aprovação junto ao custo em tokens.

Posso utilizar o mesmo SKILL.md com um agente diferente?

Sim, desde que permaneça dentro dos campos definidos pelo padrão Agent Skills: name, description, license, compatibility, metadata e allowed-tools. 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. O carregamento de uma skill com um campo fora do padrão falha com um erro explícito que lista as propriedades permitidas. Por isso, decida desde cedo se a skill deve permanecer no Claude Code ou ser utilizada noutros agentes.