Mapa da trilha
Conteúdo detalhado
🧬 Anatomia de uma Skill
O que é um SKILL.md, o frontmatter name/description, o corpo de instruções e como o Claude descobre e dispara a skill sozinho.
Um arquivo Markdown com frontmatter YAML que ensina o Claude a executar uma tarefa específica sob demanda.
É a unidade mínima de tudo. Quem entende o arquivo entende o sistema inteiro.
Texto, não código. Versionável, legível, portável entre máquinas.
O identificador único da skill, em kebab-case, que o Claude usa internamente.
Nome ambíguo = skill que ninguém acha. É o primeiro campo que importa.
Curto, descritivo, estável. Mudar o name quebra referências.
A frase que diz ao Claude o que a skill faz E quando usá-la. É o que ele lê para decidir disparar.
90% do sucesso de uma skill mora aqui. Description fraca = skill morta.
Faz + Quando. Verbos de ação, gatilhos concretos.
Tudo abaixo do frontmatter: o passo a passo, regras, exemplos e o formato de saída esperado.
É onde a qualidade da execução é definida. Instruções vagas geram resultados vagos.
Workflow, regras duras, formato de saída, princípios.
No início, o Claude só vê name + description de cada skill — nunca o corpo inteiro de todas.
Entender isso explica por que a description é tudo e por que skills demais confundem.
Índice leve, matching semântico, carregamento sob demanda.
Quando o pedido casa com uma description, o Claude carrega aquele SKILL.md e passa a seguir suas instruções.
É a diferença entre uma skill que ativa sozinha e uma que você precisa invocar na mão.
Disparo automático, invocação explícita, contexto da conversa.
📂 Progressive disclosure & estrutura
As pastas references/, scripts/ e assets/, o carregamento sob demanda e a regra de ouro: manter o SKILL.md enxuto.
Estratégia de mostrar primeiro só o essencial e revelar o detalhe só quando ele for necessário.
É o princípio que mantém o contexto leve e a skill rápida e barata de carregar.
Camadas, sob demanda, economia de contexto.
Arquivos de apoio (templates, design systems, tabelas) que o SKILL.md manda ler quando precisar.
É onde mora o detalhe que tornaria o SKILL.md gigante se ficasse inline.
Documentos de apoio, leitura condicional, modularidade.
Scripts (Python, shell, etc.) que a skill executa em vez de pedir ao Claude para reescrever lógica toda vez.
Código determinístico é mais confiável e barato que regenerar a lógica em cada chamada.
Determinismo, reuso, separar lógica de prosa.
Arquivos estáticos — fontes, imagens, templates HTML, exemplos — que a saída usa ou referencia.
Mantém a skill autocontida: tudo que ela precisa viaja junto.
Autocontido, recursos versionados, exemplos de saída.
O SKILL.md deve conter o fluxo e as decisões; o detalhe pesado vai para os arquivos de apoio.
Um SKILL.md inchado custa contexto toda vez que dispara, mesmo quando o detalhe não é usado.
Roteador, não enciclopédia. Aponta, não despeja.
O padrão de instruir o Claude a abrir um arquivo de apoio só em condições específicas.
É o que transforma um conjunto de arquivos em uma skill que se navega sozinha.
Condições de leitura, tabela de roteamento, gatilho por tarefa.
🎯 Descriptions que disparam
A anatomia de uma description que ativa na hora certa: gatilhos, exemplos, anti-padrões e — tão importante quanto — quando NÃO disparar.
Toda boa description tem duas partes: o que a skill produz e em que situações ela deve ser usada.
Descrições que só dizem "o que fazem" não dão ao Claude o sinal de quando disparar.
Capacidade + condição, ação + contexto.
Palavras e pedidos reais ("crie um itinerário", "/travel") que sinalizam que a skill se aplica.
Gatilhos concretos elevam drasticamente a taxa de disparo correto.
Linguagem do usuário, sinônimos, comandos de barra.
Incluir casos de uso curtos dentro da própria description para ancorar o matching.
Exemplos dão ao Claude âncoras semânticas que descrições abstratas não dão.
Casos de uso, âncoras, "use quando...".
Descrições vagas, genéricas demais ou puramente técnicas que não dizem quando usar a skill.
Reconhecer o anti-padrão é o caminho mais rápido para corrigir uma skill que não ativa.
Vago, redundante, sem gatilho, jargão sem contexto.
Deixar claro na description (e no corpo) os casos em que a skill NÃO deve ser usada.
Falsos positivos atrapalham tanto quanto falsos negativos. Limites evitam ambos.
Escopo negativo, "não use para...", desambiguação.
Rodar pedidos reais e variados para ver se a skill ativa quando deve e fica quieta quando não deve.
Description é hipótese; só o teste confirma. É um loop, não um chute único.
Casos de teste, falso positivo/negativo, iteração.