🏗️ Anatomia de uma Skill que Funciona

O nome de uma skill não é apenas um rótulo — é o identificador primário pelo qual o sistema inteiro a reconhece e pelo qual você a invoca. Um nome ruim contamina tudo que vem depois: cria colisões com outras skills, dificulta o invoke manual e torna impossível auditar o inventário de forma inteligente. A regra é direta: o nome deve ser específico o suficiente para ser inequívoco e descritivo o suficiente para comunicar a função sem precisar abrir o arquivo.

A convenção de nomenclatura mais eficaz segue o padrão domínio-função: "n8n-workflow-patterns", "code-review-python", "session-handoff", "brand-guidelines". Em poucos caracteres, você sabe o contexto de uso e a função principal. Evite nomes genéricos como "helper", "assistant", "tool" ou "workflow" — eles são inutilizáveis para triagem e criam confusão em um inventário com 10 ou mais skills.

A descrição no frontmatter é o contrato entre a skill e o sistema de seleção do Claude. É o texto que o Claude usa para decidir, em frações de segundo, se deve invocar esta skill para o contexto atual. Uma descrição que não menciona os casos de uso concretos e as palavras-chave de trigger vai resultar em uma skill que nunca dispara automaticamente — ou que dispara na hora errada.

A estrutura ideal de uma descrição de gatilho inclui: o que a skill faz (uma frase), quando usar (condições específicas), e palavras-chave que provavelmente aparecerão nas conversas onde a skill é relevante. A descrição é uma declaração de intenção e um filtro de relevância ao mesmo tempo. Invista tempo aqui — é onde a maioria das skills falha silenciosamente.

Progressive disclosure é a técnica de organizar o conteúdo da skill em seções nomeadas, onde cada seção é relevante apenas para determinados contextos de uso. Em vez de um bloco monolítico de instruções que o Claude processa inteiramente, você cria uma estrutura navegável onde o Claude lê apenas o que é pertinente à tarefa atual. O resultado é uma skill mais eficiente, menos propensa a confusões e significativamente mais poderosa.

A estrutura típica com disclosure inclui: uma seção de visão geral sempre carregada, seções de instruções para casos de uso específicos, exemplos organizados por cenário, e referências técnicas consultadas sob demanda. Headers com nomes descritivos funcionam como índices que o Claude usa para navegar o conteúdo sem precisar ler tudo linearmente.

Skills de alta qualidade não entram em execução imediatamente ao ser invocadas — elas primeiro fazem perguntas estratégicas para entender o contexto específico do usuário. Essa fase de "entrevista" é inspirada em como consultores experientes trabalham: antes de propor qualquer solução, eles diagnosticam. A skill que pergunta antes de agir produz outputs significativamente melhores e reduz o retrabalho quase a zero.

A UX de entrevista na prática é simples: na seção de início da skill, você instrui o Claude a fazer 2-4 perguntas essenciais antes de executar qualquer parte do fluxo principal. As perguntas devem ser cirúrgicas — focadas nos pontos de variação que mais impactam a qualidade do output. Não é um interrogatório, é uma coleta de contexto precisa e rápida que torna tudo que vem depois mais acertado.

Uma skill que termina o trabalho e encerra a conversa desperdiça uma oportunidade valiosa: o fechamento do loop de aprendizado. A reflexão final é uma seção instruindo o Claude a, ao concluir o trabalho principal, fazer uma síntese estruturada do que foi feito, identificar pontos de melhoria observados durante a execução, e sugerir próximos passos concretos para o usuário.

Esse fechamento estruturado tem múltiplos benefícios: o usuário recebe uma visão consolidada do trabalho, o Claude é forçado a revisar o que produziu antes de encerrar (o que frequentemente captura inconsistências), e a conversa termina com direcionamento claro em vez de uma resposta solta. Skills com reflexão final têm taxas de satisfação significativamente maiores do que skills que simplesmente entregam o output e param.

Miguel Ângelo dizia que o bloco de mármore já continha a estátua — seu trabalho era apenas remover o que não era ela. Skills funcionam de forma similar: você não cria a skill perfeita na primeira versão. Você cria uma versão funcional, usa ela, observa onde ela falha ou deixa a desejar, e remove ou refina o que não serve. Melhorar 1% a cada uso por 30 dias resulta em uma skill 35% melhor ao final do mês — uma transformação significativa por investimentos mínimos diários.

O hábito de iteração diária é o diferencial entre quem tem skills que funcionam razoavelmente e quem tem skills que são genuinamente extraordinárias. A resistência à iteração é normalmente psicológica: "já funciona, para que mexer?" Mas "funciona razoavelmente" e "é excelente" são distâncias enormes quando multiplicadas pelo uso diário ao longo de meses e anos.