Quantas skills dá para deixar ativas ao mesmo tempo sem atrapalhar o Claude?

Fala aí, beleza? Instalar uma skill leva dois minutos, e é justamente aí que mora a pegadinha

O custo não aparece na instalação

Ele aparece semanas depois, quando o Claude começa a chamar a skill errada, ou chama a certa e age como se não soubesse o que ela faz

E a pergunta que todo mundo faz nessa hora é "qual é o limite de skills?"

A resposta honesta: a documentação não crava número nenhum

O que ela crava é um orçamento de contexto pra listagem de skills e um jeito de medir o quanto a sua configuração já ocupa

Bora entender COMO isso funciona por dentro, porque o cálculo muda bastante depois que você sacar o mecanismo 🙂

Como o Claude decide qual skill usar (e por que isso muda o cálculo):

Skill é uma pasta com um arquivo SKILL.md dentro, composto por frontmatter YAML (os metadados) e um corpo em Markdown (as instruções)

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Simples assim

O detalhe importante é o que entra no contexto, e QUANDO entra

A documentação de Agent Skills chama isso de divulgação progressiva, e são três estágios:

1. no começo da sessão, só o name e a description de cada skill instalada vão pro system prompt
2. o SKILL.md completo só entra no contexto quando a skill fica relevante
3. arquivos extras empacotados dentro da pasta só entram quando são efetivamente lidos

Se liga na consequência disso, porque é contraintuitivo

O tamanho da sua skill não pesa

Você pode empacotar um monte de arquivo de referência dentro dela que aquilo não consome contexto até ser acessado, não existe limite prático pro conteúdo empacotado

O que pesa é a listagem de metadados, aquele bloco com nome e descrição de tudo que está instalado, que o modelo vê a cada turno

Ou seja: 30 skills enxutas podem custar menos que 8 skills com descrição inchada

Onde as skills vivem:

No Claude Code você tem três vias

~/.claude/skills/     # pessoal, vale em todos os seus projetos
.claude/skills/       # do projeto, versionado junto com o time

E plugins como terceira via de distribuição

Todas competem pelo mesmo espaço na listagem, beleza? Não existe "essa aqui é de graça porque é pessoal"

A description é o critério de escolha, não a documentação da skill:

Essa é a parte que quase todo mundo trata como enfeite

A doc oficial de boas práticas é bem direta: a description é o que decide a seleção da skill certa entre potencialmente mais de 100 skills disponíveis

E ela precisa dizer duas coisas, não uma: o que a skill faz E os gatilhos específicos de quando usar

Se você conhece aquele padrão de escrever docstring de função, é bem parecido

A diferença é que aqui a docstring é lida por um modelo que precisa ESCOLHER entre dezenas de opções parecidas, no meio de um pedido seu que provavelmente está mal formulado haha

Sinais de que sua configuração de skills passou do ponto:

Não dá pra contar skill no dedo e decidir

Dá pra ler sintoma

O Claude invoca a skill mas parece não saber o que ela faz:

Causa: o Claude Code reserva uma fração fixa da janela de contexto pra listagem de skills, controlada por skillListingBudgetFraction, que vem com padrão 0.01 (1% da janela)

Quando a listagem estoura esse orçamento, ele derruba as descrições das skills menos usadas e mantém só o nome delas

O modelo ainda consegue invocar, só que ficou cego pro que a skill faz

Daí aquele comportamento estranho de chamar a coisa certa e usar errado

Solução: medir, não adivinhar

/doctor te dá uma estimativa do custo de contexto da listagem e mostra quais são os maiores contribuintes

/context reporta o tamanho da listagem JÁ depois do orçamento aplicado, ou seja, o que o modelo realmente recebeu

A diferença entre os dois é a sua conta de quanto foi cortado

Duas skills disputam o mesmo pedido:

Causa: descrições sobrepostas, sem gatilho específico

Duas skills que dizem "ajuda com testes" e "cuida da suite de testes" são, do ponto de vista do modelo, a mesma coisa escrita duas vezes

Solução: a description precisa carregar o gatilho

Não "cuida de banco de dados", e sim o que faz mais em qual situação isso deve ser acionado

Quanto mais específico o gatilho, menos empate

E vale o aviso: não existe regra documentada de desempate pra quando duas descrições casam com o mesmo pedido, então esse é um problema pra resolver na escrita, não na configuração

A skill é chamada na hora errada:

Causa: descrição genérica ou escrita em segunda pessoa

A doc recomenda terceira pessoa sempre, porque a description é injetada no system prompt e ponto de vista inconsistente atrapalha a descoberta

O exemplo que ela mesma dá:

# ruim
description: Você pode usar isto para processar arquivos Excel

# bom
description: Processa arquivos Excel e gera relatórios

Parece frescura de estilo

Não é, isso muda a taxa de acerto da seleção

Uma skill com efeito colateral disparou sozinha:

Deploy, envio de mensagem, essas coisas que você não desfaz com ctrl+z

Causa: a invocação pelo modelo está habilitada, que é o padrão

Solução: disable-model-invocation: true no frontmatter do SKILL.md

Com ele, só o usuário invoca a skill

E tem um bônus de contexto: a description dessa skill não fica no contexto, e a skill completa só carrega quando você chama

É o mesmo raciocínio de IA escrevendo teste e código: quando ela decide sozinha as duas pontas, você perde o ponto de verificação

Como prevenir:

Trate cada description como verba de contexto, não como documentação da sua skill

Documentação vai no corpo do SKILL.md, que só carrega quando precisa

Na description entra só o que o modelo precisa pra decidir se aquilo serve ou não pro pedido atual

Como medir e enxugar sua lista de skills:

Passo a passo curto, tudo com o que dá pra verificar na própria ferramenta

1. Rode /doctor

Ele dá a estimativa do custo de contexto da listagem de skills e mostra os maiores contribuintes

Começa por aí, é a foto de quem está comendo seu orçamento

O erro comum deste passo: olhar a lista de contribuintes e sair apagando arquivos de dentro da pasta da skill

Não adianta nada, lembra? Arquivo empacotado não consome contexto até ser acessado, o peso está na listagem de metadados

2. Rode /context

Ele reporta o tamanho da listagem de skills já depois do orçamento aplicado, que é exatamente o que o modelo recebe

Se o número do /context está bem abaixo do que o /doctor estimou, você já sabe: tem descrição sendo derrubada

3. Corte as descrições gordas

O campo description do SKILL.md tem máximo de 1024 caracteres, precisa ser não vazio e não pode conter tags XML

E existe um teto por skill no texto que aparece na listagem, somando description e when_to_use, configurável em skillListingMaxDescChars, padrão 1536 caracteres

O erro comum deste passo: escrever até o limite porque o limite existe

O limite é teto, não meta 😀

4. Reescreva em terceira pessoa, com gatilho explícito

O que a skill faz, mais quando ela deve ser usada

Duas frases resolvem a maioria dos casos

5. Marque disable-model-invocation: true no que só você deve chamar

---
name: deploy-producao
description: Publica a build atual no ambiente de produção
disable-model-invocation: true
---

Isso tira a description do contexto e ainda te protege de disparo automático em fluxo com efeito colateral

Dois problemas, uma linha

6. Se as skills embutidas não fazem parte do seu fluxo, desligue

O Claude Code traz um conjunto próprio, invocado digitando / seguido do nome: /doctor, /code-review, /batch, /debug, /loop e /claude-api

Pra desligar todas de uma vez, no settings.json:

{
  "disableBundledSkills": true
}

Tome cuidado aqui: isso desliga o conjunto embutido, com uma exceção

O /doctor continua digitável a partir do Claude Code v2.1.205, então você não perde a ferramenta de diagnóstico, mas o resto some

Só puxe esse gatilho se você realmente não usa nenhuma delas

Onde cada skill deveria morar: pessoal, projeto ou plugin?

Enxugar por gosto é chato e você não faz

Enxugar por ESCOPO é mecânico, e aí funciona

A pergunta é sempre a mesma: essa skill precisa estar visível em todo lugar, ou só num contexto?

Skill que só faz sentido num repositório específico não tem motivo nenhum pra viver em ~/.claude/skills/ ocupando espaço nos outros 12 projetos que você abre

Esse raciocínio de manter cada coisa no seu escopo é o mesmo que vale pra rodar dois projetos ao mesmo tempo sem misturar contexto

O caso dos fluxos com efeito colateral:

Deploy, envio de mensagem, qualquer coisa que toca o mundo real

Esses ficam melhor como invocação exclusiva do usuário, com disable-model-invocation: true

Você ganha segurança e ganha contexto de volta, já que a description sai da listagem

E as skills embutidas:

Vale lembrar que /doctor, /code-review, /batch, /debug, /loop e /claude-api já vêm com o Claude Code e já ocupam espaço na sua listagem

Não é motivo pra sair desligando tudo

É motivo pra contar elas na conta quando você for medir

O número que importa não é quantas skills, é quanto elas ocupam

Não tem número mágico, e desconfie de quem cravar um

O critério é bem mais simples que isso: uma skill merece continuar ativa se a description dela cabe no orçamento e é específica o bastante pra não competir com as vizinhas

Se ela falha em qualquer um dos dois, ou você reescreve, ou ela vira invocação exclusiva sua, ou ela sai

Próximo passo concreto, dá pra fazer hoje em cinco minutos:

roda /doctor, anota os maiores contribuintes, roda /context pra ver o que sobrou depois do corte e ataca de cima pra baixo

E já que você vai estar depurando o que está carregado, a doc indica o checklist completo: /context, /doctor, /hooks e /mcp

Skill costuma ser a primeira suspeita, mas raramente é a única inquilina do seu contexto…

Até o próximo post! =)