Um arquivo SKILL.md é o coração de toda Claude Skill - um arquivo Markdown que começa com um cabeçalho YAML curto (um name e uma description) e é seguido pelas instruções que Claude deve seguir. A descrição informa a Claude quando usar a Skill; o corpo informa como.
Se você já viu o term e se perguntou o que realmente há dentro dele, esta é a anatomia de um SKILL.md, por que cada parte é importante e como escrever um que funcione.
O que é SKILL.md
Um Claude Skill é uma pasta, e SKILL.md é o arquivo obrigatório na raiz. É Markdown simples, então pode ser aberto em qualquer editor de texto. Claude o lê para aprender uma capacidade - as etapas, regras e práticas recomendadas para um tipo de tarefa. Extras opcionais (modelos, scripts, arquivos de referência) podem ficar na mesma pasta, mas o SKILL.md é o único arquivo que toda Skill deve ter.
Quer ver um SKILL.md bem delimitado em vez de criar um do zero? O frontmatter e as instruções do Yuri já estão escritos e testados para detectar bugs, falhas de segurança e problemas de desempenho em uma revisão.
Ver o Skill de IA de revisão de código do Yuri →As duas partes de um SKILL.md
1. O frontmatter (metadados)
No topo fica um pequeno bloco YAML entre marcadores ---. Ele contém os metadados essenciais - no mínimo um name e uma description:
---
name: weekly-report
description: Formata notas brutas em nosso relatório semanal padrão. Use quando o usuário pedir uma atualização semanal, um relatório de status ou para "organizar a semana".
---Este bloco é especial: quando uma sessão começa, Claude pré-carrega apenas o nome e a descrição de cada Skill instalada - não o arquivo inteiro. Isso mantém a janela de contexto leve e explica por que a descrição é tão importante.
2. O corpo (instruções)
Abaixo do frontmatter, em Markdown comum, você escreve o que Claude deve realmente fazer - idealmente como etapas numeradas e claras, com quaisquer regras ou exemplos:
## Etapas
1. Agrupe as anotações em Vitórias, Em andamento e Bloqueios.
2. Mantenha cada tópico em uma frase, no passado.
3. Termine com um resumo de uma linha sobre a "Próxima semana".
4. Nunca invente métricas que não estejam nas anotações.Por que a descrição é a linha mais importante
O acionamento depende inteiramente da descrição. Conforme você trabalha, Claude compara sua solicitação com a descrição de cada skill e carrega o arquivo completo somente quando há correspondência. Uma descrição vaga ("ajuda com relatórios") raramente é acionada. Uma específica ("use quando o usuário pedir uma atualização semanal ou um relatório de status") é acionada de forma confiável. Se você guardar uma regra, que seja esta: escreva a descrição para indicar quando usar o skill, não apenas o que ele é.
Como Claude usa o arquivo
- Na inicialização: Claude lê o nome e a descrição de cada skill.
-
Durante a tarefa: se a sua solicitação corresponder a uma descrição, Claude carrega o
SKILL.mdcompleto desse skill (e todos os recursos anexados). - Depois: Claude segue as instruções do corpo para concluir o trabalho.
Essa abordagem de "carregar somente quando necessário" é chamada de divulgação progressiva e permite manter muitos skills instalados sem sobrecarregar o contexto do modelo.
Escrevendo um bom SKILL.md
- Capriche na descrição. Diga claramente quando o skill deve ser acionado.
- Mantenha a primeira versão pequena. Cinco a dez linhas de etapas claras são melhores do que um documento enorme.
- Seja concreto. Use etapas numeradas, regras explícitas e um exemplo curto.
- Teste em tarefas reais. Expanda somente onde o Claude falhar.
Você precisa escrever um por conta própria?
Não. Escrever o seu próprio skill é ótimo para fluxos de trabalho exclusivos para você, mas, se você quer apenas o resultado, os skills prontos já vêm com o SKILL.md elaborado e testado. Navegue pela biblioteca da KissMySkills, com mais de 1.000 skills, pacotes de prompts e agentes, ou pela coleção de skills do Claude Code. Quer ver um em ação primeiro? Experimente um gerador gratuito ou adquira um skill gratuito.
Nem todo SKILL.md é para programadores - o frontmatter e as instruções de Ryan são escritos para materiais de reunião do conselho, memorandos gerais e briefings executivos, sem necessidade de edição.
Ver o Skill de AI de Ryan - Chefe de Gabinete →Perguntas frequentes
O SKILL.md é apenas Markdown?
Sim - é um arquivo Markdown padrão com um bloco de frontmatter YAML no topo. Ele é aberto em qualquer editor de texto, sem necessidade de software especial.
O que é necessário em um SKILL.md?
No mínimo, um bloco de frontmatter com um nome e uma descrição. O corpo com as instruções é o que torna o Skill útil, mas os metadados são o que o tornam detectável e acionável.
Onde fica o arquivo SKILL.md?
Na raiz da pasta do Skill. No Claude Code, os Skills ficam em ~/.claude/skills/<name>/ para uso pessoal ou em .claude/skills/<name>/ dentro de um projeto, em SKILL.md na raiz da pasta.
Posso usar o conteúdo de um SKILL.md no ChatGPT ou Gemini?
Sim. As instruções são portáteis - cole o corpo nas instruções personalizadas do ChatGPT ou Gemini para obter o mesmo comportamento. O acionamento automático via frontmatter é um recurso do Claude.
Em resumo:
Se preferir não escrever o frontmatter YAML por conta própria, Yuri - Revisor de Código é uma ótima escolha para desenvolvedores, e Ryan - Chefe de Gabinete abrange redação executiva e empresarial. Todos funcionam no Claude, ChatGPT e em qualquer chat com AI, sem programação e com garantia de reembolso em 30 dias.
Comece com um exemplo funcional
A maneira mais rápida de entender o SKILL.md é ler um bom exemplo. Baixe um Skill gratuito, abra o arquivo e veja a estrutura de frontmatter mais etapas em ação - depois leia como instalá-lo em três minutos.