Claude Code Skills: como reduzir o custo de contexto

Agora já dá para identificar quais Claude Code skills cobram aluguel de contexto sem entregar trabalho útil — e cortar esse custo sem jogar fora instruções de que seus fluxos reais ainda precisam. O novo relatório /skill-doctor do Claude Code transforma a manutenção das skills: sai o palpite, entra um hábito operacional mensurável e reversível.

Em resumo: execute /skill-doctor, classifique cada skill não utilizada pelo impacto que faria se desaparecesse, aplique a mudança de visibilidade menos destrutiva e teste em uma sessão nova. Não comece apagando pastas. Uma skill que fica quieta por uma semana ainda pode ser justamente o recurso que protege um deploy ou uma resposta a incidentes.

O Claude Code 2.1.261, lançado em 4 de setembro de 2026, adicionou o /skill-doctor para mostrar quais skills carregadas não são usadas e quanto cada uma custa em contexto. Isso importa porque toda skill listada acrescenta um nome e, em geral, uma descrição a cada turno, mesmo quando o Claude nunca abre suas instruções completas.

Quanto contexto as Claude Code skills realmente consomem

O contexto das skills gera duas cobranças. Confundi-las leva a cortes ruins.

A primeira é o custo de listagem. Antes mesmo de você digitar qualquer coisa, o Claude recebe os nomes e as descrições das skills disponíveis para decidir qual delas combina com o pedido. Por padrão, a Anthropic limita essa listagem a 1% da janela de contexto do modelo, e o texto combinado de description e when_to_use de cada skill fica limitado a 1,536 caracteres por padrão.

A segunda é o custo de invocação. O conteúdo integral de SKILL.md só entra no contexto quando você ou o Claude invoca a skill. Depois de carregado, ele permanece na conversa nos turnos seguintes. Após uma compactação, o Claude Code pode reanexar até 5,000 tokens de cada skill invocada, com um orçamento combinado de 25,000 tokens para todas as skills reanexadas.

Pense na listagem como a vitrine de uma loja e no corpo da skill como o estoque levado até o balcão. Toda placa ocupa espaço na rua. O estoque ocupa muito mais, mas só aparece quando alguém pede.

Essa diferença muda a solução. Uma skill não utilizada com descrição longa gera um custo recorrente de listagem. Já uma skill invocada com frequência e com um corpo enorme cria um custo persistente na sessão. O /skill-doctor é mais eficaz contra o primeiro problema; uma boa arquitetura de skills resolve o segundo.

A conta cresce por turno, não por instalação

Uma skill ociosa não é um gasto único de configuração. O texto de sua listagem volta a ser apresentado conforme a conversa avança. Uma estimativa prática é:

Contexto evitável por dia = tokens de listagem não usados por turno × turnos do Claude por dia

Por exemplo: se o relatório encontrar 2,000 tokens de contexto não utilizado na listagem e seu trabalho gerar 40 turnos do modelo, serão 80,000 tokens de entrada apresentados ao longo do dia. É um exemplo, não um benchmark. O cache de prompts pode reduzir o valor cobrado pelo texto repetido, mas não faz o contexto desaparecer.

Para quem usa API ou provedores de nuvem, esses tokens extras pesam na fatura. Para assinantes, eles consomem a capacidade do plano e deixam menos espaço de trabalho antes da compactação. Segundo a Anthropic, implantações empresariais do Claude Code custam, em média, cerca de $13 por desenvolvedor por dia ativo e $150 a $250 por desenvolvedor por mês. O desperdício das skills é apenas uma parte dessa despesa, mas agora é uma das poucas que podem ser isoladas por nome.

E não é só o orçamento do modelo que sofre. A produtividade da equipe também cai. Uma listagem lotada pode levar o Claude Code a descartar as descrições das skills menos usadas. Isso poupa espaço, mas também dificulta a seleção automática dessas skills.

Fluxo seguro para cortar, repetir e restaurar

O fluxo mais seguro tem sete etapas.

1. Comece em uma sessão atualizada do terminal

Atualize para o Claude Code 2.1.261 ou uma versão posterior e confirme a versão instalada com claude --version. A referência da Anthropic informa que o /skill-doctor exige a versão 2.1.252 ou posterior; já a 2.1.261 é a versão do changelog que anunciou o comando.

Execute /skill-doctor no terminal da máquina que hospeda a sessão. Em uma sessão interativa, o relatório é aberto na aba Stats do gerenciador /plugin. No modo não interativo com -p, o resultado sai como texto, o que facilita salvá-lo para uma auditoria local. O Remote Control não consegue retornar esse relatório.

2. Registre o ponto de partida

Antes de mudar qualquer coisa, salve três dados: o custo total da listagem de skills, os maiores itens não utilizados e as skills ou plugins que pretende alterar. Rode também /context para ver a linha Skills após a aplicação do orçamento e /doctor para identificar os maiores responsáveis pela listagem.

Não converta a contagem de tokens diretamente em dinheiro sem conhecer o modelo, o comportamento do cache e os valores do contrato. Use tokens como unidade estável e calcule o custo financeiro separadamente.

3. Classifique os candidatos pelo custo de uma falha

Separe cada candidato em uma destas três categorias:

É aqui que o relatório exige critério. “Nunca invocada” mede frequência, não valor. Um extintor pode nunca ter sido usado e ainda assim merecer continuar por perto.

4. Prefira o controle menos destrutivo

Para skills locais, pessoais, de projeto ou sincronizadas, o menu /skills grava uma alteração reversível de skillOverrides em .claude/settings.local.json.

• Use name-only quando o Claude precisar saber que a skill existe, mas não necessitar da descrição completa na listagem.
• Use user-invocable-only quando quiser manter /skill-name disponível sem permitir seleção automática.
• Use off apenas quando nem você nem o Claude devam enxergá-la.
• Use on para restaurar o comportamento original.

Se a skill for sua, disable-model-invocation: true é a versão portátil, no nível do autor, de uma política restrita ao usuário. Essa opção remove a descrição da listagem do Claude, mas preserva a invocação direta.

Com skills de plugins, a regra muda: skillOverrides não tem efeito sobre elas. Desative o plugin sem desinstalá-lo usando /plugin disable plugin-name@marketplace-name e restaure-o com /plugin enable plugin-name@marketplace-name. Vale lembrar que um plugin também pode fornecer agentes, hooks, servidores MCP ou ferramentas de linguagem. Inspecione esses componentes antes de desligá-lo.

5. Reduza o corpo sem reduzir a capacidade

Se uma skill útil tiver um corpo grande, transforme SKILL.md em um cartão de roteamento e leve exemplos detalhados, referências de API e casos extremos para arquivos de apoio. A Anthropic recomenda manter SKILL.md abaixo de 500 linhas. Os arquivos de apoio só entram no contexto quando o Claude precisa deles, e scripts auxiliares podem ser executados sem que seu código-fonte seja colocado no prompt.

Logo no começo, deixe a tarefa, o gatilho, as regras inegociáveis e o mapa para os arquivos de apoio. Isso também protege a parte importante depois da compactação, quando apenas os primeiros 5,000 tokens de cada skill reanexada são preservados.

6. Teste em uma sessão nova

Alterar uma skill não apaga as instruções que já foram carregadas na conversa atual. Abra uma sessão nova, rode alguns prompts que deveriam acionar a skill e compare os resultados com os mesmos prompts quando ela estiver oculta. Meça primeiro o sucesso da tarefa; depois, os tokens.

A Anthropic recomenda comparações em sessões novas porque resíduos do contexto de autoria ou da própria skill podem esconder o que ela realmente acrescenta. Se alterações em plugins exigirem /reload-plugins, espere um custo em tokens na solicitação seguinte e, possivelmente, a reconstrução do cache de prompts quando o plugin expuser ferramentas MCP não adiadas.

7. Reverta as perdas e repita a auditoria

Se a qualidade cair, volte um passo: de off para user-invocable-only, de restrita ao usuário para name-only, ou de plugin desativado para ativado. Se a qualidade se mantiver, preserve a configuração mais enxuta e execute /skill-doctor outra vez depois de um período representativo de trabalho real.

Essa última rodada faz diferença. A meta não é ter a menor lista possível, e sim a lista mais barata que ainda encaminha corretamente os trabalhos recorrentes.

Quem mais se beneficia dessa otimização

Os casos de uso abaixo estão ordenados pelo provável impacto econômico.

1. Times de plataforma com uma configuração compartilhada do Claude Code

Um líder de plataforma com dezenas de desenvolvedores pode pedir a um grupo-piloto que exporte os relatórios locais do /skill-doctor, identificar skills que aparecem para todos mas não são acionadas por ninguém e mover fluxos opcionais para disponibilidade restrita ao usuário ou ao projeto. O ganho se multiplica a cada turno de cada desenvolvedor, enquanto o arquivo de restauração mantém o experimento reversível. Skills gerenciadas pela empresa não entram no relatório; portanto, esse método funciona como amostra local da frota, não como auditoria completa de políticas.

2. Times de engenharia que usam muitos plugins

Uma equipe pode instalar um plugin para uma única migração e manter suas skills, agentes, hooks e ferramentas MCP habilitados por meses. O /skill-doctor revela plugins sem uso recente, e o gerenciador permite desativá-los sem desinstalação. O ganho vai além da descrição da skill, porque um plugin ocioso pode adicionar vários componentes que ocupam contexto. O risco também é mais amplo: desligá-lo pode remover componentes úteis que não são skills.

3. Consultores que alternam entre stacks de clientes

Um consultor pode carregar globalmente skills de frontend, dados, ecommerce e infraestrutura, embora apenas um grupo seja adequado ao cliente atual. É possível manter perfis nomeados nas configurações locais, expor o conjunto relevante e deixar fluxos raros de segurança restritos à invocação manual. O resultado é um contexto inicial limpo para cada projeto, sem precisar reconstruir o kit de ferramentas toda segunda-feira.

4. Responsáveis por monorepos grandes

O Claude Code consegue descobrir skills aninhadas à medida que lê diretórios mais profundos, e elas permanecem disponíveis pelo restante da sessão. Quem mantém um monorepo pode auditar o ambiente depois de uma tarefa que atravessou vários pacotes, mover instruções específicas para o diretório aninhado correto e encurtar as descrições do nível raiz. O ganho aparece no roteamento: o trabalho de backend deixa de carregar um desfile de descrições de fluxos de frontend.

5. Equipes com comandos raros e de alto risco

Skills de deploy, rollback, migração de dados e incidentes podem passar semanas sem serem acionadas. Isso não significa que devam ser apagadas só porque o relatório as marcou como ociosas. Ao torná-las manuais, as descrições somem da listagem recorrente do Claude, mas o atalho exato /skill-name continua disponível. Assim, o contexto das sessões normais diminui sem que seja preciso recriar o runbook em plena emergência.

6. Autores de skills com instruções carregadas de referências

Um autor pode usar o relatório para localizar uma skill cara e então separar exemplos longos e especificações em arquivos de apoio. O arquivo principal vira um mapa de decisão conciso. O ganho é adiar o custo de contexto: os detalhes só chegam quando o trabalho alcança o caminho que precisa deles.

7. Desenvolvedores solo limitados pela assinatura

Quem trabalha sozinho talvez não veja redução direta em dinheiro, pois os planos Pro e Max incluem o uso na assinatura. O benefício é conseguir fazer mais dentro da mesma franquia e ter mais espaço antes da compactação. Combine o /skill-doctor com uma configuração enxuta do Claude Code e limpe a sessão ao trocar para um trabalho sem relação com o anterior.

Três produtos que valem a pena construir

O mercado de busca é maior do que a novidade da consulta sugere. Segundo a DataForSEO, claude code skills recebe 12,100 buscas mensais nos EUA e tem CPC de $8.26. As expressões mais específicas sobre redução do contexto das skills não retornaram sugestões. Isso aponta para uma oportunidade recente dentro de um mercado consolidado de skills, não para uma categoria independente já madura.

1. Skill Budget Guard, a aposta mais forte

Crie uma ferramenta local-first de CLI e CI que leia as skills do repositório, as configurações de visibilidade e um relatório exportado do /skill-doctor, mostrando quanto cada pull request altera o contexto. Times de plataforma pagariam por ela porque a ferramenta transforma a limpeza feita por uma pessoa em um orçamento repetível para toda a equipe.

O sinal de demanda é incomumente claro: claude code skills soma 12,100 buscas mensais, tem CPC de $8.26, e a Anthropic relata um custo empresarial médio do Claude Code entre $150 e $250 por desenvolvedor por mês. A menor versão vendável precisa de um parser local, um arquivo de orçamento versionado no repositório, uma GitHub Action e sugestões reversíveis, como “mover para uso manual” ou “separar as referências”.

O obstáculo real é o risco de plataforma. A Anthropic pode ampliar o /skill-doctor, e sua Analytics API já é gratuita para organizações elegíveis. A camada defensável está no histórico de políticas, na comparação entre repositórios e na prova de que a redução de contexto não prejudicou o sucesso das tarefas.

2. Project Skill Profile Switcher

Crie perfis nomeados como frontend, data, incident e release que apliquem alterações de skillOverrides junto com a ativação ou desativação de plugins e depois restaurem o estado anterior com um único comando. Consultores e equipes de monorepo formam o público comprador.

A DataForSEO registra 590 buscas mensais para best claude code skills, com intenção comercial e CPC de $11.91. O MVP inclui um manifesto, uma prévia das diferenças, gravações seguras nas configurações locais, comandos para plugins e um ponto de restauração. A fragilidade é a barreira competitiva baixa: os menus do próprio Claude Code já oferecem os controles básicos, e recarregar plugins pode gerar um custo de cache em um turno.

3. Skill Outcome Lab

Crie um executor de testes que envie o mesmo prompt realista por sessões novas, com a skill ativada e desativada, e compare a taxa de sucesso, o tempo e o uso de tokens. Autores de skills e equipes internas de capacitação pagariam para comprovar que cada instrução compensa o contexto que ocupa.

A DataForSEO registra 110 buscas mensais para claude code skills best practices, com intenção comercial e lances no topo da página entre $4.14 e $6.01. Um MVP útil precisa de prompts de teste, verificações do resultado esperado, isolamento em sessões novas e um relatório simples de antes e depois.

Há, porém, um obstáculo decisivo: o plugin oficial skill-creator da Anthropic já compara execuções com e sem uma skill. Esse recurso deve entrar no Skill Budget Guard, não virar uma empresa independente.

Se sua equipe distribui skills entre produtos ou agentes, esta comparação entre Notion Skills e Claude Skills API acrescenta o lado de governança à decisão.

O que o /skill-doctor não resolve

O /skill-doctor é um profiler do desperdício na listagem de skills, não um otimizador completo de custos do Claude Code.

• Ele não audita skills nativas nem gerenciadas pela empresa.
• Ele não remove o corpo de uma skill que já foi carregada na conversa atual.
• Ele não mede CLAUDE.md, histórico antigo da conversa, escolha do modelo, tokens de raciocínio, saídas verbosas de ferramentas ou sobrecarga de MCP.
• Ele não consegue retornar relatórios de uso pelo Remote Control.
• Ele não sabe dizer se uma skill rara evitou um erro caro.
• Ele não torna gratuito o contexto em cache. O preço do cache e o espaço ocupado no contexto são questões distintas.

Não comece reduzindo skillListingBudgetFraction. Quando a listagem excede seu orçamento, o Claude Code mantém os nomes, mas descarta descrições a partir das skills menos usadas. Isso pode reduzir o texto da listagem ao mesmo tempo que diminui a chance de a skill certa ser acionada. Remova ou oculte deliberadamente as entradas de pouco valor.

Outro erro é desinstalar plugins à primeira vista. Primeiro desative, depois teste; só então desinstale, quando tiver certeza de que os demais componentes do plugin são desnecessários.

A ação para a próxima segunda-feira

Escolha um repositório real e um desenvolvedor que use o Claude Code intensamente. Execute /skill-doctor, registre os cinco maiores itens não utilizados e altere somente dois: coloque um fluxo raro em modo manual e desative um plugin realmente irrelevante. Abra uma sessão nova, repita três tarefas normais e restaure qualquer item que mude o resultado. Assim, até sexta-feira você terá uma política defensável de economia de contexto, não apenas uma configuração mais organizada que silenciosamente piorou o agente.

Como fazer o Claude Code usar menos contexto?

Execute /skill-doctor para encontrar o custo de skills não utilizadas na listagem, use /context para ver a distribuição geral, oculte skills irrelevantes, deixe fluxos raros em modo manual, mova referências longas para arquivos de apoio e use /clear entre tarefas sem relação entre si.

Como reduzir o custo do Claude Code?

Comece reduzindo o contexto recorrente. Depois, cuide da escolha do modelo, das sessões longas, das configurações de raciocínio, das saídas verbosas de ferramentas e dos servidores MCP sem uso. O /skill-doctor cobre apenas a parcela da conta ligada às skills.

As skills do Claude Code são gratuitas?

A documentação de skills da Anthropic não indica uma cobrança separada por um SKILL.md local, mas o nome e a descrição podem consumir contexto a cada turno, e o corpo completo passa a ocupar contexto depois da invocação. Usuários da API pagam conforme o uso de tokens; assinantes consomem a franquia incluída.

Como compactar o contexto do Claude Code?

Use /compact quando precisar manter a continuidade de uma tarefa longa e /clear ao mudar para um trabalho sem relação com o anterior. O corpo de skills invocadas pode ser reanexado após a compactação, com limite de 5,000 tokens por skill e 25,000 tokens no total.

Devo limpar o contexto no Claude Code?

Sim, ao passar para uma tarefa sem relação com a anterior. Em um teste de redução de skills, uma sessão nova é importante porque o corpo já carregado na conversa antiga pode esconder o efeito da desativação.

Se você quer um fluxo mensurável de governança de skills para sua equipe de engenharia, conheça os sistemas de IA em produção.