✅ Quando VALE uma skill
Uma skill custa contexto e manutenção. Ela só se paga quando há ganho real e repetido. Existem quatro sinais verdes — quanto mais deles presentes, mais clara é a decisão de empacotar. A regra prática: se dois ou mais sinais batem, vale criar a skill.
🔁 Workflow repetível
Você executa a mesma sequência de passos toda semana — gerar componente, configurar deploy, escrever um tipo de teste. Repetição é o sinal número um.
Exemplo: padrão de PR, convenção de commit, scaffold de feature.
🧠 Conhecimento de contexto do time
Algo que só o seu time sabe: convenções internas, gotchas do legado, decisões de arquitetura. O modelo não adivinha isso sozinho.
Exemplo: "neste repo, sempre use o wrapper X em vez de fetch direto".
🔍 Output verificável
Dá pra checar se ficou certo — testes passam, lint limpa, schema valida. Output verificável permite iterar e medir a skill.
Exemplo: código que compila, JSON que valida contra um schema.
🪜 Multi-step
A tarefa tem vários passos encadeados com ordem e dependências. A skill encapsula o processo inteiro, não só uma dica solta.
Exemplo: ler config → gerar arquivos → rodar build → validar.
💡 Dica de calibragem
Se você se pega explicando a mesma coisa pro agente pela terceira vez na semana, isso é um workflow repetível + conhecimento de contexto. Dois sinais verdes: pare e escreva a skill agora.
🚫 Quando NÃO vale
Tão importante quanto saber quando criar é saber quando não criar. A maioria das skills inúteis nasce de um impulso de "vou organizar isso numa skill" para algo que não precisava. Três sinais vermelhos indicam over-engineering.
✗ NÃO crie skill quando...
- ✗Tarefa one-off: você vai fazer isso uma vez só. Skill é overhead puro.
- ✗O modelo já faz sozinho: formatar markdown, traduzir, resumir — capacidade nativa, sem ganho.
- ✗Query simples de 1 passo: "qual a capital da França?" não vira skill.
- ✗Você ainda não tem o processo claro nem na sua cabeça.
✓ Faça outra coisa
- ✓One-off → apenas peça no prompt da hora.
- ✓Capacidade nativa → confie no modelo, não duplique.
- ✓1 passo → uma frase no prompt resolve.
- ✓Processo difuso → faça manual 3x, então extraia o padrão.
O teste do "já faz sozinho"
Antes de criar, rode a tarefa sem skill (baseline). Se o resultado já está bom, a skill não agrega — só ocupa contexto. Skill só vale se o delta com-skill vs baseline for visível.
🌳 Skill vs CLAUDE.md vs MCP vs subagente
Quatro ferramentas resolvem problemas diferentes. Escolher a errada é o erro de design mais comum. A árvore de decisão abaixo te leva à escolha certa com duas ou três perguntas.
CLAUDE.md — sempre-ativo
Regras que valem em toda sessão, sem gatilho. Estilo de resposta, idioma, proibições gerais. Pesa no contexto o tempo todo — use só para o que é universal.
MCP — conexão
Servidor que dá ao agente ferramentas para falar com serviços externos (banco, API, browser). MCP é encanamento; skill é conhecimento. Não confunda.
Subagente — isolamento
Trabalho pesado, paralelo e com contexto próprio (ex.: buscar em todo o repo). Mantém o contexto principal limpo. Pode até usar skills dentro dele.
Skill — sob-demanda
Conhecimento que dispara só quando a description bate. Não pesa quando irrelevante. É a escolha padrão para workflow repetível + contexto que não cabe sempre no CLAUDE.md.
🐘 Anti-padrão: escopo gigante
O primeiro anti-padrão que mata skills: a tentação de criar uma skill "tudo-sobre-X". Uma skill de 800 linhas que cobre React inteiro, do useState ao deploy. Parece eficiente. É o oposto.
✗ Escopo gigante
- ✗
tudo-sobre-react.mdcom 800 linhas - ✗Description vira genérica: "ajuda com React"
- ✗Dispara em tudo ou em nada
- ✗Agente absorve mal — instrução diluída
- ✗Impossível de testar e versionar
✓ Skills atômicas
- ✓
react-component-scaffold - ✓
react-hooks-conventions - ✓
react-a11y-guidelines - ✓Cada uma com gatilho preciso e <500 linhas
- ✓Compõem juntas quando o contexto pede
A regra de divisão — um gatilho por skill:
# ✗ ANTES (uma skill, vários gatilhos misturados) skills/ tudo-sobre-react/SKILL.md # 800 linhas, dispara em "react" # ✓ DEPOIS (uma responsabilidade cada) skills/ react-component-scaffold/SKILL.md # dispara em "novo componente" react-hooks-conventions/SKILL.md # dispara em "usar hook / estado" react-a11y-guidelines/SKILL.md # dispara em "acessibilidade"
💡 Heurística de divisão
Se você não consegue escrever uma description de uma frase que diga exatamente quando a skill dispara, ela está grande demais. Cada gatilho distinto = uma skill. Atomicidade não é estética: é o que faz o trigger funcionar.
📢 Anti-padrão: MUSTs em maiúscula e overfit
O segundo anti-padrão: encher a skill de "VOCÊ DEVE SEMPRE" em caixa-alta e colar exemplos específicos demais. O modelo decora os casos exatos e falha em qualquer variação. A skill passa nos seus testes e quebra na vida real — isso é overfit.
overfit vs generalização:
# ✗ OVERFIT (decora o caso, não o princípio) VOCÊ DEVE SEMPRE nomear o arquivo de "Button.tsx". VOCÊ DEVE SEMPRE usar a cor #14b8a6. # ✓ GENERALIZA (ensina o porquê, vale fora dos exemplos) Nomeie componentes em PascalCase, igual ao nome exportado, porque o resolver de imports e a navegação do editor dependem dessa correspondência. Ex.: Button → Button.tsx, UserCard → UserCard.tsx.
✗ MUSTs e overfit
- ✗Caixa-alta e imperativos gritados
- ✗Exemplos colados como regras fixas
- ✗Nenhuma explicação do porquê
- ✗Quebra em qualquer caso novo
✓ Princípio + porquê
- ✓Imperativo calmo, normal
- ✓Exemplos ilustram, não engessam
- ✓Explica a razão por trás
- ✓Generaliza para casos novos
Por que o porquê importa
O modelo é bom em raciocinar a partir de princípios. Quando você explica a razão ("porque o resolver de imports depende disso"), ele aplica a regra corretamente em situações que você nunca previu. MUSTs em maiúscula só sinalizam ansiedade — não aumentam a aderência e ainda incentivam decorar em vez de entender.
🎯 Anti-padrão: description vaga
O terceiro anti-padrão — e o mais letal. A description é o gatilho: o único nível da skill que fica sempre no contexto. Se ela for vaga, a skill nunca dispara (subdisparo) ou dispara no contexto errado. Uma skill brilhante com description ruim é invisível.
gatilho ruim vs gatilho bom:
# ✗ VAGA (nunca dispara ou dispara errado) description: Ajuda com código. # ✓ ESPECÍFICA (diz O QUE faz E QUANDO usar) description: Gera componentes React com a convenção do time (PascalCase, hooks, props tipadas). Use quando o usuário pedir um novo componente, refatorar JSX, ou criar UI em React/Next. Acione também ao mencionar "componente", "tela" ou "página" num projeto React.
Diga O QUE faz
A capacidade concreta, não a área. "Gera componentes React com a convenção do time" — não "ajuda com frontend".
Diga QUANDO usar
Os gatilhos explícitos: verbos e substantivos que aparecem no pedido do usuário. "Use quando pedir novo componente, refatorar JSX...".
Seja um pouco pushy
O modelo tende a subdisparar. Inclua "acione também ao mencionar X" para os casos limítrofes. Melhor disparar a mais do que sumir quando deveria aparecer.
💡 O teste de 5 segundos
Leia só a description (sem o corpo). Você consegue dizer exatamente em que pedido ela deveria disparar? Se hesitou, o modelo também vai hesitar. A description é a única parte que decide se a skill existe na prática.
✅ Resumo do Módulo
Próximo Módulo:
5.2 — 🚀 Publicar, versionar e medir — você decidiu que vale e evitou os anti-padrões; agora leve a skill ao mundo: repo, git, skills.sh, evals de gatilho e o ciclo de vida