🔬 Anatomia de uma skill Claude
Frontmatter, description, corpo, referências. O que o modelo vê sempre e o que só carrega sob demanda.
Skill = pasta com SKILL.md (mais frontmatter) + references/ (opcional). Claude carrega quando detecta gatilho no description.
Entender a mecânica te permite criar a sua. Skills são o jeito mais poderoso de extender o Claude.
SKILL.md, frontmatter YAML, references folder, carregamento sob demanda.
Metadados entre --- no topo do SKILL.md. Dois campos: name (identificador) e description (texto que o modelo usa para roteamento).
É a parte mais importante da skill. Description ruim = skill nunca ativa. Description bom = ativa quando precisa.
YAML frontmatter, name, description, sempre carregado.
Nome único da skill (ex: fs-seis-chapeus). Deve casar com nome da pasta. Usado em logs e referências.
Nomeação consistente facilita manutenção quando você tem 10+ skills.
Prefixo (fs- para fersora), kebab-case, descritivo mas curto.
Texto curto (200-400 palavras) que descreve QUANDO a skill deve ativar. Lista gatilhos explícitos e contextos.
Esse texto é o único que o modelo sempre lê. É onde a "personalidade" da skill vive.
Roteamento, gatilhos explícitos, sempre carregado, 200-400 palavras.
Markdown com as regras, fluxo, formato de saída. Carregado quando a skill ativa. Não toma espaço até lá.
É aqui que você define como a skill opera. Deve ser completo, mas não verbosa — cada frase tem custo.
Instruções operacionais, formato de saída, regras não-negociáveis.
Arquivos .md que o modelo só lê quando o SKILL.md referencia explicitamente ("ver references/X.md").
Permite ter skills ricas sem inchar o contexto. Tabelas, exemplos longos, catálogos vão aqui.
Carregamento sob demanda, modularização, economia de contexto.
🎯 A description como roteador
Por que os gatilhos são cirúrgicos. Como calibrar para ativar quando precisa (e só quando precisa).
Frases exatas que aparecem no description entre aspas ou itálico. O modelo as trata como keywords de ativação.
Gatilho explícito = ativação previsível. Sem gatilho, você fica na mão da interpretação do modelo.
Keyword, aspas, lista explícita.
Além de gatilhos, descrever situações. Ex: "tensão emocional+técnica misturada" ou "decisão irreversível".
Contextos captam casos que o usuário não vai saber nomear — a skill ativa mesmo sem palavra-chave.
Situação, padrão reconhecível, gatilho implícito.
Descrever quando a skill NÃO deve ativar. Ex: "não ativar para perguntas factuais simples".
Exclusão reduz falsos positivos. Skill que ativa demais queima credibilidade.
Seção "NÃO usar", falso positivo, sobreativação.
Incluir sinônimos comuns. "Seis chapéus", "6 chapéus", "six hats", "six thinking hats".
Usuário nunca lembra a frase exata. Cobrir variantes garante ativação.
Variantes linguísticas, sinônimos, robustez.
Análise parte-a-parte do description atual. Cada frase tem função: roteamento, exclusão, gatilho explícito, contexto.
Ver um description bem feito ajuda a calibrar o olho para o seu.
Desconstrução, cada frase com função.
Criar 10 mensagens de teste: 5 que devem ativar, 5 que não devem. Verificar comportamento.
Feedback loop rápido. Iterar no description até acertar os 10 casos.
Conjunto de testes, iteração, calibração.
💻 Regras como código
Por que "proibido X" funciona melhor que "tente não X". Enunciação, proibições, checklists.
"Você deve X" é imperativo. "Tente X" é sugestão. Imperativo é cumprido 90%+. Sugestão é cumprida às vezes.
Skill com sugestão vira "tentativa". Skill com imperativo é confiável.
Verbo forte, obrigatoriedade, tom técnico.
Regras em forma de proibição: "PROIBIDO X", "nunca Y". Melhor do que "evite" ou "tente não".
Proibição é binária: ou tem ou não tem. Sugestão é gradiente, e o modelo vai gravitar pro meio.
Binário, maiúsculas para destacar, PROIBIDO.
Lista de items "antes de entregar, verifique". O modelo percorre antes de finalizar.
Checklist transforma regra em ritual. Aumenta compliance de 70% para 95%.
Checklist final, auto-revisão, gate antes de entregar.
Pequenos testes embutidos: "se aparecer 'porque' no Vermelho, a frase é inválida". O modelo aplica como assertion.
Teste operacional pega erro antes de sair. Skill mais robusta.
Assertion, teste embutido, early fail.
Regras sem exceção explícita. "Sempre X" é melhor que "quase sempre X, exceto quando Y".
Exceções viram buracos. Modelo gravita pras exceções quando é conveniente.
Sem exceção, monolítico, simplicidade brutal.
Oficina: pegar 5 regras fracas e reescrever em forma imperativa, monolítica, testável.
A parte prática. Você ganha olho para detectar regras fracas.
Exercício, detecção de fraqueza, reescrita.
📁 Modularização com references/
Quando dividir em arquivos. Por que variants, frameworks, anti-patterns e examples são separados.
Se a informação é (1) opcional — nem toda sessão precisa, (2) longa — tabela, lista extensa, (3) coesa — um tema só.
Dividir de menos = SKILL.md gigante carregado à toa. Dividir demais = fricção.
Opcional, longo, coeso — os 3 critérios.
Catálogo das 7 variantes de ordem. Só é consultado quando a Fase 0 decide qual usar.
Exemplo perfeito: opcional (só consulta quando decide), longo (7 × detalhamento), coeso (um tema).
Catálogo, tabela de decisão, referência.
Os 10 marcos (A-J) em detalhe. Consultado quando o Chapéu Verde é ativado.
Carregar os 10 marcos todo turno seria custoso. Sob demanda é eficiente.
Catálogo especializado, ativação por fase.
Catálogo de erros com sintoma + teste + correção. Usado como auto-revisão antes de entregar.
Ter anti-padrões como arquivo separado permite que a skill se auto-audite.
Auto-auditoria, pattern recognition, correção.
2-3 sessões completas ilustrativas. Só consultado quando o modelo precisa calibrar formato da saída.
Exemplos valem mais que regras. Um modelo "vê" o formato e imita.
Few-shot learning, imitação, calibração de formato.
Arquivos em kebab-case. Nome descritivo do conteúdo. Sempre .md (markdown). Sempre singular ou plural consistente.
Consistência de nomes reduz fricção quando você tem 10+ skills com references/.
kebab-case, descritivo, consistência.
🧱 Isolamento como engenharia de prompt
Como forçar o modelo a "esquecer" os outros chapéus. Linguagem monolítica, auto-revisão, testes.
LLM tende a "equilibrar" — se vê Amarelo, quer adicionar "mas também há riscos" naturalmente. Quebrar isso é engenharia.
O instinto de equilibrar é o que quebra o isolamento. Precisa ser proibido explicitamente.
Bias de equilíbrio, instinto do LLM, proibição explícita.
Cada chapéu é "monolítico": só aquele modo, sem exceção. Palavra-chave do SKILL.md.
Palavras como "monolítico" viram commandos. Modelo leva a sério.
Monolítico, commando-palavra, severidade de linguagem.
Template com cabeçalhos fixos para cada chapéu. Modelo preenche por seção — fica mais difícil vazar.
Estrutura fixa ajuda o modelo a manter o isolamento mecânico.
Template, cabeçalhos fixos, separação visual.
Checklist no fim do SKILL.md: "antes de entregar, há contaminação cruzada? Se houver, reescrever".
Auto-revisão pega 80% dos vazamentos antes de chegar ao usuário.
Gate final, auto-audit, reescrita se falha.
Gerar 5 sessões teste e procurar "mas", "embora", "também" no chapéu errado.
Teste grep simples. Se contamina 1/5, iterar regra.
Teste grep, iteração, métrica de contaminação.
Análise da regra "sem 'porque' no Vermelho": simples, binária, testável com grep, com correção óbvia. Padrão ouro.
Ver um exemplo perfeito ajuda a calibrar o olho para regras suas.
Regra binária, teste via palavra, correção óbvia.
🛠️ Criando sua própria variante
Workshop final. Criar "três chapéus para decisões pessoais" ou "seis chapéus para code review".
Fork: copiar e adaptar. Herança: "use fs-seis-chapeus com modificação X". Fork é mais simples, herança requer orquestração.
90% dos casos, fork é melhor. Herança complica para ganho marginal.
Fork, herança, trade-off simplicidade vs manutenção.
Novo description com gatilhos específicos da sua variante ("code review", "decisão pessoal").
O description é o que distingue uma skill fork. Sem adaptar, as duas ativam ao mesmo tempo.
Gatilhos específicos, unicidade.
"Seis chapéus para code review": Branco = fatos do código. Amarelo = o que está bom. Preto = bugs/segurança. Verde = refactorings alt.
Adaptar cada chapéu para seu domínio é o coração da variante.
Domain-specific, exemplos por chapéu.
Se seu domínio tem marcos próprios, adicione ao divergence-frameworks.md. Ex: "Padrões de design" para code review.
Marcos domain-specific são mais úteis que os genéricos para problemas especializados.
Extensão, marcos especializados.
Rodar sua skill em 10 casos reais do seu trabalho. Ver o que quebra. Iterar.
Skill não testada no real é teoria. Iteração pós-uso é onde ela vira robusta.
Validação real, iteração, observabilidade.
Lista de 10 items: description testado, regras imperativas, auto-revisão, exemplos, references/ organizado etc.
Checklist evita publicar skill com erro bobo. 5 minutos de ouro antes de merge.
Gate de qualidade, 10 items, auto-audit.