🧭 Quando vale uma skill (e os anti-padrões)
A árvore de decisão completa: workflow repetível ou one-off? Skill, CLAUDE.md, MCP ou subagente? E os três anti-padrões que matam skills antes mesmo de disparar.
Uma skill se justifica quando há um workflow repetível, conhecimento de contexto do time, output verificável e tarefa multi-step. Quando ≥2 desses sinais aparecem, vale empacotar.
Skill mal aplicada vira ruído no contexto. Saber os sinais verdes evita criar skills que ninguém dispara — e que poluem o catálogo.
workflow repetível · conhecimento de contexto · output verificável · multi-step
Tarefa one-off, algo que o modelo já faz sozinho com qualidade, ou uma query simples de 1 passo não precisam de skill. Skill aqui é over-engineering.
A maioria das skills ruins é criada para problemas que não existiam. Reconhecer o anti-caso poupa esforço e mantém o agente leve.
tarefa one-off · capacidade nativa do modelo · query de 1 passo
Quatro ferramentas, quatro propósitos: CLAUDE.md para regras sempre-ativas, MCP para conectar serviços externos, subagente para trabalho isolado paralelo, e skill para conhecimento que dispara sob demanda.
Usar a ferramenta errada é o erro mais comum. Skill não é MCP, e regra global não é skill. A árvore de decisão resolve em segundos.
sempre-ativo vs sob-demanda · conhecimento vs conexão vs isolamento
A skill "tudo-sobre-react" de 800 linhas que tenta cobrir tudo. O agente absorve mal, a description fica vaga e o trigger nunca acerta. Divida em skills atômicas.
Escopo gigante é o anti-padrão mais sedutor — parece eficiente, mas degrada tanto o trigger quanto a qualidade da resposta.
atomicidade · uma responsabilidade · <500 linhas · split por gatilho
Encher a skill de "VOCÊ DEVE" em maiúscula e colar exemplos específicos demais. O modelo decora os casos e falha fora deles. Explique o PORQUÊ e generalize além dos exemplos.
Overfit é silencioso: a skill passa nos seus testes e quebra na vida real. Entender o porquê torna a instrução robusta.
explicar o porquê · generalização · imperativo calmo · evitar overfit
A description é o gatilho. Se ela for vaga ("ajuda com código"), a skill nunca dispara — ou dispara errado, no contexto errado. Diga O QUE faz E QUANDO usar.
Uma skill brilhante com description ruim é invisível. O gatilho é o único nível sempre no contexto — vale ouro investir nele.
o que + quando · um pouco pushy · evitar subdisparo · triggers explícitos
🚀 Publicar, versionar e medir
Do repo GitHub ao skills.sh: estrutura de pasta, versionamento via git, aparecer no diretório, medir triggering, segurança e o ciclo de vida completo da skill.
Um repo publicável tem uma pasta skills/, e dentro dela cada skill com seu SKILL.md mais os resources (scripts/, references/, assets/). Convenção que o CLI e o skills.sh entendem.
Estrutura fora do padrão = skill não é indexada nem instalável. A convenção é o passaporte para o ecossistema.
pasta skills/ · SKILL.md · scripts/ references/ assets/ · progressive disclosure
Skills vivem em git. Como são instaladas como symlinks, um git push + npx skills update propaga a nova versão para todos que instalaram. Versionar bem importa.
Você não controla só seu repo — controla o comportamento de quem instalou. Versionamento descuidado quebra agentes alheios.
git como fonte · symlink · npx skills update · changelog
O skills.sh indexa repos públicos e mostra install count como métrica social. É a vitrine: das 39.366 skills do catálogo, só 0,3% passam de 100k installs.
Descoberta é metade do jogo. Entender a lei de potência do catálogo calibra expectativas e estratégia de naming/description.
install count · leaderboard · lei de potência · 53,9M installs somadas
A description dispara nos casos certos? Você mede com evals de gatilho: listas de queries should-trigger e should-not-trigger, mais os near-misses que confundem.
Triggering é o KPI mais ignorado. Sem medir, você não sabe se a skill some no contexto certo ou invade o errado.
should-trigger · should-not-trigger · near-miss · precisão/recall do gatilho
Uma skill não deve fazer nada que o usuário não esperaria pela description — nada de deletar arquivos, enviar dados ou rodar comandos destrutivos surpresa.
Skills rodam com a confiança do usuário. Uma surpresa destrutiva queima a reputação do repo inteiro — e do ecossistema.
não-surpresa · least privilege · transparência · auditar resources
Publicar não é o fim: é publicar → observar installs e feedback → iterar na description e no corpo → republicar. E onde continuar aprendendo: o portal INEMA.CLUB.
Skill é produto vivo. O ciclo de vida fecha o curso e te dá o mapa de para onde ir depois da sua primeira skill.
publicar · observar · iterar · INEMA.CLUB
⭐ As Melhores Skills de Processo
As skills mais amadas não ensinam um domínio — ensinam COMO pensar e trabalhar. test-driven-development, a família superpowers e o padrão de process skills (rígida vs flexível).
Skill de domínio codifica "o que saber sobre X" (React, Postgres). Skill de processo codifica COMO trabalhar — independente do assunto e da stack.
Processo tem mercado total maior e é o que falta no agente por default — por isso domina o topo dos installs.
domínio vs processo · agnóstico de stack · trigger por tipo de tarefa
A process skill mais instalada de Testing (obra/superpowers). Força escrever o teste que falha ANTES da implementação.
Muda o comportamento padrão preguiçoso do agente: cada feature nasce com cobertura real, "passa nos testes" deixa de ser teatro.
red · green · refactor · output verificável
brainstorming, systematic-debugging, writing-plans e verification-before-completion — cada uma muda um comportamento do agente em um momento específico.
São o modelo de process skills atômicas que se invocam entre si — o oposto da skill "tudo-sobre-X".
brainstorming · systematic-debugging · writing-plans · verification
O espectro das process skills: rígida (sequência fixa que não admite desvio) vs flexível (princípios que o agente adapta ao contexto).
Escolher errado no espectro é anti-padrão: rígida onde o caso varia gera atrito; flexível com MUSTs gera overfit.
rígida · flexível · errar dói → rígida · valor é julgamento → flexível
Corrigem o default preguiçoso, servem qualquer linguagem/projeto (mercado total enorme) e o ganho se acumula em todo trabalho.
Entender o porquê do amor te diz que tipo de skill vale criar — uma process skill bem feita rompe a média de um grupo morno.
corrige default · mercado total · efeito composto · Testing&QA
Os padrões que tornam uma process skill amada: atômica, trigger por tipo de tarefa, explica o porquê, compõe com outras.
Você não precisa publicar a próxima superpowers — basta aplicar esses padrões na sua skill.
atômica · agnóstica de stack · explica o porquê · compõe
🛠️ Como Criar: Da Decisão ao Publish
O caminho concreto: o checklist de decisão antes de criar, estruturar o repo, versionar via git e os comandos exatos — npx skills add / update — pra ir ao ar no skills.sh.
Quatro perguntas (repetível? contexto? verificável? multi-step?) e a árvore que escolhe entre skill, CLAUDE.md, MCP e subagente.
Usar a ferramenta errada é o erro mais comum. O filtro separa skill útil de poluição de catálogo.
≥2 sins → vale · sempre-ativo vs sob-demanda · conhecimento vs conexão
A convenção que o CLI e o skills.sh entendem: pasta skills/ na raiz, cada skill com SKILL.md (frontmatter + corpo) + scripts/ references/ assets/.
Fora do padrão = skill não é indexada nem instalável. A convenção é o passaporte para o ecossistema.
skills/ · SKILL.md · frontmatter name+description · resources
Git é a fonte da verdade. Symlinks fazem o push propagar para quem instalou — trate a main como produção, use branch + PR + CHANGELOG.
Você controla o comportamento de quem instalou, não só seu repo. Versionamento descuidado quebra agentes alheios.
git fonte · symlink · main = produção · CHANGELOG
npx skills add ./local pra testar antes, add owner/repo pra produção e update pra puxar as últimas versões.
O symlink torna o loop de teste rápido: edite o SKILL.md local e já reflete. É como você itera antes de publicar.
add ./local · add owner/repo · update · com-skill vs baseline
Repo público com a pasta skills/ na convenção certa; o skills.sh indexa e expõe o install count. name + description são a vitrine.
Descoberta é metade do jogo. O mesmo texto que serve de gatilho vende a skill na busca — dois pássaros.
repo público · indexação · install count · naming vende
Decidir → estruturar → testar local → afinar gatilho → versionar → ir ao ar → medir. A sequência única que você segue hoje.
Junta tudo num roteiro acionável — da decisão ao install count rodando.
decidir · estruturar · testar · afinar · versionar · publicar · medir
🚀 Dicas Avançadas: Governança, Segurança e Escala
O nível profissional: skills internas, princípio da não-surpresa, estratégia de versionamento, rollout em time, medir adoção e manter dezenas de skills vivas. Fecha o curso.
Conhecimento proprietário e fluxos do time viram skills marcadas com metadata.internal, instaladas só com a flag INSTALL_INTERNAL_SKILLS.
Evita vazar contexto sensível no catálogo público e poluir o skills.sh com ruído só-seu.
metadata.internal · INSTALL_INTERNAL_SKILLS · opt-in explícito
A skill nunca faz o que a description não promete: nada de exfiltração, rm -rf escondido ou acesso a segredos sem pedir. Least privilege.
Symlink + update propagam para muita gente. Uma quebra de confiança queima o repo inteiro e respinga no ecossistema.
não-surpresa · least privilege · auditar resources · sem malware
Classifique cada mudança por risco. Mexer na description é potencial major, porque altera quando a skill dispara para todos.
Em escala, push na main sem estratégia vira instabilidade. Disciplina de versão separa o seguro do arriscado.
patch · minor · major · description = mudança de gatilho · tags
Centralize skills aprovadas num repo curado, pilote num subgrupo antes do geral e comunique antes de cada update de gatilho.
Distribuir para um time quer consistência e controle — diferente de publicar para o mundo aberto.
repo curado · piloto · comunicar update · onboarding via README
Duas métricas que cruzam numa matriz: install count (descoberta) e triggering (precisão do gatilho). O pior cenário é muito install com gatilho ruim.
Skill em escala é produto, e produto se mede. Cada quadrante pede uma ação diferente.
install count · triggering · matriz de adoção · evals
Evals no CI, auditar sobreposição de gatilhos, aposentar skills mortas e manter o corpo enxuto — para que um portfólio de dezenas não apodreça.
Uma skill é fácil; vinte são um produto. E aqui o curso fecha — daqui é prática e o portal INEMA.CLUB.
evals no CI · sobreposição · aposentar · enxuto · INEMA.CLUB
Mapa da trilha
Decida em 30 segundos: skill ou não? E pare de matar suas skills sem querer.
Do git ao skills.sh. Publique, meça o gatilho e itere como produto vivo.
As mais amadas não ensinam um domínio — ensinam como pensar e trabalhar.
Da pergunta "vale a pena?" ao npx skills add rodando no skills.sh.
Skills internas, não-surpresa e portfólio vivo. O fecho do curso.
🎓 Fim da jornada — e começo da sua
Esta é a última trilha do curso. Você já sabe o panorama, a qualidade, a anatomia, o loop de criação e agora os modelos mentais de decisão e publicação. O próximo passo é publicar sua primeira skill — e continuar aprendendo no portal.