🧬 Fundamentos de Agent Skills

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.

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.

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.

SKILL.md abaixo de 500 linhas, referências linkadas direto dele e sumário no topo de referência com mais de 100 linhas.

Referência aninhada é só pré-visualizada: as regras do fim do arquivo somem sem aviso.

500 linhas, um nível de profundidade, sumário.

Quanto controle cada passo merece: instrução em texto, modelo com variação ou script exato.

Erro caro pede script exato; tarefa aberta pede só a direção.

Risco, fragilidade, "e se o agente fizer diferente?".

O que a skill faz e quando usar, em terceira pessoa, com até 1.024 caracteres; descrição + when_to_use são cortadas em 1.536 na listagem.

O que passa do corte o modelo não vê, e a skill deixa de disparar.

Terceira pessoa, "quando usar", limites de tamanho.

Lista que o agente copia na resposta e marca, com linha de volta, e um loop rodar, corrigir e repetir.

Tarefa longa sem checklist pula passos; saída sem loop sai com o primeiro erro.

Checklist, critério que passa ou falha, verificador.

Rodar a skill nos modelos que vão usá-la e conferir se orienta o bastante sem explicar demais.

Cada modelo reage diferente à mesma instrução.

Haiku orienta? Sonnet econômico? Opus sem excesso?

Linha de instalação para cada pacote, hooks no frontmatter da skill e regras críticas no topo, porque a compactação guarda só os primeiros 5.000 tokens.

É o que faz a skill funcionar na máquina do colega e numa sessão longa.

Instalação, hook, compactação, modelos 5.5.