Skills demais no Claude Code

O que é cada coisa

1. Skill: uma pasta com um arquivo SKILL.md de instruções que você dá ao Claude. As pessoais ficam em ~/.claude/skills/<nome>/SKILL.md e valem em todos os projetos. As de projeto ficam em .claude/skills/<nome>/SKILL.md, dentro da pasta do projeto.
2. Descrição: o campo description no começo do SKILL.md. É por ela que o Claude decide quando usar a skill sozinho. O campo opcional when_to_use é somado à descrição na lista e conta no mesmo teto de caracteres.
3. Lista de skills: o Claude Code manda ao Claude uma lista com o nome e a descrição de cada skill. A documentação diz que cada skill da lista ocupa espaço em toda mensagem, mesmo que o Claude nunca a use. O resto do SKILL.md só entra quando a skill é usada.
4. Espaço que o Claude tem para ler: é a janela de contexto, o tanto de texto que o modelo consegue considerar de uma vez numa conversa. A lista de skills disputa esse espaço com o resto da conversa.
5. Orçamento da lista: a lista tem um teto de 1% da janela de contexto do modelo. Quando passa do teto, o Claude Code corta descrições, começando pelas skills que você menos usa. O nome continua na lista, e as skills que você mais usa mantêm o texto inteiro.
6. Teto de cada descrição: a descrição somada ao when_to_use é cortada em 1.536 caracteres, independente do orçamento. O valor muda com a configuração skillListingMaxDescChars.

Por que isso faz o Claude ignorar uma skill

Sem a descrição, somem as palavras que o Claude usa para ligar o seu pedido àquela skill. A chance de ele escolher a skill sozinho cai. Nossa leitura: a chance cai, mas não zera, e você ainda pode chamar a skill pelo nome, digitando /nome-da-skill, desde que ela não esteja desligada.

Veja quanto a lista ocupa

Dentro de uma sessão do Claude Code:

/doctor

Segundo a documentação, o /doctor mostra uma estimativa do quanto a lista de skills ocupa e quais skills pesam mais. A linha Skills do comando /context mostra o tamanho da lista depois do corte, que é o que o modelo de fato recebe. Em versões anteriores à 2.1.196, essa linha mostrava um número muito maior que o real; se o seu parece enorme, atualize antes de se preocupar. Quando a lista passa do orçamento, o Claude Code também grava um aviso no arquivo de diagnóstico que ele mantém para quem investiga problemas, visível se você abrir o Claude Code com --debug.

Ache as skills que você não usa

Dentro de uma sessão:

/skill-doctor

O relatório mostra o custo de contexto de cada skill e quantas vezes ela foi usada, e marca as que nunca foram usadas. Na sessão interativa, ele abre na aba Stats do gerenciador /plugin. No terminal, fora de uma sessão, você recebe o mesmo relatório em texto:

claude -p "/skill-doctor"

Cuidados:

• Exige Claude Code 2.1.252 ou mais novo.
• Não funciona pelo Remote Control (quando você controla do celular ou do navegador uma sessão que roda no computador) nem em sessões que pulam a busca de recursos novos. Rode no terminal da máquina onde a sessão roda. Se o comando não existir na sua sessão, confira a versão.
• O relatório não inclui as skills que já vêm com o Claude Code nem as da empresa.
• A documentação recomenda começar pelas skills que custam mais contexto.
• Nossa leitura: "nunca usada" vem do histórico de uso. Uma skill rara e importante pode aparecer na lista. Confira antes de mexer.

Decida o que fazer com cada uma

A configuração skillOverrides tem quatro estados para cada skill:

on

O Claude vê nome e descrição. Aparece no menu /.

name-only

O Claude vê só o nome. Aparece no menu /.

user-invocable-only

No menu aparece como user-only. O Claude não vê. Aparece no menu /.

off

O Claude não vê. Não aparece no menu /.

Skill que não aparece em skillOverrides fica como on.

O jeito mais simples é o menu, dentro de uma sessão:

/skills

Escolha a skill, aperte Espaço para trocar o estado e Esc para salvar. O menu grava a escolha em .claude/settings.local.json.

Se preferir escrever à mão, o formato é este (os nomes são exemplo). JSON é só um formato de arquivo de configuração: copie igual, com chaves, aspas e vírgulas. Se o arquivo .claude/settings.local.json já existir, não cole o bloco inteiro por cima: adicione só a parte "skillOverrides": { ... } dentro das chaves que já existem, separada das outras linhas por vírgula. Se o arquivo não existir, o caminho mais seguro é usar o menu /skills, que cria o arquivo sozinho.

{
  "skillOverrides": {
    "revisar-sql": "name-only",
    "testes-api": "off"
  }
}

Como escolher:

• Deixe em name-only para liberar espaço e manter a skill a um /nome-da-skill de distância. Nossa recomendação para skills raras que você ainda quer ter à mão.
• Use user-invocable-only quando o Claude pode deixar de ver a skill, mas você ainda quer chamá-la pelo menu.
• Use off para sumir de tudo. Chamar pelo nome completo devolve erro em vez de rodar. Também esconde a skill de quem usa o Claude Code pelo Remote Control ou pelo Agent SDK. Antes de usar off, confira se alguma outra skill ou rotina sua chama essa skill pelo nome. Na dúvida, use name-only. Nossa leitura: como a configuração só controla a visibilidade, a pasta da skill continua no disco. Remover de verdade seria apagar a pasta, e este guia não pede isso.

Atenção: skills de plugin não obedecem skillOverrides. Gerencie essas pelo /plugin.

Escreva a descrição com o uso principal no começo

Nas skills que ficam, a documentação recomenda pôr o caso de uso principal logo no início da descrição, porque cada descrição tem teto de 1.536 caracteres. Um exemplo (essa linha fica entre os dois traços --- no começo do SKILL.md, junto do campo name):

description: Revisa consultas SQL, procura erros e sugere melhorias. Use quando alguém pedir para revisar uma consulta.

Se precisar, aumente o orçamento

Se você usa muitas skills de verdade, dá para aumentar o orçamento da lista nas configurações. O exemplo abaixo dobra o teto para 2% da janela de contexto. Coloque essa linha dentro do seu arquivo de configurações, sem apagar o que já está lá:

{
  "skillListingBudgetFraction": 0.02
}

A documentação também cita a variável de ambiente SLASH_COMMAND_TOOL_CHAR_BUDGET, que fixa o orçamento num número de caracteres. Ela é para quem já usa variáveis de ambiente; se você não usa, ignore. Nossa leitura: um orçamento maior deixa mais descrições inteiras, mas a lista passa a ocupar mais espaço em toda mensagem. Nossa recomendação: enxugue antes de aumentar.

Resumo para guardar

1. Rode /doctor e veja quanto a lista ocupa.
2. Rode /skill-doctor e ache as skills nunca usadas.
3. No /skills, deixe as raras como name-only e desligue com off só as que você dispensa.
4. Ponha o uso principal no começo de cada descrição.
5. Só aumente o orçamento se ainda faltar espaço.

Mito x verdade

• Mito: "skill instalada é skill que funciona". Verdade: se a lista passa do orçamento, a descrição dela pode ser cortada, e o Claude pode não saber quando usá-la.
• Mito: "skill que eu não uso não pesa". Verdade: segundo a documentação, toda skill da lista ocupa espaço em toda mensagem.
• Mito: "desligar apaga a skill". Verdade: off só esconde. Nossa leitura: a pasta continua no disco. Para religar, troque o estado de volta no /skills ou apague a linha do arquivo de configurações.

Fonte

Claude Code Docs, Skills, lida em 13/11/2026. Conteúdo educativo e independente, sem vínculo com a Anthropic.