🧬 Anatomia de uma Skill

Todo SKILL.md tem duas partes: um bloco de frontmatter YAML delimitado por --- no topo, seguido do corpo em Markdown com as instruções.

É o esqueleto de toda skill. Errar a estrutura faz o arquivo nem ser reconhecido pelo agente.

delimitadores --- · YAML · corpo Markdown · campos obrigatórios

O identificador da skill — sempre em kebab-case minúsculo (ex.: frontend-design), único dentro do agente.

É como a skill é referenciada e instalada. Nome ambíguo ou com maiúsculas/espaços quebra a ativação.

kebab-case · lowercase · unicidade · igual ao nome da pasta

A frase que o agente lê para decidir se ativa a skill. Deve dizer o que ela faz e exatamente quando usá-la.

É o campo que mais impacta o disparo. Uma description vaga = skill que nunca ativa.

gatilho · O QUE + QUANDO · exemplos de uso · pushy

As instruções de verdade. Escritas em modo imperativo, explicando o PORQUÊ e mostrando padrões de output e exemplos.

É onde o comportamento real é definido. Texto longo e sem foco dilui a skill.

imperativo · explicar o porquê · exemplos · sem MUSTs gritados

Pastas ao lado do SKILL.md: scripts/ para código determinístico, references/ para docs sob demanda e assets/ para templates.

Organizar recursos mantém o SKILL.md enxuto e permite carregar só o necessário.

scripts/ · references/ · assets/ · bundled resources

Comparar um SKILL.md de 5 linhas com o frontmatter real da skill frontend-design da Anthropic.

Ver um exemplo de produção mostra o nível de detalhe que uma description vencedora carrega.

exemplo mínimo · frontmatter real · frontend-design · 488k installs

A skill carrega em camadas: metadata sempre presente, corpo quando dispara, recursos sob demanda.

Entender as camadas é o que permite escrever skills grandes sem inchar o contexto.

nível 1 metadata · nível 2 corpo · nível 3 recursos · contexto

Apenas name + description (~100 palavras) ficam carregados o tempo todo no contexto do agente.

É o único nível sempre presente — por isso a description precisa carregar todo o peso de disparo.

~100 palavras · sempre carregado · custo de contexto

O corpo Markdown (recomendado abaixo de 500 linhas) só entra no contexto quando a skill é ativada.

Manter o corpo enxuto melhora a aderência do agente às instruções.

<500 linhas · carregado sob disparo · foco

Arquivos em scripts/, references/ e assets/ — tamanho ilimitado, lidos ou executados só quando necessários.

Scripts executam sem trazer o código pro contexto — é assim que skills ficam poderosas e baratas.

ilimitado · sob demanda · execução determinística

A arte de escrever a description: o que faz, quando usar e gatilhos explícitos, sendo um pouco pushy.

Claude tende a SUBDISPARAR skills; uma description mais assertiva corrige isso.

pushy · subdisparo · o que + quando + gatilhos

Quebrar referências por domínio (aws.md, gcp.md, azure.md) e dar índice em arquivos com mais de 300 linhas.

O agente lê só o arquivo relevante, economizando contexto e mantendo precisão.

divisão por domínio · leitura seletiva · tabela de conteúdo

Aprender a escrever SKILL.md dissecando os mais instalados do ecossistema e extraindo seus padrões.

Cada skill campeã resolve um trade-off diferente; juntas formam um catálogo de moldes prontos.

roubo honesto · forma vs conteúdo · trade-offs · catálogo de padrões

A skill mais instalada da Anthropic; description que diz o quê, quando (com exemplos) e o diferencial, sem pastas.

É o arquétipo mais comum: uma competência só, corpo único, fácil de manter.

verbo de ação · exemplos como gatilho · diferencial final · zero pastas

O exemplo canônico de skill grande organizada por pastas (~33KB), com ponteiros do corpo para os recursos.

É o molde para quando há código reutilizável, docs longos e templates de saída.

scripts/ · references/ · assets/ · ponteiros no corpo

Description agressiva que começa com "Use when doing ANY task" e lista Triggers por categoria.

É o padrão quando a skill é o porteiro de uma plataforma inteira e precisa disparar em qualquer ponta.

Triggers: categorizados · ANY assertivo · metadata · Core Principles

Skills enormes que usam USE FOR / DO NOT USE FOR na description e uma tabela de sub-skills no corpo.

É como escalar uma skill operacional sem disparo errado nem perda de controle.

USE FOR / DO NOT USE FOR · tabela de sub-skills · pre-execution

Um decisor rápido: cada anatomia é a resposta a uma pergunta sobre a sua skill.

Saber escolher o molde certo evita refazer a estrutura depois.

competência única · multi-arquivo · porteiro · operacional grande

O trajeto de seis paradas da criação: intent, frontmatter, corpo, pastas, empacotar, iterar.

Ter o mapa evita começar grande demais; um SKILL.md válido nasce com só frontmatter + corpo.

seis etapas · começar minúsculo · pastas opcionais

O identificador da skill em kebab-case minúsculo, sem espaços nem maiúsculas, igual ao nome da pasta.

Divergência entre name e pasta quebra o carregamento da skill.

kebab-case · lowercase · name = pasta · sem sufixos

A fórmula da description: o que faz, quando usar e gatilhos concretos, em ~100 palavras pushy.

É o único texto sempre carregado e o que faz a skill disparar; Claude subdispara por padrão.

fórmula · ~100 palavras · pushy · palavras-chave reais

O corpo Markdown em modo imperativo, com título, When to Use, Steps numerados e Output Format.

É onde o comportamento real é definido; explicar o porquê vence MUSTs gritados em maiúscula.

imperativo · When to Use · Steps · Output Format

O gatilho para criar cada diretório: determinístico → scripts/, docs longos → references/, saída → assets/.

Pastas nascem da necessidade, não da estética; cada arquivo precisa de um ponteiro no corpo.

scripts/ determinístico · references/ sob demanda · assets/ saída

Um SKILL.md inteiro pronto: frontmatter, When to Use, Steps, Output Format e ponteiros para as pastas.

Copiar, trocar os nomes e instalar é o caminho mais rápido para a sua primeira skill.

template pronto · instalável · base para iterar

Pôr em prática os 3 níveis: o SKILL.md vira um menu e cada arquivo só entra quando aquela rota é escolhida.

É o que permite skills cobrirem dezenas de serviços sem estourar o contexto.

menu · rotas · carregamento seletivo · economia de contexto

Organizar referências por variante e deixar o corpo rotear; o agente lê só o arquivo relevante.

Três arquivos de 300 linhas economizam 66% de contexto frente a um de 900 e facilitam manutenção.

domain organization · tabela de roteamento · leitura seletiva

Tarefas determinísticas viram scripts que executam e devolvem só a saída; o código nunca entra no contexto.

Mais confiável e barato que instruir o agente a raciocinar o passo a passo.

determinístico · execução sem contexto · extração de helper repetido

Adicionar uma tabela de conteúdo no topo de todo arquivo de referência com mais de 300 linhas.

O agente vai direto à seção certa sem reler o arquivo inteiro; se ainda for grande, particione.

índice no topo · âncoras · partição por subtema

Manter o corpo abaixo de 500 linhas movendo detalhes para references/ e deixando pointers claros.

O corpo entra inteiro no contexto a cada disparo; hierarquia paga o custo só quando preciso.

limite de 500 linhas · mover detalhes · pointers de "quando ler"

assets/ guarda templates, fontes e ícones preenchidos no output, distinto de references/ (que se lê).

Fecha o checklist do que separa uma skill brinquedo de uma como azure-ai ou supabase.

assets preenchidos · scripts vs references vs assets · checklist final