Uma skill de design grande ou várias pequenas? Como organizar skills no Claude Code

Fala aí, beleza? Tua primeira skill funcionou, o Claude aplicou a regra sozinho na hora certa e bateu aquela vontade de jogar TODO o resto pra dentro do mesmo arquivo

Aí vem a dúvida que todo mundo enfrenta no segundo dia: um SKILL.md completão com tudo que é regra de design, ou vários pequenos separados por assunto?

A resposta não é gosto de organização, é mecânica

O que decide é como o Claude Code descobre, carrega e escolhe a skill no momento exato em que a regra precisa ser aplicada

E nesse ponto os dois formatos se comportam de jeitos bem diferentes…

Como o Claude Code carrega e escolhe uma skill

Antes de comparar formato, o básico, porque a comparação inteira se apoia nisso

Uma skill é um diretório que contém um arquivo SKILL.md, com frontmatter YAML seguido de conteúdo em Markdown

Ou seja: não é um arquivo solto perdido no projeto, é pasta com nome + o SKILL.md dentro

.claude/
└── skills/
    └── design-front-end/
        └── SKILL.md

E onde essas pastas ficam? As skills pessoais ficam em ~/.claude/skills/ e as de projeto em .claude/skills/

No caso das de projeto, o Claude Code busca em .claude/skills/ do diretório onde a sessão foi iniciada e também em cada diretório pai, até a raiz do repositório

Isso já resolve uma dor clássica: tu não precisa abrir a sessão exatamente na raiz pra skill do repo ser vista

O carregamento é progressivo:

Essa é a parte que muita gente ignora e depois reclama que "a skill não ativou"

Inicialmente o Claude vê apenas os metadados do frontmatter do SKILL.md

Só quando a skill é considerada relevante é que o conteúdo completo entra, junto com scripts e recursos auxiliares

Traduzindo: o corpo lindo que tu escreveu não ajuda em NADA na hora da escolha, quem faz esse trabalho é o frontmatter

O frontmatter, campo por campo:

No Claude Code os campos suportados em SKILL.md são name, description, disable-model-invocation e allowed-tools

Todos são opcionais, e apenas description é recomendado, justamente pro Claude saber quando usar a skill

---
name: Design de front-end
description: Aplica o guia visual do projeto em telas e componentes. Usar quando o pedido envolve layout, tipografia, espaçamento ou tema da interface.
---

O disable-model-invocation é booleano: com true, a skill fica invocável somente por você, e o Claude não aciona ela por conta própria

Já o allowed-tools vale sempre que a skill é invocada, por você ou pelo Claude, mas atenção: ele NÃO é lista de restrição

Toda ferramenta continua chamável e as configurações de permissão seguem valendo pras que não estão listadas

Tome cuidado com esse aqui: o campo name define apenas o rótulo exibido nas listagens

O comando continua vindo do nome do diretório da skill

Então renomear o name e achar que o comando mudou junto é um erro bem fácil de cometer

Se tu ainda tá se situando entre skills, comandos e subagentes, vale dar uma olhada nisso antes, porque a confusão entre eles aparece muito nessa fase

A referência completa tá na documentação de skills do Claude Code

Skill de design grande x várias skills pequenas: comparação

Agora dá pra confrontar os dois formatos pelo que acontece na hora da aplicação, e não pelo que é mais bonito na pasta

Repara que a linha mais decisiva é a primeira

Cada skill tem exatamente um campo description, e é por ele que o Claude escolhe a skill certa no meio de todas as skills disponíveis

Uma description só, tentando descrever cinco assuntos, é uma description pior pra CADA um deles

Quando uma skill só resolve e quando é hora de separar

Não é regra cega, beleza? Tem cenário em que juntar é o certo

A skill única resolve quando:

• A regra é curta e sempre se aplica junto (tipo um padrão de espaçamento e tipografia que vale pro projeto inteiro)
• O corpo cabe folgado abaixo das 500 linhas recomendadas
• Não existe caminho dentro dela que tu use isolado dos outros

Se é isso, para por aqui, não invente complexidade

É hora de separar quando:

• O arquivo mistura assuntos que quase nunca são usados na mesma conversa
• Tu precisa lembrar de dizer "use a parte X da skill" no prompt, sinal claro de que a escolha não tá acontecendo sozinha
• O corpo passou das 500 linhas: aí a orientação oficial é dividir em arquivos separados usando carregamento progressivo

E olha um argumento de autoridade que vale mais que teoria: o repositório público de Agent Skills da Anthropic não tem uma única skill de design

Ele traz skills separadas, tipo canvas-design, frontend-design, brand-guidelines e theme-factory

Quatro assuntos que se tocam, mas raramente são acionados na mesma tarefa

E quando o time entra na história:

Tem um detalhe que decide a briga de escopo pra muita gente

Sessões do Cowork e sessões na nuvem (incluindo routines) não leem o ~/.claude/skills/ da tua máquina

As sessões na nuvem carregam as skills de projeto commitadas em .claude/skills/ do repositório clonado

Ou seja: se a regra de design precisa valer pro time ou pra rodar remoto, ela tem que estar versionada no projeto, e não na tua pasta pessoal

Esse ponto sozinho já empurra bastante gente pro caminho de skills de projeto separadas por assunto

O que aparece quando você usa skills em todo projeto

Aqui eu falo do que eu faço na prática, e não de teoria de documentação

Eu uso seis skills em praticamente todos os projetos que inicio com Claude Code, encadeadas em sequência, cada uma cobrindo uma etapa diferente

Não é uma skill gigante tentando fazer tudo

Eu começo com a skill de brainstorm, que conduz uma rodada de perguntas pra entender o que eu quero antes de escrever qualquer código, e fecha gerando uma documentação de especificação

Eu revisei essa doc antes de seguir (durante o brainstorm ainda me ofereceram gerar mockups e diagramas no navegador, com aviso de consumo maior de tokens, e eu recusei pra ir direto pra implementação)

Depois passei a documentação aprovada pra uma segunda skill, de planejamento, pedindo um plano de implementação com tarefas em ordem, dependências e critérios de aceitação

O plano saiu com 14 tarefas, e essas 14 foram concluídas na execução

A terceira skill executou o plano, com pedido de rodar com subagents e TDD (teste primeiro, implementação depois), formato que depende bastante do tamanho do projeto

Como o plano já estava no contexto, bastou pedir a execução, mas dá pra referenciar o arquivo direto pra ter certeza de qual documento vai ser executado

Um aviso honesto: a execução gera MUITO pedido de aceite na fase de criação de arquivos

E tem etapa demorada mesmo: a configuração de sessão (terceira tarefa) ficou quase 10 minutos rodando aqui

No fim o app subiu, mas quebrou no fluxo de criar conta e login

Eu colei o erro no chat, pedi análise e correção, e só então consegui acessar e cadastrar uma despesa

Agora o ponto que interessa pra este post: as três primeiras skills resolveram estrutura e arquitetura, e entregaram uma interface genérica

Projeto sem alma, é assim que eu chamo

Esse problema eu prefiro resolver com uma skill específica de front end, e não enfiando regra de visual dentro da skill de execução

Quando ativei a skill de design com um prompt descritivo (visual clean, moderno, modo escuro, sensação de controle das finanças), a mudança foi significativa em tipografia, consistência de elementos e estilo geral

E aproveitando: boa parte das reclamações de resultado ruim em design vem do prompt fraco, não da skill

O resultado também pode variar entre execuções, isso é honesto dizer

Na parte de segurança eu fui pelo mesmo raciocínio ao contrário: eu poderia criar uma skill única englobando muitos requisitos e fazendo uma análise milimétrica, mas avalio que isso pode não ser tão bom

Prefiro criar a skill sob medida pro projeto, alinhada às tecnologias e regras dele, mesmo quando peço pro próprio Claude Code gerar a skill

Criei ela como skill do projeto, e não global, e nessa skill eu listei categorias explícitas (secrets, inputs, autenticação, dependências, headers), exigi verificação mecânica com comandos reais e contagem de problemas, e pedi nota total, breakdown por categoria e lista de problemas no final

Nada disso é bala de prata, é o que funciona na minha rotina =)

Eu gravei esse encadeamento inteiro acontecendo na tela, do brainstorm até o redesenho do front end, com os travamentos e as correções no meio

Veredito: separe por assunto e trate a description como a interface da skill

Meu veredito é direto: quebrar por assunto ganha, e o motivo é a seleção

A escolha da skill acontece pela description, então cada assunto merece a sua

E description não é enfeite, é a interface pública da tua skill

A documentação oficial recomenda escrever em terceira pessoa, incluindo o que a skill faz e os gatilhos de quando usar

O porquê importa aqui: a description é injetada no system prompt, e ponto de vista inconsistente causa problema de descoberta

Ou seja, aquela description no estilo "eu te ajudo com design" atrapalha, não ajuda

As boas práticas oficiais de autoria de skills também batem na tecla do tamanho: corpo do SKILL.md abaixo de 500 linhas, e se passar, divide em arquivos separados

Os limites do padrão que tu precisa respeitar:

• name: no máximo 64 caracteres, só letras minúsculas, números e hifens
• name: sem tags XML e sem as palavras reservadas anthropic e claude
• description: não pode ser vazia e vai até 1024 caracteres

Mil e poucos caracteres parece muito, mas tenta descrever tema, marca, front-end e canvas numa description só e tu vai sentir o aperto na hora

E quando a skill única continua sendo a escolha certa? Quando o assunto é um só e a regra sempre se aplica inteira

Separar nesse caso só cria mais pasta pra manter, sem ganho nenhum de precisão

Se a dúvida ainda tá em pé no teu caso específico, vale ver como dividir skills no Claude Code com mais calma

Como quebrar uma skill de design grande em skills menores

Passo a passo curto, sem firula

1. Liste os assuntos que estão dentro do arquivo atual

Abre teu SKILL.md e marca os blocos: tema, marca, componentes, layout, o que for

O erro comum deste passo: separar por tamanho ("tá grande, corto no meio") em vez de separar por assunto, o que gera duas skills com gatilhos idênticos e nenhuma das duas com description clara

2. Crie um diretório por skill, cada um com seu SKILL.md

.claude/
└── skills/
    ├── design-tema/
    │   └── SKILL.md
    ├── design-marca/
    │   └── SKILL.md
    └── design-front-end/
        └── SKILL.md

O erro comum deste passo: achar que o name do frontmatter define o comando

Não define, o comando vem do nome do diretório, e o name é só o rótulo exibido nas listagens

3. Mova pra arquivos separados os caminhos mutuamente exclusivos

Aquele trecho que quase nunca é usado junto com o resto sai do corpo e vira arquivo próprio, apoiado no carregamento progressivo

O erro comum deste passo: mover conteúdo que SEMPRE é usado junto, e aí tu só espalhou a mesma regra em dois lugares

4. Mantenha o corpo de cada SKILL.md abaixo de 500 linhas

Se passou, é sinal de que ainda tem assunto demais ali dentro

5. Reescreva cada description com o que faz e quando usar

Terceira pessoa, gatilhos explícitos, dentro dos 1024 caracteres

O erro comum deste passo: manter a description antiga genérica nas três skills novas, o que devolve exatamente o problema que tu estava tentando resolver

6. Decida o escopo: ~/.claude/skills/ ou .claude/skills/

Pessoal pra tuas manias, projeto pro que o time e o repo precisam

O erro comum deste passo: deixar em pessoal uma regra que precisa valer no time ou em sessão na nuvem

Remoto não lê o ~/.claude/skills/ da tua máquina, ele lê as skills de projeto commitadas

Conclusão

O critério de decisão cabe numa frase: o Claude escolhe pela description, então uma description por assunto

Skill grande não é errada por ser grande, ela é errada quando obriga um campo só a descrever cinco gatilhos diferentes

Teu próximo passo é bem concreto: pega a tua maior skill hoje, lista os assuntos que moram dentro dela e separa o PRIMEIRO caminho que quase nunca é usado junto com o resto

Um corte só já dá pra sentir a diferença na hora em que o modelo precisa aplicar a regra

E pra quem quer ir além, uma referência ajuda bastante: a skill oficial skill-creator, que vive no repositório anthropics/claude-plugins-official, na pasta plugins/skill-creator

Dá uma organizada nas tuas skills e me conta como ficou, até o próximo post! 🙂