Uma skill para tudo ou várias pequenas: qual divisão funciona melhor no Claude Code?

Fala aí, beleza? Tem uma decisão que vem ANTES de você escrever a primeira linha do seu SKILL.md, e quase ninguém para pra pensar nela: você vai empacotar o fluxo inteiro numa skill só, ou fatiar em skills menores por etapa?

Parece detalhe de organização, mas não é

Toda skill é um arquivo SKILL.md com frontmatter YAML, e só dois campos são obrigatórios ali: name e description

O name aceita no máximo 64 caracteres, só letras minúsculas, números e hifens, sem tags XML e sem as palavras reservadas anthropic ou claude

O description vai até 1024 caracteres, não pode ficar vazio, também não aceita tags XML, e precisa dizer o que a skill faz E quando usar ela

Repare no detalhe: esses dois campos são justamente o que o Claude carrega de TODAS as suas skills logo na inicialização

Ou seja, a granularidade que você escolher muda diretamente como o Claude encontra e carrega o seu arquivo 🙂

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

Skill única x skills menores: comparativo lado a lado

Antes da tabela, o mecanismo que explica quase toda linha dela: skills usam divulgação progressiva em 3 níveis

Nível 1: name + description de cada skill instalada entram no system prompt sempre

Nível 2: o corpo do SKILL.md só entra em contexto quando a tarefa combina com a description

Nível 3: arquivos extras são lidos só quando referenciados

Enquanto a skill não é acionada, ela custa em contexto apenas os metadados, o que permite manter várias skills instaladas sem estourar o contexto à toa

Se liga no comparativo:

E onde esses diretórios ficam importa tanto quanto o conteúdo deles

No Claude Code, o local define QUEM consegue usar a skill: ~/.claude/skills/<skill-name>/SKILL.md é pessoal e vale em todos os seus projetos, .claude/skills/<skill-name>/SKILL.md é do projeto e vale só ali, <plugin>/skills/<skill-name>/SKILL.md vale onde o plugin está habilitado, e o nível enterprise vem via managed settings

A skill de projeto é a que você distribui pro time: é só commitar .claude/skills/ no repositório

Tome cuidado com nome repetido! Quando skills de níveis diferentes têm o mesmo name, existe ordem de precedência: enterprise sobrescreve pessoal, e pessoal sobrescreve projeto

Ou seja, fatiar em muitas skills multiplica também as chances de colisão de nome

E vale lembrar que esse mesmo formato de arquivo aparece em outros agentes, dá pra ver o paralelo em skills em agentes de código

Quando uma skill única é a escolha certa

A doc oficial dá um critério bonito pra isso: calibrar os graus de liberdade da skill conforme a fragilidade e a variabilidade da tarefa

Baixo grau de liberdade é quando só existe UM caminho seguro: aí você escreve instruções exatas e guardrails (limites)

O exemplo citado na própria documentação é migração de banco de dados, que precisa rodar em sequência exata

E aqui o monolito ganha fácil

O fluxo tem um caminho seguro só:

Se o passo 3 sem o passo 2 quebra o banco, fatiar é convite pro Claude acionar a etapa errada sozinho

Numa skill única, a sequência inteira está no mesmo corpo, na ordem, com os avisos no lugar certo

É como uma receita de bolo: você não separa ‘bater a massa’ e ‘levar ao forno’ em dois papéis diferentes esperando que alguém adivinhe a ordem 😀

As etapas são SEMPRE usadas juntas:

O critério oficial pra dividir conteúdo é contexto mutuamente exclusivo ou raramente usado junto

Inverte a frase e você tem o critério pra NÃO dividir: se as etapas rodam sempre juntas, separar só cria três descriptions competindo pelo mesmo acionamento

O corpo cabe folgado abaixo de 500 linhas:

A recomendação oficial é manter o corpo do SKILL.md abaixo de 500 linhas

Se o seu fluxo inteiro cabe ali com sobra, você não tem problema de tamanho pra resolver

Dividir por dividir, nesse caso, é só trabalho a mais de manutenção

Quando vale fatiar em skills menores por etapa

Agora o outro lado

Os contextos são mutuamente exclusivos:

Esse é o critério mais direto da documentação: quando o conteúdo cobre situações que raramente aparecem juntas, separar reduz uso de tokens

Pensa num fluxo que atende três frentes que nunca se cruzam numa mesma tarefa

Junto tudo, toda vez que a skill aciona por causa de uma frente, o corpo das outras duas entra em contexto de carona

O corpo passou de 500 linhas:

Quando o SKILL.md fica grande demais, a orientação oficial é clara: separar o conteúdo em arquivos e referenciá-los

E aqui tem a alternativa intermediária que muita gente esquece

Você NÃO precisa ir direto de ‘uma skill gigante’ pra ‘cinco skills’

Dá pra manter uma skill só e mover o conteúdo pesado pra arquivos referenciados, que são lidos apenas quando necessários

Algo assim:

.claude/skills/
└── revisao-de-codigo/
    ├── SKILL.md
    ├── seguranca.md
    └── performance.md

O SKILL.md continua sendo a porta de entrada, e os arquivos auxiliares só entram em contexto quando o próprio fluxo mandar ler

Isso é o nível 3 da divulgação progressiva trabalhando a seu favor

A tarefa tem alto grau de liberdade:

Quando muitos caminhos levam ao sucesso, a doc recomenda dar só a direção geral

O exemplo oficial citado é code review

E tarefa de direção geral pede skill enxuta, não manual gigante tentando prever cada caso

Tem um detalhe de modelo aqui:

A documentação avisa que o nível de detalhe necessário varia por modelo

O que funciona bem no Opus pode exigir mais detalhe no Haiku

Se a sua skill vai rodar em vários modelos, escreva instruções que funcionem em todos

Isso mexe na conta do tamanho: skill que precisa ser mais explícita cresce mais rápido, e chega antes no ponto de dividir

E se você ainda tem dúvida sobre em quais ambientes esse arquivo é lido, vale entender onde uma skill roda de verdade antes de decidir a divisão

Veredito: qual divisão funciona melhor

Vou ser honesto contigo: não existe resposta única aqui, e desconfie de quem te vender uma

A granularidade não se escolhe por gosto nem por estética de pasta bonita

Ela se escolhe por DUAS coisas: acionamento e exclusividade dos contextos

Acionamento porque o Claude decide carregar o corpo comparando a tarefa com a description

Exclusividade porque o único critério oficial pra separar conteúdo é contexto mutuamente exclusivo ou raramente usado junto

Então a régua prática pra dividir skills no Claude Code cabe em três perguntas:

1. As etapas rodam sempre juntas? Se sim, mantém numa skill só. Se cada uma aparece sozinha na maior parte do tempo, fatia
2. O corpo passa de 500 linhas? Se passa, separa em arquivos referenciados primeiro. Só vira skill nova se as descriptions também forem diferentes de verdade
3. Existe um caminho só ou muitos? Caminho único e frágil pede baixa liberdade e instruções exatas no mesmo arquivo. Muitos caminhos pedem direção geral e corpo enxuto

O critério deste post é o que a documentação oficial recomenda

Número de tamanho ideal por tipo de skill que circula por aí eu não vou repetir, porque não achei em fonte oficial

Acho zoado botar dado por achismo

Por onde começar a sua primeira skill

A recomendação oficial começa num lugar que não é o editor: começa na avaliação

Identifique as lacunas REAIS de capacidade do agente e construa skills de forma incremental pra cobrir essas lacunas

O que isso quer dizer na prática? Não nasça com um pacote grande

Você não precisa adivinhar a granularidade certa no dia 1: descobre onde o agente falha, escreve a skill pra aquilo, e deixa a divisão aparecer conforme os contextos se separam sozinhos

Dois lugares pra olhar antes de sair escrevendo:

1. O repositório público de Agent Skills da Anthropic, em anthropics/skills, pra ver como skills reais estão escritas
2. A skill oficial skill-creator, distribuída como plugin: ela vive em plugins/skill-creator/skills/skill-creator/SKILL.md, no repositório anthropics/claude-plugins-official

E fecho com uma pegadinha que pode te queimar tempo

O campo de frontmatter allowed-tools só é suportado quando você usa a CLI do Claude Code

Ele NÃO se aplica a skills via SDK, onde o acesso a ferramentas é controlado pela opção allowedTools da query

No Agent SDK ainda tem outro detalhe: quais diretórios de skills carregam depende do setting sources, com .claude/skills/ entrando quando inclui "project" e ~/.claude/skills/ quando inclui "user"

Ou seja, a mesma skill pode simplesmente não aparecer se você mudar de ambiente e esquecer disso

Decide a granularidade pelo acionamento, começa pequeno, cresce quando o contexto pedir

Até o próximo post! 😀