Como revisar as skills do Claude Code que você instalou e nunca usou

Fala aí, beleza? Aposto que sua pasta de skills virou depósito: instalou porque viu num vídeo, achou massa, rodou uma vez e nunca mais abriu…

O problema é que skill parada não fica quietinha num canto

Na inicialização, o Claude Code pré-carrega os metadados (name e description) de TODAS as skills que ele enxerga, e só lê o SKILL.md completo quando a skill vira relevante

Ou seja: a listagem em si já ocupa orçamento de contexto, mesmo das skills que você nunca chamou

E tem mais: depois que uma skill carrega, o conteúdo dela fica no contexto entre os turnos, virando custo recorrente de token que disputa espaço com o histórico da conversa

Então bora fazer faxina? 😀

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 110 aulas
• 4 projetos
• 9h 2min

Conhecer formação

O que você precisa saber antes de mexer

Antes de sair desligando coisa, vale entender onde esse acúmulo mora e como ele funciona

Onde as skills vivem:

São dois lugares:

• ~/.claude/skills/: skills pessoais, valem pra todos os seus projetos
• .claude/skills/: skills do projeto, ficam dentro do repositório

Essa diferença muda a decisão da faxina inteira

Skill pessoal parada te acompanha em todo projeto que você abrir, enquanto a de projeto viaja junto com o repo, que é justamente o caminho pra padronizar skills com o time

O formato de uma skill:

Cada skill é uma pasta com um arquivo SKILL.md dentro

Esse arquivo tem frontmatter YAML entre os marcadores --- e o corpo em markdown com as instruções

minha-skill/
  SKILL.md

E o SKILL.md começa assim:

---
name: revisao-de-codigo
description: Revisa o diff atual procurando bugs de correção e pontos de simplificação
---

Instruções da skill em markdown aqui

Por que o frontmatter é o coração da faxina?

Porque a decisão de acionamento automático é baseada nos metadados name e description

É com esses dois campos que o Claude decide se aquela skill entra ou não na tarefa atual

Ou seja: description ruim é skill que nunca aciona, e description larga demais é skill que aciona quando ninguém pediu

Dois avisos pra não tomar susto:

A escolha que você faz no menu /skills é salva em .claude/settings.local.json

E skills que vieram de plugin NÃO são afetadas por skillOverrides, essas você gerencia pelo /plugin

Guarda isso, porque é o motivo número um de "desliguei e continua aparecendo" 🙂

Passo a passo da faxina de skills do Claude Code

A ideia aqui é fazer em lote, uma vez, com calma

1. Inventário das duas pastas

Abre ~/.claude/skills/ e .claude/skills/ e lista o que existe

Depois lê o frontmatter de cada SKILL.md, só o topo, entre os ---

Anota o name, a description e responde uma pergunta só: "eu usaria isso essa semana?"

O erro comum deste passo: revisar só a pasta do projeto e esquecer a pessoal

A pessoal é a que pesa em TODOS os projetos, é ali que mora o entulho de curiosidade

2. Rodar /doctor pra ver o tamanho do estrago

O /doctor traz uma estimativa do custo de contexto da listagem de skills e aponta as que mais pesam

/doctor

Esse é o seu diagnóstico inicial, e é ele que transforma achismo em decisão

O erro comum deste passo: começar desligando pelo "feeling" e mexer justamente nas leves, deixando as pesadas intactas

3. Subir com –debug quando a listagem estoura

Quando a listagem de skills passa do orçamento de contexto, o Claude Code grava um aviso no log de debug

Pra ver esse aviso, roda com a flag:

claude --debug

Se o aviso aparecer, é sinal claro de que a faxina não é frescura, é necessidade

4. Abrir /skills e ciclar os estados

Esse é o caminho mais rápido, sem editar arquivo na mão:

/skills

Destaca a skill, aperta Espaço pra ciclar entre os estados e Enter pra salvar a escolha

A escolha vai parar no .claude/settings.local.json

O erro comum deste passo: sair do menu sem apertar Enter e achar que ficou salvo

5. Classificar cada skill nos quatro estados

Aqui é onde a faxina fica cirúrgica, porque não é só ligado ou desligado

O skillOverrides define o estado por nome, com quatro valores:

Na prática:

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

Skill que não estiver no skillOverrides é tratada como on

Ou seja: quem você não citar, continua ligado do jeito que está

O erro comum deste passo: tentar domar skill de plugin por aqui

skillOverrides não se aplica a skill de plugin, essa é a regra e não tem jeitinho

6. Tratar as skills embutidas

As que já vêm no Claude Code também entram na conta, e tem uma chave só pra elas:

{
  "disableBundledSkills": true
}

Isso desliga todas as bundled skills, com uma exceção: o /doctor continua

O que é ótimo, porque é justamente ele que você vai querer rodar depois pra conferir o resultado 😀

O erro comum deste passo: ligar essa chave achando que resolve tudo

Ela não toca nas suas skills pessoais, nem nas de projeto, nem nas de plugin

7. Tratar as skills que vieram de plugin

Pra essas, o caminho é o plugin em si

Dá pra desativar sem desinstalar, reativar, ou remover de vez limpando as dependências no mesmo passo:

claude plugin disable <plugin>
claude plugin enable <plugin>
claude plugin uninstall <plugin> --prune

Os comandos aceitam escopo pela flag -s / --scope, que recebe user, project ou local

E a instalação tem quatro escopos: user (pessoal, vale em todos os projetos, é o padrão), project (compartilhado com o time via controle de versão), local (específico do projeto, não compartilhado) e managed (somente leitura)

Detalhe que economiza xingamento: rodar /plugin disable, /plugin enable ou /plugin uninstall dentro do Claude Code abre o painel de plugins e o deixa aberto

Pra script, a orientação é usar os comandos claude plugin no shell, que não abrem painel nenhum

O erro comum deste passo: tentar desativar um plugin que outro plugin ativo depende, aí a operação falha

E o irmão feio desse erro: mandar /plugin marketplace remove <nome> no impulso, porque remover o marketplace desinstala os plugins que vieram dele

Ajustar ou tirar: como decidir o destino de cada skill

Faxina boa não é sair deletando tudo, é decidir caso a caso

Se liga na árvore de decisão:

Cenário 1: a skill nunca aciona sozinha

Se o Claude nunca puxa aquela skill, o suspeito número um é a description vaga

Lembra que a decisão de acionamento é baseada em name e description? Então é ali que se mexe

Respeitando os limites de validação:

• name: máximo 64 caracteres, apenas letras minúsculas, números e hífens, sem tags XML e sem palavras reservadas
• description: máximo 1024 caracteres, não pode ser vazia, sem tags XML

Escreve a description dizendo QUANDO usar aquilo, não só o que aquilo é

Cenário 2: a skill aciona, mas entrega errado

Aqui tem uma armadilha que pega muita gente: ver a skill ser acionada não prova que ela fez o que deveria

São duas medições separadas:

1. se o Claude invoca a skill nos prompts em que deveria invocar
2. se a saída corresponde ao esperado quando ela é invocada

Se a primeira está ok e a segunda não, o problema é o corpo do SKILL.md, não o frontmatter

E se duas descriptions cobrem o mesmo terreno, o caminho é resolver o conflito entre duas skills antes de culpar o modelo

Cenário 3: é útil, mas só quando EU chamo

Aquela skill de tarefa pontual, que você quer disponível mas não quer que entre sozinha no meio de um prompt qualquer?

user-invocable-only: escondida do Claude, mas ainda no menu /

Esse estado é o melhor amigo de quem tem skill boa e específica demais pra ficar competindo por atenção

Cenário 4: baixa prioridade, só precisa existir

Pra essas, a própria documentação sugere name-only

A skill fica listada sem a description, o que reduz o custo da listagem

É o meio-termo honesto entre "deixa ligado e paga o preço" e "desliga e esquece que existe"

Cenário 5: skill morta

Instalou por curiosidade, nunca entrou no fluxo, não vai entrar

off: escondida do Claude e do menu /

Sem drama, sem saudade 🙂

O que a prática com skills mostrou na hora de limpar

Esse post nasceu de um susto meu, pra ser bem honesto

No vídeo abaixo eu rodo um prompt simples, de criação de landing page, e percebo que skills instaladas de vídeos e projetos anteriores foram acionadas sozinhas

Eu não tinha pedido nada relacionado a elas

Elas não estavam presas àquele projeto: por estarem em pastas genéricas, ficavam disponíveis pra ferramenta agêntica usar em qualquer projeto

E aí vem a parte que confirma o diagnóstico: quem não tem skills instaladas simplesmente não veria esse comportamento

O gatilho veio do que estava acumulado na minha máquina, não do prompt

Minha conclusão no vídeo foi essa: excesso de skills é prejudicial, porque a ferramenta passa a usar skill quando o usuário não pediu

E isso não sai de graça, aumenta o consumo

Já tinha falado desse mesmo problema em outros vídeos meus sobre Claude Code e Antigravity, mas ver acontecendo num prompt bobo de landing page é outra coisa

Skill, no fim, é arquivo markdown com instrução pra tarefa específica do projeto: análise de saúde do código, revisão de código, planejamento de deploy, verificação de segurança, verificação de performance, criar componente, criar página, por aí vai

Cada uma dessas parece inofensiva sozinha

Juntas, viram uma listagem que compete com o seu histórico de conversa

Problemas comuns depois da limpeza (e como prevenir)

Faxina sempre gera efeito colateral, então antecipando os seus:

A skill sumiu do menu /

Causa: ela foi parar em off, que esconde do Claude E do menu

Solução: volta pra on se você quer acionamento automático, ou user-invocable-only se você só quer poder chamar na mão

O Claude parou de acionar aquela skill sozinho

Causa: name-only

Esse estado lista só o name pro Claude, sem a description, e é justamente a description que alimenta a decisão de acionamento

Solução: se você QUER o acionamento automático de volta, é on

Se você só queria economizar contexto, então está funcionando como o esperado, é só chamar pelo menu /

Desativar o plugin falhou

Causa: existe plugin ativo dependendo dele, e o disable falha nesse caso

Solução: resolve o dependente primeiro, depois volta no que você queria desligar

Ativar um plugin trouxe outros junto

Causa: o enable propaga dependências no mesmo escopo

Solução: nada quebrado aqui, é o comportamento

Só vale conferir o escopo que você usou (user, project ou local) pra não espalhar coisa pro time sem querer

A skill some depois da compactação

Essa aqui confunde geral

Na compactação da conversa, o Claude Code reanexa a invocação mais recente de cada skill depois do resumo

São 5.000 tokens mantidos por skill reanexada, com orçamento combinado de 25.000 tokens

E o preenchimento começa pela skill invocada mais recentemente, então skills antigas podem ser descartadas por completo se muitas foram invocadas na mesma sessão

Solução: menos skill ativa por sessão, mais chance da que importa sobreviver ao resumo

Prevenção

Revisa em lote, num momento reservado pra isso

Decidir estado de skill no meio de uma sessão de trabalho é receita pra desligar a errada e só descobrir três dias depois 😛

Faxina feita: o que fazer na próxima revisão

A parte chata é que isso não é evento único, é rotina

Toda vez que você testa ferramenta nova, assiste vídeo e instala coisa por curiosidade, a pasta enche de novo

Então fica com esses três hábitos:

• manter em on só o que participa do seu dia a dia de verdade
• usar name-only como meio-termo, em vez de decidir tudo no oito ou oitenta entre on e off
• passar o /doctor de tempos em tempos, só pra ver se a listagem voltou a inchar

E o próximo passo é pequeno, dá pra fazer hoje: abre a lista, escolhe UMA skill que está parada e decide entre ajustar a description ou desligar

Uma só já muda o jogo, porque quebra a inércia de "depois eu vejo isso"

até o próximo post! 🙂