/skill-doctor: identificar os skills que custam contexto

Lanças o Claude Code, ainda não pediste nada, e uma parte do contexto já se foi. Na instalação medida aqui, estão carregados 117 skills pessoais, 108 nunca foram invocados, e a sua listagem volta a sair em cada turno de conversa.

O que mostra exatamente o /skill-doctor

O comando chegou com o Claude Code 2.1.261, publicado a 4 de setembro de 2026. A nota de lançamento anuncia-o numa linha: mostra quais os skills carregados que continuam por usar e o que custam em contexto, para que os possas podar.

A documentação precisa o âmbito. O relatório cobre os skills da tua sessão, à exceção dos skills incluídos no Claude Code e dos skills empresariais. Assinala os que nunca foram invocados, indica onde os desativar, e lista ainda os plugins que não usaste recentemente. Em sessão interativa, abre-se no separador Stats do gestor /plugin, em modo não interativo, com -p, o Claude Code imprime-o em texto.

Duas condições a conhecer antes de experimentar. É preciso o Claude Code 2.1.252 ou mais recente. E a partir do Remote Control, no telemóvel ou no navegador, o comando recusa-se a responder: devolve Skill usage reports are not available on this connection. Executa-o no terminal da máquina que aloja a sessão.

Porque é que um skill nunca invocado custa contexto?

Porque um skill carrega em três tempos. O standard aberto Agent Skills chama a isto divulgação progressiva: no arranque, o agente lê apenas o nome e a descrição de cada skill, quando uma tarefa corresponde a essa descrição, lê o corpo do SKILL.md, só abre os ficheiros anexos se precisar deles. O mecanismo está detalhado no nosso guia do formato SKILL.md.

Já o primeiro nível é pago a cada turno de conversa. A documentação do Claude Code é explícita: cada skill da listagem soma ao contexto em cada turno, quer o Claude o use quer não. E essa listagem tem um orçamento em caracteres que vale 1% da janela de contexto do modelo. Para lá disso, o Claude Code encurta as descrições para caber no orçamento, arriscando eliminar justamente as palavras-chave que acionam o skill certo.

Ter demasiados skills custa portanto tokens, e degrada de passagem a ativação daqueles que realmente querias.

O relatório, sobre 117 skills

Numa instalação que carrega 117 skills pessoais, o comando dá uma linha por skill e uma frase de conclusão. O modo não interativo imprime-o em texto simples, o que permite guardá-lo:

claude -p '/skill-doctor'

Skills loaded this session

  skill                      source        context  7d tokens   uses  last used
  ab-test-setup              userSettings     ~270          -     0×  never
  cold-email                 userSettings     ~230          -     0×  never
  …
  seo-onpage                 userSettings     < 20          -     0×  never
  …
  seo-search-console         userSettings     ~190       1.2m     1×  6 days
  seo-keyword-research       userSettings     ~160      15.2m     1×  3 days
  video                      userSettings     ~210     548.4k     4×  3 days
  wp-article-thumbnails      userSettings     ~190      28.5m     8×  today

  context = this skill's one-line listing in the system prompt, included every turn
  (dash = not in the current listing, costs nothing; full SKILL.md loads only when it runs)
  7d tokens = tokens attributed to the skill over the last 7 days of sessions on this machine

108 skills loaded but never invoked. Each one adds to the system prompt every turn.
Disable in /skills, or remove from .claude/skills.

Quatro colunas suportam a decisão. context dá o peso da linha de listagem, a que volta a sair em cada turno: de menos de 20 a 360 tokens por skill aqui, cerca de 8 800 no total. 7d tokens conta o que o skill consumiu realmente em sete dias, e mostra um travessão quando não consumiu nada. uses e last used dizem o resto: dos 117 skills carregados, 108 nunca foram invocados, e só cinco consumiram alguma coisa durante a semana.

Medir sem o comando

Numa versão anterior à 2.1.252, ou simplesmente para cruzar a ordem de grandeza, o nível 1 mede-se diretamente nos ficheiros, já que é feito apenas de frontmatter YAML.

# Peso do nível 1: nome + descrição de cada skill pessoal
awk 'FNR==1{f=0;p=0}
     /^---[[:space:]]*$/{f++; next}
     f!=1{next}
     /^[A-Za-z_-]+:/{p=($1=="name:"||$1=="description:"||$1=="when_to_use:")}
     p{c+=length($0)}
     END{printf "%d skills, %d caracteres, ~%d tokens\n", ARGC-1, c, c/4}' \
  ~/.claude/skills/*/SKILL.md
# 117 skills, 45715 caracteres, ~11428 tokens

A estimativa «um token por cada quatro caracteres» dá 11 428 tokens onde o relatório conta cerca de 8 800: peca por excesso, o que chega perfeitamente para decidir. O mesmo cálculo sobre ~/.codex/skills dá 7 skills e cerca de 590 tokens: neste ponto, os dois agentes não jogam na mesma liga, como mostra a comparação entre o Codex e o Claude Code.

O segundo comando dá a classificação. Basta essa para decidir.

awk 'FNR==1{if(NR>1) print c, d; c=0; f=0; p=0; n=split(FILENAME,t,"/"); d=t[n-1]}
     /^---[[:space:]]*$/{f++; next}
     f!=1{next}
     /^[A-Za-z_-]+:/{p=($1=="name:"||$1=="description:"||$1=="when_to_use:")}
     p{c+=length($0)}
     END{print c, d}' ~/.claude/skills/*/SKILL.md | sort -rn | head -5
# 1101 elevenlabs-game-music
# 1078 elevenlabs-game-sfx
# 864 directory-submissions
# 855 customer-research
# 831 ab-test-setup

Estes 117 ficheiros SKILL.md totalizam 778 142 caracteres, ou seja, cerca de 194 500 tokens, e a listagem representa apenas 6% disso. A divulgação progressiva está portanto a fazer o seu trabalho, e o que pesa no dia a dia continua a ser o número de skills. Ainda assim, 45 715 caracteres estão na ordem de grandeza do orçamento da listagem: impossível saber sem o /context se as minhas descrições já estão a ser cortadas.

Cortar o que não serve

Abre /skills, seleciona um skill, prime Espaço para percorrer os estados, depois Esc para gravar. O próprio menu escreve a definição skillOverrides em .claude/settings.local.json. Existem quatro estados.

name-only é o bom compromisso para um skill que tu próprio invocas de vez em quando: o nome mantém-se na listagem, a descrição deixa de pesar. off serve para os que tinhas instalado «só para ver».

Atenção ao caso dos plugins: os skills trazidos por um plugin não são abrangidos pelo skillOverrides. É preciso desativar o plugin a partir de /plugin e depois executar /reload-plugins ou reiniciar a sessão para que os seus skills sejam descarregados.

Verificar se o corte serviu

A linha Skills de /context dá o tamanho da listagem depois de aplicado o orçamento: é exatamente o que o modelo recebe. Regista o valor, corta, reinicia a sessão, regista de novo. Se não mudar apesar de teres desativado dez skills, é provavelmente porque já estavas no limite e o Claude Code truncava as tuas descrições, ainda assim, o corte terá ganho em precisão de ativação.

Quanto à fatura, /cost e /usage continuam a ser as referências, mas não esperes um ganho grande: o verdadeiro benefício sente-se em contexto, não em euros. Se procuras poupanças de outra ordem de grandeza, é o encaminhamento das leituras de ficheiros que deves olhar, como no relato de experiência da Spotify sobre os hooks.

Duas definições permitem alargar o orçamento em vez de cortar: skillListingBudgetFraction (por exemplo, 0.02 para 2%) e a variável de ambiente SLASH_COMMAND_TOOL_CHAR_BUDGET, que fixa um número de caracteres. Alargar desloca o problema: o contexto ganho nos skills perde-se noutro lado.

A reter

• Um skill nunca invocado custa na mesma o nome e a descrição em cada turno: é o nível 1 da divulgação progressiva.
• O /skill-doctor exige o Claude Code 2.1.252 ou mais recente, e aparece no separador Stats do gestor /plugin.
• O relatório conta aqui 117 skills carregados, 108 nunca invocados, cerca de 8 800 tokens de listagem. Duas linhas de awk sobre ~/.claude/skills/*/SKILL.md dão a mesma ordem de grandeza sem o comando.
• Corta-se com /skills e a tecla Espaço, os skills de plugin cortam-se a partir de /plugin, depois /reload-plugins.
• Verifica-se na linha Skills de /context, que reflete o orçamento realmente aplicado.