Uma skill grande ou várias pequenas: o que funciona melhor no Claude Code?

Fala aí, beleza? Você montou sua primeira skill, ela funcionou, e agora bateu aquela dúvida chata: engorda o mesmo SKILL.md ou cria uma pasta nova pra próxima etapa?

Parece decisão de arrumação de arquivo

Não é

Essa escolha muda o que o agente enxerga, QUANDO ele enxerga e quanto do seu contexto some só pra ele lembrar das regras. Uma skill grande ou várias pequenas é, no fundo, uma decisão sobre atenção do modelo

Bora destrinchar isso com o que a documentação realmente diz, e não no achismo 🙂

Como o Claude Code decide qual skill usar

Antes de discutir tamanho, tem que entender o mecanismo de carregamento. Porque é ele que explica tudo o que vem depois

Uma skill no Claude Code é uma pasta com um arquivo SKILL.md dentro. O nome da pasta vira um comando que você digita, e a skill pode ser chamada por você com /nome ou carregada automaticamente pelo Claude quando ele julga que é relevante

Onde essa pasta mora muda o alcance:

• ~/.claude/skills/ guarda as skills pessoais, que valem em todos os projetos
• .claude/skills/ (dentro do repositório) guarda as skills daquele projeto

Além do SKILL.md, que é obrigatório, a estrutura aceita pastas opcionais pra código executável, documentação de referência e ativos como templates e dados:

.claude/skills/
└── revisar-pr/
    ├── SKILL.md
    ├── scripts/
    ├── references/
    └── assets/

Divulgação progressiva em 3 estágios:

Aqui mora o pulo do gato. O carregamento não é tudo de uma vez, ele acontece em estágios:

1. Descoberta: no começo o agente vê só o name e a description de cada skill
2. Ativação: o corpo do SKILL.md entra no contexto quando a tarefa casa com aquela descrição
3. Execução: os arquivos de apoio (scripts, referências) só são lidos na hora que forem usados

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Se você conhece lazy loading, é a mesma ideia: carrega o mínimo pra decidir, e o resto só sob demanda

E repara numa consequência direta: a escolha da skill é feita pela description, não pelo conteúdo. Claude compara a tarefa com as descrições disponíveis. Se as descrições são vagas ou se sobrepõem, ele pode carregar a skill errada ou deixar passar uma que ajudaria

Por isso a description tem regras próprias: até 1024 caracteres, escrita em terceira pessoa, dizendo o que a skill faz E quando usar, com termos concretos de acionamento. O name aceita até 64 caracteres, só minúsculas, números e hífens

---
name: revisar-pr
description: Revisa pull requests checando testes, lint e mudanças de schema. Usar quando o usuário pedir revisão de PR, análise de diff ou checagem de branch antes do merge.
---

As propriedades permitidas no frontmatter do SKILL.md são allowed-tools, compatibility, description, license, metadata e name

Uma curiosidade que ajuda a entender o desenho: no Claude Code, um arquivo em .claude/commands/deploy.md e uma skill em .claude/skills/deploy/SKILL.md criam o mesmo /deploy e funcionam do mesmo jeito. Os arquivos que você já tem em .claude/commands/ continuam funcionando, então não precisa sair migrando nada às pressas

Skill grande vs. várias skills pequenas: comparativo

Colocando os dois desenhos lado a lado nos critérios que realmente doem no dia a dia:

Nenhuma coluna ganha em tudo, e é exatamente por isso que essa discussão existe 😀

Quando uma skill grande faz sentido

Concentrar compensa em três situações bem específicas

Fluxo único e linear. Se as etapas sempre rodam na mesma ordem e ninguém nunca pede só o pedaço do meio, separar não traz ganho nenhum. Você só cria duas descriptions parecidas competindo pela mesma tarefa, que é justamente o cenário em que o modelo erra a escolha

Conteúdo que cabe confortavelmente no arquivo. A documentação de autoria recomenda manter o corpo do SKILL.md abaixo de 500 linhas. Se o seu fluxo inteiro cabe folgado nisso, tá tudo certo, não precisa inventar arquitetura

Passos que quase sempre são usados juntos. Aqui a lógica é a mesma do ponto anterior, mas por outro ângulo: se o contexto da etapa A quase sempre também é necessário pra etapa B, dividir não economiza token, só adiciona uma decisão a mais pro modelo tomar

O ponto é esse: skill grande não é pecado. Skill grande MAL RECORTADA é que dói

Quando fatiar em skills menores é melhor

Agora o outro lado. Tem sinais bem objetivos de que chegou a hora de quebrar

Contextos mutuamente exclusivos. Quando dois caminhos raramente são usados juntos, manter eles separados reduz o uso de tokens. Simples assim. Não faz sentido carregar 200 linhas sobre migração de banco quando o pedido era ajustar um componente de UI

Graus de liberdade diferentes por etapa. A orientação oficial é casar a especificidade com a fragilidade da tarefa:

• liberdade alta: instruções em prosa, quando vários caminhos servem
• liberdade média: pseudocódigo ou script com parâmetros, quando existe um padrão preferido
• liberdade baixa: script específico, com poucos ou nenhum parâmetro, pra operações frágeis

Se uma etapa do seu fluxo é "explore como quiser" e a outra é "rode EXATAMENTE este script", empurrar as duas no mesmo arquivo é pedir pro modelo misturar os tons. Essa é a hora clássica de dividir as skills por etapa em vez de continuar engordando o mesmo arquivo

Etapas com efeito colateral. No Claude Code, dois campos do frontmatter restringem a invocação, e disable-model-invocation: true faz com que só você possa chamar aquela skill. É perfeito pra fluxo que commita, faz deploy ou dispara mensagem

---
name: deploy-prod
description: Executa o deploy da branch main em produção. Usar somente quando o usuário pedir deploy explicitamente.
disable-model-invocation: true
---

Repara que isso só existe como opção se a etapa perigosa estiver ISOLADA numa skill própria. Se ela mora dentro da skill gigante, ou você trava o fluxo inteiro ou não trava nada

E tem um detalhe bonito do modelo: skills são compostas. O Claude identifica quais são necessárias e coordena o uso delas, em vez de exigir um agente customizado por caso de uso. Ou seja, fatiar não te obriga a orquestrar tudo na mão

Os três problemas mais comuns de cada escolha

Sintoma: a skill nunca é acionada sozinha

Você criou, ela tá lá, mas o Claude só usa quando você digita /nome na marra

Causa: a seleção é feita pela description. Descrição vaga ("ajuda com o projeto") ou sobreposta com outra skill leva à escolha errada ou à omissão

Solução: reescreve a description em terceira pessoa, com "o que faz" mais "quando usar", e termos concretos que apareceriam no pedido real do usuário. Você tem até 1024 caracteres, então dá pra ser específico sem apertar

Prevenção: antes de salvar, lê as descriptions de todas as suas skills em sequência. Se duas soam parecidas pra VOCÊ, vão soar parecidas pro modelo também

Sintoma: a skill come contexto demais

A conversa começa a esquecer coisa que você falou lá atrás, logo depois que a skill entra

Causa: depois que o Claude carrega o SKILL.md, cada token dele compete com o histórico da conversa e com o resto do contexto. Corpo longo é corpo caro

Solução: empurra o conteúdo pra arquivos separados e instrui o Claude a ler o arquivo apropriado conforme a tarefa. Arquivos adicionais só são lidos quando necessários, então isso devolve contexto pra conversa

Prevenção: usa a régua das 500 linhas como alarme. Passou disso, divide

Sintoma: o agente escolhe a skill errada entre muitas

Você instalou um monte de coisa, achou lindo, e agora ele erra o alvo

Causa: o metadado (name e description) de CADA skill disputa atenção no system prompt. Com skills demais ativas, o modelo pode não selecionar a correta ou ignorar uma relevante

Solução: limita quantas skills ficam carregadas ao mesmo tempo e mede o recall com uma suíte de avaliação. Quando o desempenho cai, para de adicionar

Prevenção: cuidado especial ao instalar coleções de terceiros. Dá pra adicionar um marketplace com /plugin marketplace add <owner>/<repo> e depois rodar /plugin install <nome>, e um plugin pode trazer skills, agentes, hooks e servidores MCP de uma vez só. É a hora de pensar se a skill mais popular serve pro SEU fluxo, ou se ela só vai ocupar espaço competindo com as suas

Detalhe pra não confundir: nas requisições da API do Claude o limite é de 20 skills por requisição. Isso é limite da API, não do Claude Code, então não saia por aí tratando 20 como número mágico do seu terminal

Como decidir na prática: um roteiro em 5 passos

Bora ver na prática? Esse roteiro funciona tanto pra skill nova quanto pra refatorar uma que já tá inchada

1. Mapeia as etapas do fluxo em uma linha cada. Escreve literalmente "etapa 1 faz X", "etapa 2 faz Y". Se uma etapa precisa de um parágrafo pra ser descrita, ela provavelmente são duas

Erro comum deste passo: mapear pelo arquivo que você já escreveu, em vez de mapear pelo que o usuário realmente pede. O recorte tem que nascer do pedido, porque é o pedido que vai ser comparado com a description

2. Escreve PRIMEIRO as descriptions, antes do corpo. Uma por etapa candidata, em terceira pessoa, com "o que faz" e "quando usar". Depois lê as duas juntas e pergunta: dá pra confundir?

Erro comum deste passo: escrever description genérica pra "cobrir mais caso". Description ampla não te dá mais acionamento, te dá acionamento errado

3. Define o grau de liberdade de cada etapa. Prosa quando vários caminhos servem, pseudocódigo ou script com parâmetros quando existe um padrão preferido, script exato pras operações frágeis

Erro comum deste passo: escrever tudo em prosa porque é mais rápido. Aí a etapa frágil vira improviso do modelo, e você descobre no pior momento possível

4. Confere o tamanho do corpo. Passou de 500 linhas? Move o excesso pra arquivos separados e aponta no SKILL.md qual arquivo ler pra qual tarefa

Erro comum deste passo: quebrar em arquivos e esquecer de dizer QUANDO ler cada um. Arquivo de apoio sem instrução de leitura é arquivo que nunca vai ser aberto

5. Mede antes de consolidar. A recomendação corporativa é começar com skills estreitas e específicas de fluxo, e só consolidar em pacotes por papel quando as avaliações confirmarem desempenho equivalente ao das skills individuais que a versão consolidada substitui

Erro comum deste passo: consolidar "porque tá bagunçado". Organização visual não é métrica, beleza? Consolidação sem avaliação é troca de precisão por estética de pasta

O que aconteceu quando usei skills num projeto real

No vídeo abaixo eu monto um app de finanças combinando pesquisa e geração de código, e o recorte das skills foi justamente o ponto que mais mexeu no resultado

A pesquisa veio do NotebookLM, com 10 fontes reunidas sobre o tema antes de qualquer linha de código. Só depois disso as skills entraram em cena

E aqui vem a parte que interessa pro nosso dilema: eu testei usar uma ÚNICA skill full stack pra gerar back-end e front-end juntos, numa leva só, em vez de rodar dois prompts separados pra cada parte

Dava pra fazer separado, eu deixei isso claro no vídeo. Eu optei por me apoiar na skill ampla justamente pra fechar as duas pontas de uma vez

Depois que a aplicação inteira já estava de pé, eu apliquei uma segunda skill, essa focadinha só em design de interface, como camada extra de refinamento

Ou seja: na prática eu não escolhi um lado. Usei uma skill ampla pra base e uma skill pequena e específica pro acabamento

Um detalhe operacional que virou hábito meu: eu conferi se a skill tinha sido usada DE VERDADE checando se a ferramenta acessou o arquivo de instruções da skill. Pra mim esse é o sinal honesto de acionamento, não o "parece que funcionou"

E já aviso: leia o conteúdo de uma skill antes de jogar ela no seu projeto. Sempre. Você tá entregando instrução operacional pro agente, então saber o que tá escrito ali não é paranoia, é higiene básica

A motivação de colocar skills no fluxo foi melhorar a qualidade do código entregue e gastar menos prompt e menos cota. Num workflow anterior, sem skills, a ferramenta errava mais e entregava menos, por causa da complexidade do projeto somada ao limite de uso do plano gratuito

O que eu mudaria hoje no desenho? Eu escreveria a description da skill ampla com mais cuidado, porque "full stack" é exatamente o tipo de termo que casa com tarefa demais. E manteria a de design separada do jeito que estava, já que ela roda em outro momento e com outro objetivo

Veredito: qual desenho escolher para o seu fluxo

Vamos ao que interessa

Fluxo pequeno, linear e sempre usado inteiro: pode viver numa skill só. Mantém o corpo abaixo de 500 linhas, escreve uma description específica e segue a vida. Dividir aqui só cria duas descrições brigando pela mesma tarefa

Fluxo com etapas distintas, contextos que não se cruzam ou riscos diferentes: fatia. Principalmente se tiver etapa com efeito colateral, porque só assim dá pra isolar ela com disable-model-invocation: true

Na dúvida: começa estreito. A recomendação oficial é essa, e ela tem um motivo prático forte, que é ser MUITO mais fácil juntar duas skills pequenas depois do que dissecar um SKILL.md de mil linhas

E guarda essa: quantidade de skills ativas tem custo de precisão. Cada metadado disputa atenção no system prompt, então encher o ambiente de skill "por via das dúvidas" degrada a seleção. Consolidar só se justifica com evidência de avaliação, nunca com a sensação de que tá organizado

Conclusão

A pergunta "uma skill grande ou várias pequenas" não tem resposta única, mas tem um critério: a divisão certa é a que faz o modelo acertar a escolha e carregar só o contexto necessário

O próximo passo prático é bem direto

Abre suas skills atuais e lê APENAS as descriptions, uma atrás da outra. Duas parecidas? Já achou seu problema

Depois roda uma tarefa real e observa qual skill foi carregada. Esse teste de 5 minutos revela mais que qualquer teoria sobre arquitetura de pasta

E se quiser uma referência de recorte estreito bem feito, olha as skills que já vêm embutidas no Claude Code: /doctor, /code-review, /batch, /debug, /loop e /claude-api. Cada uma faz UMA coisa e o nome já entrega quando usar. É exatamente esse nível de clareza que a sua description precisa ter

Bora testar? 😀

Até o próximo post!