Biblioteca de skills do Claude: quando revisar e quando aposentar uma skill

Fala aí, beleza? Tem uma skill na sua máquina agora mesmo ensinando o Claude a rodar um comando de um projeto que você já apagou

Ninguém apaga skill

A gente cria, testa, acha massa, e segue a vida. Aí seis meses depois a pasta tem skill de um stack que você abandonou, skill que sincronizou do claude.ai e você nem lembra, skill duplicada com nome parecido

E isso não é só bagunça estética: skill vencida cobra em dois lugares. Cobra contexto, porque nome e descrição de toda skill ficam carregados o tempo todo, e cobra acerto, porque descrição vaga faz o Claude acionar a coisa errada na hora errada

Bora arrumar isso? 🙂

Onde sua biblioteca de skills mora (e como olhar pra ela)

Antes de revisar, você precisa saber o que está olhando

A biblioteca não é um painel mágico em nuvem, é arquivo no disco. Isso é ótimo, porque significa que dá pra tratar ela como código

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Os diretórios são estes:

• ~/.claude/skills/ para as skills pessoais, que valem em qualquer projeto seu
• .claude/skills/ dentro do repositório, para as skills daquele projeto
• ~/.claude/skills/synced/ para as skills sincronizadas do claude.ai, que passam a ser carregadas em toda sessão local seguinte

Esse terceiro é o que mais pega gente de surpresa, porque ele enche sozinho

E tem mais uma origem que não é pasta que você criou: skill que vem de plugin. Ela aparece com o namespace nome-do-plugin:nome-da-skill, e a gente volta nisso lá na frente

A anatomia mínima de uma skill:

Uma skill é uma pasta. O único arquivo obrigatório é o SKILL.md, com frontmatter YAML mais o corpo em markdown

scripts/ e references/ são opcionais

~/.claude/skills/
  revisao-de-pr/
    SKILL.md          <- obrigatório
    scripts/          <- opcional
    references/       <- opcional

No frontmatter, todos os campos são opcionais e só description é recomendada. O campo name aceita apenas letras minúsculas, números e hífens

---
name: revisao-de-pr
description: Revisa um diff procurando bug de lógica e regressão. Use quando o pedido for revisar PR, diff ou branch antes do merge.
---

Se você ainda está decidindo se vale a pena ter skill pra tudo, eu já escrevi sobre quando skills compensam no Claude Code e sobre os limites delas

Os três comandos que mostram a verdade:

Dentro de uma sessão interativa do Claude Code você tem três lentes diferentes:

• /skills lista as skills carregadas naquela sessão
• /context tem uma linha Skills com o tamanho da listagem já com o orçamento aplicado, ou seja, coincide com o que o modelo realmente recebe
• /doctor entrega uma estimativa do custo de contexto da listagem e aponta os maiores contribuintes

Guarda esses três, porque a rotina inteira gira em volta deles

A rotina de revisão da biblioteca de skills em 5 passos

A ideia aqui é uma passada curta e repetível, do tipo que você faz em meia hora e não em um fim de semana

1. Inventariar os diretórios e ver o que realmente carregou

Primeiro o disco, depois a sessão

ls ~/.claude/skills/
ls ~/.claude/skills/synced/
ls .claude/skills/

Aí, dentro do Claude Code:

/skills

A diferença entre as duas listas já é informação. Pasta que existe no disco e você não reconhece na sessão merece uma olhada, e skill carregada que você não lembra de ter escrito provavelmente veio sincronizada ou de plugin

O erro comum deste passo: revisar só o .claude/skills/ do projeto que você está agora e esquecer que a pasta pessoal viaja com você pra todos os outros repositórios

2. Medir o custo, não o tamanho do arquivo

Agora as duas medições:

/context
/doctor

O /context te dá a linha Skills com o tamanho pós orçamento e o /doctor te dá a estimativa da listagem mais os maiores contribuintes

Lembra que só nome e descrição ficam carregados até a skill ser acionada? O corpo entra sob demanda, na tal divulgação progressiva. Então o SKILL.md gigante de 400 linhas pode não ser o vilão, e a skill de 20 linhas com uma descrição enorme pode ser

O erro comum deste passo: abrir o du -sh da pasta e decidir por ali. Tamanho de arquivo não é custo de contexto, quem manda é o que entra na listagem

3. Ler a description de cada skill como se você fosse o Claude

O campo description é o que determina quando o Claude aciona a skill. Por isso ele precisa dizer duas coisas: o que a skill faz E quando usá-la

Pega cada uma e responde: se eu só tivesse esta frase, eu saberia em qual pedido do usuário disparar?

Descrição do tipo "ajuda com deploy" não responde nada. Ela não fala de qual projeto, qual ambiente, em que situação

O erro comum deste passo: escrever descrição bonita pro humano ler. Ela não é vitrine, é gatilho

4. Confrontar o corpo do SKILL.md com o projeto de hoje

Esse é o passo que ninguém faz, e é onde mora o estrago de verdade

Abre o SKILL.md e vai riscando o que mudou: caminho de pasta que não existe mais, comando de build que virou outro, convenção de nomenclatura que o time abandonou, endpoint que foi migrado

Skill com instrução desatualizada é pior que skill nenhuma, porque ela dá confiança pro modelo seguir por um caminho morto

A documentação oficial de boas práticas trata skills como documentos vivos e recomenda um ciclo de observar, refinar e testar, medindo o comportamento real do agente em vez de suposição. E tem um detalhe importante nisso: medir a linha de base sem a skill

Porque às vezes a skill não está errada, ela só não está fazendo diferença nenhuma

O erro comum deste passo: reescrever no capricho e nunca testar. Você troca uma suposição velha por uma suposição nova e segue achando que melhorou

5. Decidir o destino de cada skill

Só tem quatro saídas: manter, reescrever, restringir ou aposentar

Decide na hora, sem deixar pra depois, senão a pasta volta a crescer por acumulação

O Claude Code observa os diretórios de skills e detecta adição, edição ou remoção dentro da sessão em curso, sem precisar reiniciar. Então dá pra mexer e ver o efeito ali mesmo

O erro comum deste passo: achar que essa detecção ao vivo cobre tudo. Ela cobre o texto do SKILL.md. Se você criar um diretório de skills de nível superior que não existia quando a sessão começou, tem que reiniciar o Claude Code pra ele passar a observar aquele diretório

É o tipo de detalhe que faz a skill nova parecer quebrada sem ela estar 😀

A skill existe, mas o Claude não aciona mais: o que está acontecendo

Esse é o sintoma clássico de biblioteca inchada. A pasta está lá, o arquivo está certo, e o Claude simplesmente ignora

Geralmente é uma destas três causas

Sintoma: a descrição foi encurtada sem você saber

Existe um orçamento de contexto pra listagem de skills, controlado pelo setting skillListingBudgetFraction, com valor padrão de 0.01, ou seja, 1% da janela de contexto do modelo

Quando tem skill demais, o Claude Code encurta as descrições pra caber nesse orçamento. E aí some justamente a palavra que faria o casamento entre o seu pedido e a skill

Dois detalhes que ajudam no diagnóstico: os nomes sempre permanecem na listagem, e o corte começa pelas skills que você menos aciona, preservando o texto completo das mais usadas

Ou seja, a skill que você raramente chama é a primeira a ficar muda. E quanto menos ela aciona, menos ela é chamada. Bola de neve

Solução: enxugar a biblioteca (é pra isso a rotina lá de cima) e deixar descrição curta e específica. Se ainda assim precisar, dá pra mexer no skillListingBudgetFraction, e aí entra o trade-off documentado: aumentar preserva descrições longas ao custo de mais contexto por turno, diminuir faz caber mais skills dentro do orçamento

Não existe número mágico aqui, existe escolha

Sintoma: dispara a skill errada

Quase sempre é description vaga em duas skills que se parecem

"Ajuda com testes" e "roda testes" vão brigar pra sempre

Solução: diferenciar pelo quando, não pelo o que. Uma vira "use quando o pedido for escrever teste novo pra função existente", a outra vira "use quando o pedido for executar a suíte e interpretar falha"

Sintoma: tem duas skills com o mesmo nome

Acontece mais do que parece, principalmente entre a pasta pessoal e a do projeto

Quando skills de níveis diferentes têm o mesmo nome, a precedência é enterprise sobre pessoal, e pessoal sobre projeto. Então aquela skill caprichada que você commitou no repositório pode estar sendo silenciada por uma versão velha na sua home

E a colisão de nome não acontece só entre skills. Se um comando em .claude/commands/ e uma skill em .claude/skills/ têm o mesmo nome, a skill vence. Com .claude/commands/deploy.md e .claude/skills/deploy/SKILL.md no mesmo projeto, o /deploy executa a skill, não o comando

Se essa fronteira ainda te confunde, vale entender a diferença entre skills, comandos e subagentes antes de sair renomeando coisa

Skill vinda de plugin é a exceção tranquila: como ela usa o namespace nome-do-plugin:nome-da-skill, não colide com os outros níveis. Um /my-plugin:deploy convive numa boa com um deploy do projeto

Solução: nome distinto e prefixo por domínio. deploy-web, deploy-worker, e acabou a briga

Aposentar, desligar ou só tirar do automático: escolhendo a saída certa

Aposentar não é sempre deletar

Tem skill que você usa uma vez por trimestre e que é ótima justamente naquele dia. Matar ela é burrice, deixar ela concorrendo na listagem todo santo turno também

Aposentar de vez:

A orientação oficial é direta: atualizar a skill quando o fluxo de trabalho muda ou quando as avaliações caem, e depreciar quando as avaliações falham de forma consistente ou o fluxo foi aposentado

Removeu a pasta, a remoção é detectada na sessão em curso. Não precisa reiniciar nada

Tirar do automático:

Esse é o meio termo que salva skill boa de virar lixo

---
name: migrar-banco-legado
description: Roda a migração do banco legado e valida o schema. Use quando o pedido citar a migração do legado.
disable-model-invocation: true
---

Com disable-model-invocation: true o Claude não aciona a skill sozinho. A invocação fica só pra você, via /nome-da-skill

Perfeito pra skill perigosa e pra skill sazonal

Desligar o plugin inteiro:

Se o excesso veio de um plugin, mexer em skill uma a uma é enxugar gelo

/plugin disable nome-do-plugin@nome-do-marketplace
/plugin uninstall nome-do-plugin@nome-do-marketplace
/reload-plugins

O /reload-plugins aplica as mudanças feitas durante a sessão sem reiniciar o Claude Code

Um aviso pra não perder tempo:

O campo allowed-tools não é trava de ferramenta

Toda ferramenta continua acionável e as configurações de permissão seguem governando as que não estão listadas. Então não dá pra usar allowed-tools pra "aposentar pela metade" uma skill e dormir tranquilo

Se o objetivo é limitar de verdade, o lugar disso é permissão, não frontmatter de skill

Trate a biblioteca como código: revisão marcada no calendário

Skill é documento vivo, não arquivo morto

A doc oficial diz isso com todas as letras: observar, refinar e testar, medindo o comportamento real do agente. E ninguém faz isso por impulso, faz por rotina

Então o próximo passo concreto pra hoje é curtinho:

1. rodar /doctor e ver quem são os maiores contribuintes da listagem
2. cortar as três skills que mais pesam e que você não aciona há semanas
3. rodar /context de novo e olhar a linha Skills, só pra sentir a diferença

E marca a próxima revisão amarrada a um marco do projeto, não a uma data solta: mudança de stack, fim de um fluxo, entrada de plugin novo

São nesses três momentos que a biblioteca envelhece de uma vez só

Biblioteca enxuta não é minimalismo por estética, é o Claude achando a skill certa na hora certa

Até o próximo post! 😀