Índice

"Instalar Skills demais sufoca o contexto." Ouve-se isso o tempo todo. Metade está certa e metade está errada.

Segundo a documentação oficial, a listagem de Skills consome um orçamento fixo de 1% da janela de contexto do modelo, e por mais Skills que você acrescente, é ali que ela para. Ela não cresce. O que acontece no lugar disso é que as Skills deixam de ser chamadas. Quando a listagem transborda o orçamento, o Claude Code descarta descrições a partir das Skills menos invocadas e mantém apenas os nomes. Uma Skill que perdeu a descrição deixa de se conectar com aquilo que você pediu.

Não aparece erro. Nada fica mais lento. A Skill simplesmente deixa de ser usada, em silêncio. Este artigo mostra como enxergar o que de fato ocupa o seu contexto, com números em vez de suposições, e o que cortar primeiro depois de olhar.

O que realmente acontece quando você adiciona mais Skills

O orçamento da listagem é fixo em 1% da janela de contexto. O que transborda custa descrições, não tokens

DENTRO DO ORÇAMENTO
Todas mantêm a descrição

Nome e descrição entram por inteiro. Mesmo que o seu pedido use outras palavras, as palavras-chave ainda encontram a Skill

LOGO APÓS TRANSBORDAR
As descrições caem na ordem de uso

As Skills mais usadas mantêm o texto completo. As que você aciona raramente perdem a descrição primeiro

SÓ O NOME
Existe, mas nunca é escolhida

Continua na listagem. Mas nada diz para que ela serve, então ela não se liga a nenhum pedido

Fonte: documentação oficial do Claude Code, "Skills"

1. As Skills não crescem para sempre: a listagem para no orçamento de 1%

Para que o Claude saiba quais Skills estão disponíveis, o Claude Code carrega no contexto uma listagem com os nomes e as descrições das Skills. É aí que o orçamento passa a pesar. A documentação oficial afirma que "a listagem sempre inclui todos os nomes de Skills, mas, quando há muitas, o Claude Code encurta as descrições para caber no orçamento de caracteres da listagem" e fixa esse orçamento em "1% da janela de contexto do modelo".

Com números fica mais claro. Em um modelo com janela de contexto de um milhão de tokens, a listagem de Skills recebe 1% disso. Os 99% restantes existem para a conversa, os arquivos e os resultados das ferramentas. Instale 50 Skills ou instale 100: esse 1% não se move.

Então para onde vai o excedente? Para as descrições, que encolhem. A documentação chega a explicitar a ordem do corte: "quando a listagem transborda, o Claude Code descarta as descrições começando pelas Skills menos invocadas, para que as mais usadas mantenham o texto completo".

É esse o ponto mais assustador na prática. Quem paga a conta são as Skills que você usa só de vez em quando, e elas costumam ser exatamente aquelas de que você precisa depois de já ter esquecido delas. Um procedimento de migração trimestral, uma rotina de release executada poucas vezes por ano: são justamente essas que perdem a descrição primeiro.

O orçamento é ajustável. Escreva em skillListingBudgetFraction a fração da janela de contexto (por exemplo, 0.02 para 2%) e a listagem ganha mais espaço. Há também um limite por Skill: 1.536 caracteres somando a descrição e as condições de acionamento, por padrão (alterável em skillListingMaxDescChars). Se a documentação recomenda "colocar os usos principais logo no início", é porque esse limite corta pelo fim.

2. São três ferramentas para medir, e cada uma tem um papel

Para trocar o palpite por números existem três ferramentas. O /context já existe há algum tempo, mas a linha de cache de prompt do /usage chegou na v2.1.251 (28 de agosto de 2026) e o /skill-doctor, na v2.1.252 (31 de agosto). Como fazem coisas diferentes, vale conhecer as três.

/context
O que está carregado agora

Detalha o que ocupa a janela. A linha Skills informa o tamanho depois de aplicado o orçamento, então bate com o que o modelo realmente recebe

/usage
Quanto isso consumiu

Tokens e custo da sessão, mais o estado do cache de prompt e a distribuição de uso por Skill, subagente e servidor MCP

/skill-doctor
Quais se pagam

Mostra o custo e a frequência de chamada de cada Skill e marca as que nunca foram invocadas. Indica até onde cortar

Há uma ordem nisso. Veja o detalhamento com o /context, confirme quanto aquilo custou de fato com o /usage e identifique os candidatos ao corte com o /skill-doctor. Se você entrar pelo outro lado, apaga coisas sem nenhuma evidência por trás da decisão.

Sobre a linha Skills do /context, a documentação registra até o comportamento antigo: antes da v2.1.196 ela contava o número de caracteres de todas as descrições e podia exibir um valor várias vezes maior do que o orçamento configurado. Se a sua impressão de que "as Skills estão comendo o contexto" vem de uma lembrança antiga, é possível que aquele número já fosse maior do que a realidade.

3. Faça o Claude Code apontar as Skills que ninguém usa

O /skill-doctor está disponível a partir do Claude Code v2.1.252 (31 de agosto de 2026). A descrição oficial é que "você pode ver o custo e a frequência de chamada de cada Skill e decidir quais cortar". Há quatro pontos do comportamento que vale ter em mente.

O que o /skill-doctor pressupõe

  • Em uma sessão interativa, ele abre a aba Stats do gerenciador /plugin. No modo não interativo, com -p, a saída vem em texto
  • Skills incluídas de fábrica e distribuídas pela organização ficam de fora. Só aparece o que você mesmo adicionou
  • As Skills que nunca foram invocadas recebem uma marca, junto com o lugar em que seriam cortadas
  • Ele não roda por controle remoto a partir de um celular ou de um navegador, e devolve erro

Basta ter uma coisa em mente ao ler o resultado para não se perder. "Nunca invocada" não é sinônimo de "desnecessária". Como mostrou a seção anterior, uma das razões para uma Skill nunca ser chamada é que a descrição dela foi cortada e ninguém consegue encontrá-la.

Antes de cortar, o caminho seguro é chamar a Skill pelo nome. Se ela funciona quando nomeada, mas nunca é escolhida automaticamente, ela não é desnecessária: a descrição está perdendo para o orçamento. A solução não é apagar, e sim reescrever a descrição (usos principais no início) ou aumentar o orçamento.

4. O erro de cache pesa mais do que o tamanho

Daqui em diante o assunto sai do eixo do "tamanho" do contexto. Duas conversas do mesmo tamanho podem gerar cobranças completamente diferentes conforme o cache esteja funcionando ou não.

Desde o Claude Code v2.1.251 (28 de agosto de 2026), o painel de sessão do /usage traz uma linha de cache de prompt. Este é o exemplo que a documentação apresenta.

Prompt cache (main):   14 requests · 91% of input tokens from cache ·
2 misses (last 6m 10s ago, 310.2k tokens re-cached) ·
1 expected rebuild (compaction or tool-result clearing) ·
warm (1h TTL, last activity 40s ago)

Na leitura, três pontos importam.

MISSES
5% e 2.000 tokens

Conta como erro a requisição que releu acima desse volume de conteúdo que o cache poderia ter servido. Uma troca pequena não vira erro

EXPECTED REBUILD
O que você mesmo quebrou

Quando o próprio Claude Code reescreve a conversa por compactação ou pela limpeza de resultados antigos de ferramentas, isso é contado à parte como reconstrução esperada, não como erro

WARM / COLD
Dentro ou fora da validade

Se o trecho inicial já em cache continua vivo. Quando ele esfriou, a linha mostra por quanto tempo você ficou parado

A partir da v2.1.260, quando há uma explicação provável para um erro recente, a linha diz qual é (por exemplo, likely cause: tool definitions changed). Adicionar um servidor MCP ou trocar uma Skill reescreve algo perto do começo da conversa, o que invalida o cache de tudo o que vem depois. É por isso que mexer na configuração antes de começar o trabalho sai barato.

Uma ressalva. Essa linha olha apenas para a conversa principal, e não inclui os subagentes. Se o seu fluxo empurra o processamento pesado para subagentes, esses números não são o quadro completo.

5. O cache nem sempre dura uma hora

Este ponto vai direto para a fatura e mesmo assim é pouco conhecido. A validade do cache de prompt muda conforme o seu contrato e a situação.

Assinatura
1 hora

Você para para almoçar e, na volta, o cache ainda está vivo

Depois de entrar nos créditos de uso extra, ou via chave de API e provedores de nuvem
5 minutos

Basta se afastar um pouco para esfriar. A mensagem seguinte relê o contexto inteiro

Fonte: documentação oficial do Claude Code, "Manage costs effectively" (as regras de validade do cache)

A documentação afirma que "a validade é de uma hora na assinatura e cai para cinco minutos assim que você passa a consumir créditos de uso (usage credits); por chave de API ou por provedor de nuvem, o padrão são cinco minutos". No instante em que você bate no limite e entra no uso extra, a validade do cache vira um doze avos do que era. Ou seja, "depois de atingir o limite" não muda só o preço unitário: muda também o modo como o cache funciona. A documentação ainda indica definir você mesmo o TTL como forma de manter a validade de uma hora enquanto usa os créditos extras.

6. O MCP é carregado sob demanda por padrão, e mesmo assim a CLI é mais leve

A ideia de que "instalar servidores MCP come o contexto" também parte de pressupostos que mudaram. Segundo a documentação, as definições de ferramentas do MCP são carregadas sob demanda por padrão e, até que o Claude use uma ferramenta específica, só os nomes das ferramentas e a descrição do servidor entram no contexto.

Ainda assim, a documentação diz que ferramentas de linha de comando como gh, aws, gcloud e sentry-cli continuam sendo mais eficientes em contexto. A razão é simples: uma CLI não acrescenta listagem de ferramentas nenhuma. O Claude pode executar o comando diretamente, então nem os nomes precisam ser carregados.

A conclusão prática vem daí. Se uma CLI dá conta do mesmo trabalho, o motivo para escolher o MCP deve estar fora do orçamento de contexto (autenticação centralizada, resultados estruturados, controle de permissões). Um servidor instalado porque "parecia útil" é candidato ao corte, e o /mcp mostra a lista.

7. O que entra em todo turno: o CLAUDE.md e a própria conversa

Skills e MCP entram condicionalmente, mas duas coisas entram sem condição, sempre.

Uma delas é o CLAUDE.md. Ele é carregado no contexto quando a sessão começa, então os procedimentos de fluxo de trabalho que você escreveu ali ficam ocupando espaço o tempo todo, inclusive enquanto você trabalha em algo sem relação nenhuma. Como remédio, a documentação recomenda "mover para Skills as instruções detalhadas de fluxos específicos" e vai até uma meta concreta: "mantenha o CLAUDE.md abaixo de 200 linhas, só com o essencial". O raciocínio é que uma Skill só é carregada quando chamada, de modo que o mesmo conteúdo deixa de ser um peso permanente.

A outra é a própria conversa. A explicação oficial é precisa: "o Claude Code envia a conversa inteira a cada requisição e, toda vez que o Claude usa uma ferramenta, envia outra requisição carregando aquele resultado". Por isso uma pergunta de uma linha em uma sessão que ficou aberta o dia todo gera uso equivalente à conversa inteira. O cache derruba o preço unitário, mas não o zera.

É exatamente aqui que entra a escolha entre /clear e /compact. A documentação diz que "o /compact lê a conversa que vai resumir, então compactar um contexto grande é, em si, uma requisição grande; se o que você quer é recomeçar em vez de continuar, o /clear não custa nada". "Compactar por precaução" não é de graça. A decisão sobre o momento de apertar é tratada em detalhe em Devo rodar o /compact do Claude Code em intervalos fixos?

8. O uso avança sem que você faça nada

"Eu só saí da mesa e o uso subiu." Há razões concretas para isso, e a documentação as enumera. Todas têm o mesmo formato: um novo turno começa e envia o contexto inteiro mesmo com a sessão ociosa.

O que faz o uso avançar enquanto você está ocioso

  • Tarefas agendadas — disparam no intervalo definido mesmo com a sessão parada, e cada disparo envia o contexto inteiro
  • Mensagens de outras sessões — são entregues como um novo turno enquanto você está ocioso. Coloque crossSessionInbound em hold para deixá-las na fila
  • Verificações de progresso das metas — enquanto há trabalho em segundo plano, sobe um turno de verificação, até três vezes entre um prompt e outro
  • Cada integrante de uma equipe de agentes — continua consumindo tokens até terminar
  • Expiração do cache — a primeira mensagem depois da pausa relê o contexto inteiro

Para as equipes de agentes há até um multiplicador concreto. A documentação diz que "uma equipe de agentes usa cerca de 7 vezes mais tokens que uma sessão normal quando os integrantes rodam em modo de planejamento". Como cada integrante tem a própria janela de contexto, o consumo cresce quase na proporção do número de pessoas. A recomendação oficial é igualmente direta: use Sonnet para os integrantes, mantenha a equipe pequena e desligue-a quando o trabalho acabar.

Como referência, a documentação coloca a média das implantações corporativas em cerca de US$ 13 por pessoa por dia útil, ou de US$ 150 a US$ 250 por mês, e diz que 90% dos usuários ficam abaixo de US$ 30 por dia útil. Se os seus números estão bem fora dessa faixa, é provável que um dos itens acima esteja em jogo.

9. Depois de medir, o que cortar primeiro

Com os números na mão, comece por onde o efeito é maior. Reordenando as medidas que a documentação lista, da que dá retorno mais rápido para a mais lenta, chega-se a isto.

AGORA E DE GRAÇA
/clear ao mudar para um trabalho sem relação

O contexto antigo continua sendo cobrado em todas as mensagens seguintes. Rode /rename antes de limpar e você volta depois com /resume

ARRUMAR A CONFIGURAÇÃO UMA VEZ
Deixar o CLAUDE.md abaixo de 200 linhas

Mova para Skills os procedimentos de tarefas específicas. Menos coisa fica carregada o tempo todo, e vale para todas as sessões

ESTREITAR A SAÍDA
Hooks e subagentes

Em vez de mandar ler um log de 10.000 linhas, deixe um hook devolver só as linhas que interessam. Prenda o processamento verboso dentro de um subagente

BAIXAR O PREÇO UNITÁRIO
Ajustar o modelo e o esforço à tarefa

Para a maior parte da programação, o Sonnet basta. Em trabalhos simples, reduza o raciocínio com /effort

A ordem tem sentido. A primeira medida funciona já hoje e ainda é de graça. A segunda você arruma uma vez e ela vale para todas as sessões. A terceira e a quarta são questão de configuração e de hábito, então demoram um pouco para aparecer. Apagar Skills não está no topo porque, como mostraram as seções anteriores, raramente é esse o maior fator.

O que não muda é que você mede antes de mexer. O /usage oficial marca qualquer comportamento que responda por 10% ou mais do uso recente (contexto longo demais, erros de cache e assim por diante). Cortar algo que não recebeu marca nenhuma não vai mudar o que você sente.

FAQ

Q1. Quantas Skills dá para ter com segurança?
Não há limite de quantidade. O que pesa é caberem no orçamento de caracteres da listagem, que é 1% da janela de contexto. As mesmas dez Skills transbordam com descrições longas e cabem com descrições curtas. Ler a linha Skills do /context e rodar o /skill-doctor é mais preciso do que contar.

Q2. Posso apagar uma Skill que nunca foi invocada?
Chame-a pelo nome antes de apagar. Se ela funciona quando nomeada, mas nunca é escolhida automaticamente, ela não é desnecessária: a descrição está perdendo para o orçamento. Nesse caso a solução não é apagar, e sim reescrever a descrição (usos principais no início) ou aumentar o orçamento.

Q3. Apertar o /compact com frequência sai mais barato?
Não. A compactação lê a conversa que vai resumir, então, em um contexto grande, ela própria é uma requisição grande. Quando você não precisa de continuidade, o /clear é mais barato (custo zero) e mais confiável.

Q4. Qual taxa de acerto do cache eu deveria buscar?
A documentação não indica uma nota de corte, então observe a variação, e não o valor absoluto. Se a taxa caiu enquanto você trabalha do mesmo jeito, é provável que você tenha mudado a configuração (MCP, Skills, definições de ferramentas) pouco antes. A partir da v2.1.260, a linha exibe o palpite dela sobre a causa.

Q5. Devo reduzir o número de servidores MCP?
As definições de ferramentas são carregadas sob demanda por padrão, então o peso de apenas manter um instalado é menor do que era. Ainda assim, se uma CLI como o gh dá conta do mesmo trabalho, a CLI é mais leve (não acrescenta listagem de ferramentas alguma). Servidores que você não usa podem ser desligados com o /mcp.

Q6. Usar subagentes economiza contexto?
Economiza. A documentação também recomenda entregar o processamento verboso (rodar testes, buscar documentação, digerir logs) a um subagente, deixando os detalhes no contexto dele e devolvendo só um resumo. Só que a linha de cache do /usage olha apenas para a conversa principal, então, em um fluxo centrado em subagentes, aqueles números não são o quadro completo.

Q7. O /skill-doctor não funciona aqui.
É preciso Claude Code v2.1.252 ou posterior. Além disso, ele não roda por controle remoto a partir de um celular ou de um navegador, onde devolve erro. Em uma sessão interativa, ele abre a aba Stats do gerenciador /plugin, então, se você quer saída em texto, rode-o no modo não interativo com -p.

Fontes

  • Claude Code Docs — Skills (o orçamento da listagem de 1% da janela de contexto, o limite de 1.536 caracteres da descrição, a ordem do corte ao transbordar, a linha Skills do /context)
  • Claude Code Docs — Manage costs effectively (o detalhamento do /usage, a linha de cache de prompt, a definição de erro, a validade do cache, as 200 linhas do CLAUDE.md, as cerca de 7 vezes das equipes de agentes, o custo médio corporativo)
  • Claude Code Docs — Slash commands (o comportamento e os pré-requisitos do /skill-doctor)
  • Claude Code Changelog (v2.1.251 a linha de cache, v2.1.252 o /skill-doctor, v2.1.260 a estimativa de causa, v2.1.261 a configuração de limite de saída)