SKILL.md explicado: todos os campos do frontmatter e a progressive disclosure

O SKILL.md é o contrato inteiro. Tudo o que o agente sabe sobre quando disparar, o que carregar e quais ferramentas pode usar vem de um único arquivo. Erre a estrutura e a skill ou nunca dispara, ou dispara para tudo.

Se você nunca criou uma skill, comece pelo guia para criar skills do Claude Code. Ele cobre a decisão de criar ou não, o processo de destilação e como a arquitetura se compara a um prompt comum. Este artigo é a referência técnica por baixo dele: cada campo do frontmatter, o que faz, quando importa, e o modelo de progressive disclosure em três níveis que mantém o custo de contexto proporcional à complexidade da tarefa.

O arquivo fica em .agents/skills/<your-skill-name>/SKILL.md. Esse caminho é obrigatório. Adicione references/, scripts/ ou assets/ ao lado dele quando a skill precisar de material de apoio. Todo o comportamento da skill está ancorado no SKILL.md.

O que é o SKILL.md

O SKILL.md é o arquivo de entrada de toda skill do Claude Code. Ele tem duas partes: um bloco de frontmatter em YAML que controla como a skill é descoberta, disparada e restringida, e um corpo em Markdown que é o prompt de fato (a persona, o formato de saída, o mapa de carregamento, as restrições). O frontmatter é configuração legível por máquina; o corpo é instrução executável.

A divisão importa porque as duas partes carregam em momentos diferentes. Os campos name e description ficam na camada de listagem de skills que o Claude lê em toda sessão, antes de qualquer skill ativar. Eles custam contexto sempre. O corpo só carrega quando a skill dispara. Os arquivos de referência só carregam quando o corpo manda explicitamente o agente lê-los. Três camadas, cada uma custando contexto só quando faz por merecer.

A tabela de frontmatter abaixo cobre todos os campos. O FileTree mostra a convenção de diretórios. O LayerStack mapeia as três camadas de disclosure. Leia o frontmatter primeiro: ele determina o que carrega, quando, e com qual nível de capacidade.

Todos os campos do frontmatter

O campo description é o principal mecanismo de disparo — não o nome, não o slash command. O Claude lê as descriptions para decidir qual skill corresponde ao pedido do usuário. O resto do frontmatter configura o ambiente de execução ou restringe quais invocações se qualificam: permissões, modelo, nível de esforço, isolamento de contexto. A mesma chave de modelo e esforço por skill, portada para o agente Pi, é o que o pi-skill-model-handoff adiciona. A tabela abaixo cobre todos os campos que a Anthropic documenta.

Referência do frontmatter do SKILL.md

name e description são os únicos campos obrigatórios em qualquer caso. O resto é escopo e configuração: use para deixar as permissões da skill explícitas, não herdadas.

Campo	Obrigatório	Valores / Tipo	Notas
name	sim	string	Vira o slash command /name. Minúsculas, hífens. Também é a coordenada de ativação: quanto mais específico o nome, mais denso o cluster do modelo.
description	sim	string	Principal mecanismo de disparo. Somado ao when_to_use, limitado a ~1.536 caracteres na listagem. Escreva para bater com a intenção do usuário, não para resumir a skill. Puxe para o insistente.
when_to_use	não	string	Complementa a description com cenários de ativação explícitos. Divide o mesmo orçamento de ~1.536 caracteres. Use para edge cases e condições específicas que a description não traz à tona.
argument-hint	não	string	Aparece no autocomplete do slash command. Ex.: 'offer to evaluate' ou 'PR to review'. Mantém a interface autodocumentada.
arguments	não	object	Definições tipadas de parâmetros para invocação estruturada. Útil quando os argumentos controlam ramificações dentro do corpo, ex.: um switch mode: quick | deep.
user-invocable	não	boolean	Padrão true. Defina false para deixar a skill só para o modelo: o agente pode invocá-la como subetapa, mas ela não aparece no menu de slash commands do usuário.
disable-model-invocation	não	boolean	Impede que o modelo invoque a skill por conta própria. Combine com user-invocable: false para controle totalmente manual. A skill só dispara quando o usuário a chama explicitamente.
allowed-tools	não	list	Allowlist das ferramentas que a skill pode usar. Sobrescreve o padrão da sessão. Se omitir, herda todas as ferramentas da sessão, o que costuma ser permissivo demais para uma skill especializada.
disallowed-tools	não	list	Blocklist de ferramentas específicas. Use para barrar Bash, Edit ou Write numa skill que só deveria ler. Transforma um disparo acidental num limite rígido.
model	não	string	Sobrescreve o modelo para esta skill. Rode skills de consulta rápida num modelo menor e mais rápido. Rode skills de análise profunda no mais capaz. Controle de custo mora na config.
effort	não	low | medium | high | xhigh | max	Define o nível de raciocínio. high ou xhigh para auditorias de segurança e análises complexas; low para formatadores e consultas rápidas. max só quando você realmente precisa do raciocínio mais profundo.
context	não	fork	Roda a skill num fork de contexto isolado, separado da conversa principal. Use para skills que fazem bastante trabalho antes de devolver uma resposta. Evita que sessões longas consumam a context window da conversa.
agent	não	string	Delega a invocação para um subagent nomeado. Permite arquiteturas multiagente a partir de um único SKILL.md como ponto de entrada.
hooks	não	object	Hooks antes e depois da invocação. Rode scripts de setup, validação de ambiente ou limpeza em volta da execução da skill sem embutir essa lógica no corpo.
paths	não	list	Restringe o acesso a arquivos a diretórios específicos. Uma skill de code review para um serviço não precisa de acesso ao monorepo inteiro. Restrinja até onde a tarefa permitir.
shell	não	boolean	Habilita ou desabilita explicitamente o acesso a comandos de shell para esta skill. Deixa a permissão visível no arquivo em vez de herdada do contexto da sessão.

Aqui está um bloco de frontmatter funcional para uma skill de revisão de segurança. Repare na lista disallowed-tools: uma skill de review que não pode escrever arquivos não consegue aplicar uma correção por acidente, o que deixa o contrato explícito em vez de depender do julgamento do modelo:

---
name: security-reviewer
description: >
  Reviews code for security vulnerabilities, injection risks, authentication
  gaps, and secrets exposure. Applies OWASP Top 10 as the base checklist.
  INVOKE for any PR touching auth, database queries, file I/O, API endpoints,
  or environment variable handling. Do not invoke for unrelated refactors.
  REQUIRED: read references/00-checklist.md before responding.
when_to_use: >
  Invoke for PRs touching authentication, authorization, input sanitization,
  secrets handling, or third-party dependency additions. Also useful before
  any deployment that changes the attack surface.
effort: high
allowed-tools: [Read, Grep, Glob]
disallowed-tools: [Bash, Edit, Write]
context: fork
---

A description coloca o padrão de disparo logo no começo (“auth, database queries, file I/O, API endpoints”), então o modelo vê o sinal de correspondência imediatamente, antes de a description ser truncada.

Estrutura de diretórios

Um diretório de skill tem um arquivo obrigatório e três subdiretórios opcionais. Toda skill segue a mesma estrutura, o que significa que ferramentas, scripts de CI e outras skills conseguem entender a organização sem inspecionar cada arquivo individualmente.

Estrutura de diretórios de uma skill

• security-reviewer/raiz da skill
  • SKILL.mdobrigatório// frontmatter + corpo do prompt + mapa de carregamento
  • references/// carregado sob demanda por instruções no corpo do SKILL.md
    • 00-checklist.md// sempre carregado: checklist de decisão
    • 01-owasp-top10.md// referência do framework
    • 02-examples.md// exemplos resolvidos e anti-patterns
  • scripts/// código executável que a skill pode rodar
    • validate.sh// pré-checagem do ambiente
  • assets/// arquivos usados na saída: templates, ícones, dados
    • report-template.md// esqueleto da saída

O diretório references/ é onde está a maior parte da alavancagem. Uma skill sem referências responde só com os pesos do modelo. É o mesmo que não ter skill. O corpo do SKILL.md diz ao agente quais arquivos ler e quando. Nada em references/ carrega automaticamente. Essa restrição é a arquitetura, não uma limitação.

Progressive disclosure: três níveis

A progressive disclosure mantém as skills rápidas. O modelo carrega só o que a tarefa atual exige. Cada nível adiciona contexto apenas quando é acionado.

Progressive disclosure: três níveis

1. L1

   Metadados: sempre em contexto

   name e description (e when_to_use) ficam na listagem de skills que o modelo lê em toda sessão, antes de qualquer skill ativar. Esta é a camada de disparo: umas 100 palavras por skill, sempre em contexto. Cada palavra custa. Coloque o sinal na frente: a correspondência mais forte com a intenção do usuário vai na primeira frase, não na terceira.

   name: alex-hormozi-offer-design
   description: >
     Evaluates offers, pricing, guarantees, and value stacks using
     Hormozi's frameworks (Value Equation, Grand Slam Offer, RAISE).
     INVOKE for any question about pricing strategy, risk reversal,
     guarantee design, or offer testing. Do not use for brand/content work.

   +
2. L2

   Corpo da skill: carrega no disparo

   O corpo em Markdown do SKILL.md carrega quando a skill ativa. É o prompt principal: persona, formato de saída, restrições e o mapa de carregamento que direciona o agente para as referências. Mantenha o corpo abaixo de ~500 linhas. Se passar disso, o corpo virou uma referência. Mova o excesso para references/ e adicione uma instrução de carregamento.

   +
3. L3

   Arquivos de referência: carregam conforme a necessidade

   Os arquivos em references/ só carregam quando o corpo do SKILL.md manda explicitamente o agente lê-los. O modelo decide. Nada carrega sozinho. Este é o ponto crítico: sem um mapa de carregamento explícito no corpo, o agente ignora as referências por completo e responde com os pesos do treino. Seu conhecimento destilado fica lá, sem ninguém ler.

O mapa de carregamento liga o corpo da skill aos arquivos de referência e elimina a ambiguidade que deixa o modelo pegar atalhos:

Mapa de carregamento do SKILL.md

Tipo de pergunta	Carregar este arquivo
Qualquer avaliação de oferta	references/00-canon.md (sempre)
Preço ou reversão de risco	references/04-pricing.md
Construção da oferta	references/02-grand-slam-offer.md
Objeções ou taxa de fechamento	references/07-closing-and-sales.md
Veredito final	references/11-decision-checklist.md

Explícito ganha de educado. “Consulte as referências” é uma sugestão. Uma tabela que diz “pergunta de preço carrega pricing.md” é uma instrução. O modelo segue a segunda com muito mais consistência que a primeira.

Escrevendo descriptions que disparam

As descriptions são o principal mecanismo de disparo — não o nome, não o slash command. O Claude lê as descriptions para decidir qual skill corresponde ao pedido do usuário. Uma description que parece resumo de marketing está quebrada na prática. Ela descreve a skill com precisão e não bate com nenhuma intenção real do usuário.

Descriptions que disparam pouco soam como elevator pitch: “Uma skill para revisar a segurança do código.” Descriptions que disparam se parecem com o padrão que deveriam capturar: “Revisa pull requests em busca de vulnerabilidades de injeção, falhas de autenticação, exposição de secrets e controle de acesso quebrado. Invoque para qualquer PR que mexa em auth, queries no banco, variáveis de ambiente ou adição de dependências de terceiros.”

A diferença está na especificidade da intenção, não no tamanho. A segunda description bate com o que um dev digitaria ou diria quando precisa da skill (o vocabulário do problema, não o vocabulário da solução).

A própria orientação da Anthropic é deixar as descriptions “um pouco insistentes”, porque na prática as skills tendem a disparar menos do que deveriam. O custo de um falso positivo (a skill dispara quando não devia) é menor que o custo de disparar pouco de forma consistente, quando a skill nunca dispara. Prefira especificar demais a resumir.

Arquivos de referência acima de 300 linhas precisam de sumário

Todo arquivo de referência com mais de 300 linhas precisa de um sumário no topo. Isso é estrutural, não estético.

Quando o agente carrega um arquivo de referência, ele lê a partir do topo. Um arquivo longo sem sumário faz o modelo varrer a estrutura antes de achar a seção relevante: tokens desperdiçados e precisão pior. Um sumário no topo deixa o agente pular direto para a âncora de que a tarefa precisa, o que importa mais em referências multidomínio que atendem vários tipos de pergunta.

A regra também expõe um problema de design: se um único arquivo de referência tem mais de 300 linhas e não tem capítulos óbvios, provavelmente cobre domínios de decisão demais. Divida. Minha skill de avaliação de ofertas tem 13 arquivos de referência, a maioria com menos de 100 linhas, divididos por decisão: preço, garantias, value equation, fechamento, retenção. O arquivo canon (que carrega em toda invocação) tem sumário. O resto é curto o bastante para ser lido inteiro sem um.

Desenhe o mapa de carregamento no SKILL.md e a estrutura de references/ juntos. Se o corpo diz “para perguntas de preço, carregue references/04-pricing.md”, esse arquivo deve ser focado o suficiente para o agente lê-lo inteiro de uma vez. Brevidade nas referências é uma vantagem: mantém o L3 barato.

Para verificar se sua skill dispara corretamente e usa as referências que você escreveu, veja o guia para testar skills do Claude Code. Para estruturas reais de skills para estudar (incluindo a skill alex-hormozi-offer-design, com 13 referências divididas por decisão), veja exemplos de skills do Claude. Se você ainda está decidindo se vale criar uma skill, comece pelo guia para criar skills do Claude Code.

Qual é o SKILL.md mínimo viável?+

name e description são os únicos campos obrigatórios. Uma skill só com esses dois dispara e executa. Sem allowed-tools ou disallowed-tools, ela herda o conjunto completo de permissões da sessão, o que costuma ser permissivo demais para uma skill especializada.

O mínimo prático para produção: name, description, effort e pelo menos um entre allowed-tools e disallowed-tools, para deixar as permissões explícitas em vez de herdadas.

Quem dispara a skill: description ou when_to_use?+

Os dois contribuem. O modelo lê ambos ao varrer a listagem de skills para casar com o pedido atual. Eles dividem um orçamento combinado de mais ou menos 1.536 caracteres.

Use description para o padrão de intenção principal (o vocabulário do problema que a skill resolve). Use when_to_use para cenários específicos e edge cases que a description não traz à tona.

Os arquivos de referência carregam automaticamente quando a skill ativa?+

Não. Nada em references/ carrega automaticamente.

O corpo do SKILL.md carrega na ativação. Os arquivos de referência só carregam quando as instruções do corpo mandam o agente ler um arquivo específico. Sem um mapa de carregamento explícito no corpo, o agente ignora as referências e responde com os pesos do treino. Seu conhecimento destilado fica inalcançável.

O que context: fork faz?+

Roda a skill num contexto isolado, separado da conversa principal. Isso evita que sessões longas da skill (análise profunda, pesquisa em várias etapas, carregamento extenso de referências) consumam a context window da conversa que invocou a skill.

Use para skills que fazem bastante trabalho antes de devolver uma resposta. Para consultas rápidas e formatadores, o overhead não compensa.

effort: max deveria ser o padrão?+

Não. O effort escala tempo de raciocínio e custo. Defina o que a tarefa realmente pede: low para consultas rápidas e formatadores, high para auditorias de segurança e análises complexas, max só quando você realmente precisa do raciocínio mais profundo.

effort: max numa skill simples de formatação desperdiça processamento. effort: low numa auditoria de segurança vai deixar passar coisas. Ajuste o effort ao peso da decisão, não à vontade de jogar seguro.

Uma skill pode invocar outra skill?+

Sim: pelo campo agent ou incluindo instruções de invocação no corpo. Uma skill roteadora pode delegar para sub-skills especializadas dependendo do tipo de entrada.

A composição acontece na camada de orquestração: uma skill passa a vez para outra, devolve a saída, e a próxima skill segue dali. Duas skills não rodam ao mesmo tempo dentro de um único corpo de SKILL.md.

Qual deve ser o tamanho do corpo do SKILL.md?+

Menos de 500 linhas. Se o corpo passar disso, ele virou uma referência. Mova o excesso para references/ e adicione uma instrução de carregamento apontando para lá.

O corpo é o roteador e o prompt. As referências são o conhecimento. Mantê-los separados mantém a ativação rápida: o corpo inteiro carrega em toda invocação, então cada linha ali custa contexto em toda chamada.

Onde fica o diretório da skill?+

Em .agents/skills/<your-skill-name>/. O arquivo SKILL.md é o ponto de entrada obrigatório nesse caminho. Os subdiretórios (references/, scripts/, assets/) são opcionais e seguem a convenção documentada neste artigo.

O caminho consistente permite que outras ferramentas, pipelines de CI e skills descubram e entendam sua biblioteca de skills sem ler cada arquivo.