Agent Skills: como escrever a sua primeira

Uma skill é um SKILL.md com frontmatter YAML e instruções em markdown. O nome da pasta vira o comando. Isso é tudo o que você precisa para a primeira.

O que quase ninguém conta é o que acontece depois de invocar: o conteúdo renderizado entra na conversa como uma mensagem e fica lá o resto da sessão. O Claude Code não relê o arquivo nos turnos seguintes. A vantagem da skill sobre o CLAUDE.md não é que ela sai depois de usada — é que ela só entra se for usada.

Essa diferença decide o tamanho do corpo que você escreve, e explica por que uma skill às vezes "para de funcionar" no meio da sessão.

Os três carregam instrução, em momentos diferentes.

A documentação dá o gatilho para criar uma skill: quando você repete a mesma instrução, checklist ou procedimento de vários passos no chat, ou quando uma seção do CLAUDE.md deixou de ser fato e virou procedimento.

O critério prático: fato que vale em toda tarefa fica no CLAUDE.md; procedimento que vale às vezes vira skill; regra que precisa valer sempre vira hook.

A anatomia de um CLAUDE.md que funciona cobre o outro lado dessa decisão.

O exemplo abaixo resume as mudanças não commitadas e sinaliza risco. Vale a pena porque puxa o diff de verdade para dentro do prompt, em vez de deixar o agente adivinhar pelos arquivos abertos.

1. Crie a pasta. Skill pessoal vale em todos os seus projetos:

mkdir -p ~/.claude/skills/resumir-mudancas

2. Escreva o SKILL.md:

---
description: Resume mudanças não commitadas e sinaliza riscos. Use quando o
  usuário perguntar o que mudou, pedir mensagem de commit ou pedir revisão do diff.
---

## Mudanças atuais

!`git diff HEAD`

## Instruções

Resuma as mudanças acima em dois ou três bullets, depois liste os riscos que
notar: tratamento de erro ausente, valor hardcoded, teste que precisa mudar.
Se o diff estiver vazio, diga que não há mudanças não commitadas.

A linha !`git diff HEAD` é injeção de contexto dinâmico: o Claude Code roda o comando e substitui a linha pela saída antes de o agente ver o conteúdo. A instrução chega com o diff já embutido.

3. Teste dos dois jeitos. Perguntando algo que case com a descrição ("o que eu mudei?"), ou invocando direto com /resumir-mudancas.

A gramática completa do lado de comando, com argumentos posicionais e nomeados, empilhamento e o que quebra ao publicar, está em slash commands próprios.

Note o que não está no frontmatter: nem name, nem mais nada.

Aqui há uma diferença que vale conhecer. A spec aberta Agent Skills, formato criado pela Anthropic e liberado como padrão aberto, hoje adotado por Cursor, Gemini CLI, Copilot, OpenCode e dezenas de outros, define name e description como o mínimo. O Claude Code é mais permissivo: todos os campos são opcionais, e sem description ele usa o primeiro parágrafo do markdown. Só que aí o agente perde o texto que usaria para decidir invocar sozinho.

Aqui está a parte contraintuitiva: empresa sobrepõe pessoal, e pessoal sobrepõe projeto.

Sim, ao contrário do que a intuição diz. Se existe uma skill deploy em ~/.claude/skills/ e outra no .claude/skills/ do projeto, o /deploy roda a pessoal. Isso pega quem espera que o repositório tenha a última palavra.

Skills de plugin escapam do conflito porque usam namespace plugin:skill. E uma skill em qualquer nível sobrepõe uma skill embutida de mesmo nome — mas não os apelidos dela. Uma skill code-review sua substitui a /code-review embutida, e digitar o apelido /review nunca roda a sua.

O nome do comando vem da pasta, não do frontmatter. Em skill pessoal ou de projeto, o campo name define só o rótulo que aparece na listagem. Em skill de plugin é diferente: ali o name define o último segmento do comando.

Vale saber também que comandos personalizados foram unificados com skills. Um .claude/commands/deploy.md e um .claude/skills/deploy/SKILL.md criam o mesmo /deploy. Se os dois existirem, a skill tem precedência — o que também vale para os comandos embutidos do Claude Code.

São mais de quinze campos. Estes cinco resolvem quase tudo:

Duas notas de segurança sobre allowed-tools, porque são fáceis de não perceber.

A concessão vale só no turno que invocou a skill — some na sua próxima mensagem, mesmo com o conteúdo ainda no contexto. E ela não restringe: todas as ferramentas continuam chamáveis, e suas configurações de permissão continuam valendo para as que não estão na lista. Para restringir, o campo é disallowed-tools.

A segunda é mais séria: confiança de workspace não bloqueia esse campo. O allowed-tools de uma skill de projeto é aplicado sempre que ela é invocada, inclusive numa execução -p numa pasta que você nunca marcou como confiável. Uma skill pode conceder acesso amplo a si mesma. Revise o allowed-tools de skills que vêm num repositório antes de rodar o Claude Code ali.

A spec aberta descreve o carregamento em três estágios, e entender onde cada custo mora resolve a maior parte das dúvidas:

É o estágio de descoberta que explica por que ter muitas skills instaladas cobra um preço mesmo sem você usar nenhuma delas. E é a ativação que explica a próxima parte.

Invocada, a skill entra na conversa como uma única mensagem e permanece pelo resto da sessão. Isso tem três consequências práticas.

Cada linha é custo recorrente. A documentação é direta: escreva o que fazer, não a narração de como e por quê, e aplique o mesmo teste de concisão que você aplicaria ao CLAUDE.md.

Reinvocar não duplica — a menos que mude. Se o conteúdo renderizado é idêntico ao que já está no contexto, o Claude Code adiciona só uma nota dizendo que a skill já está carregada. Se mudou, porque os argumentos mudaram ou porque um comando de contexto dinâmico produziu saída nova, o conteúdo completo é anexado de novo.

A compactação não preserva tudo. Quando a conversa é resumida para liberar contexto, o Claude Code reanexa a invocação mais recente de cada skill depois do resumo, guardando os primeiros 5.000 tokens de cada uma. As reanexadas dividem um orçamento combinado de 25.000 tokens, preenchido a partir da mais recente. Se você invocou muitas skills numa sessão, as mais antigas somem por completo depois da compactação.

Há um diagnóstico que sai daí. Se a skill parece parar de influenciar o comportamento depois da primeira resposta, quase sempre o conteúdo continua lá e o modelo está escolhendo outra abordagem. A saída é reforçar a description e as instruções, ou usar hook para garantir de forma determinística. Se a skill era grande ou você invocou várias depois dela, reinvoque após a compactação.

Porque a listagem de descrições tem orçamento, e ele estourou.

O Claude Code carrega no contexto uma listagem com nome e descrição de cada skill disponível, para o agente saber o que existe. A listagem sempre contém todos os nomes. Mas se você tem muitas skills, ele encurta as descrições para caber no orçamento — e é aí que somem as palavras-chave que fariam o agente casar o seu pedido com a skill certa.

Dois números decidem isso:

• O orçamento da listagem escala em 1% da janela de contexto do modelo
• Cada entrada tem description + when_to_use limitadas a 1.536 caracteres, independentemente do orçamento

E a regra de corte importa: quando a listagem transborda, o Claude Code derruba as descrições começando pelas skills que você menos invoca. As que você usa mais mantêm o texto completo.

Isso significa que instalar dezenas de skills tem um custo que ninguém anuncia: as skills novas, que você ainda não usou, são as primeiras a perder a descrição — e sem descrição elas nunca são invocadas automaticamente, o que as mantém sem uso. É um ciclo que se fecha sozinho.

Como diagnosticar e resolver:

E os três ajustes possíveis: subir o orçamento com skillListingBudgetFraction (0.02 = 2%), marcar entradas de baixa prioridade como "name-only" em skillOverrides para liberar espaço, ou enxugar description e when_to_use na fonte — colocando o caso de uso principal primeiro, já que o corte vem do fim.

O catálogo com as skills avaliadas fica em /skills.

O catálogo com as 44 skills avaliadas existe justamente porque instalar tudo não é estratégia: cada skill instalada disputa o mesmo orçamento de listagem.

Uma skill pode ter vários arquivos na pasta. É assim que você mantém o SKILL.md enxuto sem perder material de referência.

minha-skill/
├── SKILL.md          (obrigatório — visão geral e navegação)
├── reference.md      (doc detalhada — carregada quando precisa)
├── examples.md       (exemplos — carregados quando precisa)
└── scripts/
    └── helper.py     (executado, não carregado)

A regra: referencie os arquivos de apoio a partir do SKILL.md, dizendo o que cada um contém e quando carregar. Doc de API grande, especificação, coleção de exemplos — nada disso precisa entrar no contexto toda vez que a skill roda.

O script na pasta scripts/ é executado, não lido para dentro do contexto. É a forma mais barata de dar capacidade a uma skill.

O Claude Code aceita todos os campos do frontmatter. Fora dele, não.

Para upload em claude.ai, para a Skills API e para empacotamento com o package_skill.py do repositório anthropics/skills, só valem os seis campos da spec Agent Skills: name, description, license, compatibility, metadata e allowed-tools.

E a falha é dura, não silenciosa:

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

Ou seja: se a skill nasceu com context: fork, disable-model-invocation ou paths, ela funciona lindamente na sua máquina e quebra no empacotamento. Recursos de corpo exclusivos do Claude Code, como a injeção de contexto dinâmico com !`comando`, também não funcionam no chat do claude.ai nem pela API.

Se a intenção é distribuir, escreva desde o começo dentro dos seis campos.

Para escolher entre skill, subagente, hook e CLAUDE.md antes de escrever qualquer arquivo, veja qual usar para cada coisa.

Skill ou subagente?

Skill carrega instrução no seu contexto; subagente roda em contexto próprio e devolve resumo. Se a tarefa produz saída verbosa (rodar teste, processar log), subagente evita que isso ocupe sua janela. Se é conhecimento que o agente deve aplicar ao trabalho em andamento, skill. Dá para combinar: context: fork roda a skill dentro de um subagente.

Por que o /skill-name funciona mas o agente nunca invoca sozinho?

Provavelmente o YAML do frontmatter está malformado. Nesse caso o Claude Code carrega o corpo com metadados vazios: o comando continua funcionando, mas não existe description para o agente casar com o pedido. Rode com --debug para ver o erro de parse.

Minha skill dispara demais. Como conter?

Duas saídas: deixar a description mais específica, ou adicionar disable-model-invocation: true se você quiser só invocação manual.

Quantas skills dá para ter instaladas?

Não há limite rígido, mas há um limite prático: a listagem de descrições ocupa 1% da janela de contexto, e ao estourar as descrições das skills menos usadas são cortadas. Rode /doctor para ver o custo atual. Mais útil que aumentar o orçamento é remover o que você não usa.

• Anthropic — Claude Code Docs: Extend Claude with skills. Acesso em 19/08/2026.
• Anthropic — Claude Code Docs: How Claude remembers your project. Acesso em 19/08/2026.
• Anthropic — Claude Code Docs: Sub-agents. Acesso em 19/08/2026.
• Anthropic — Claude Code Docs: Manage costs effectively. Acesso em 19/08/2026.
• Agent Skills — especificação aberta. Acesso em 19/08/2026.

Verificado em 19 de agosto de 2026.

Gatilho de reavaliação: revisar quando (a) mudarem o limite de 1.536 caracteres ou a fração de 1% do orçamento de listagem, (b) mudarem os orçamentos de 5.000 e 25.000 tokens da compactação, (c) a spec Agent Skills passar a aceitar mais campos, ou (d) a precedência entre escopos pessoal e projeto mudar.