Um arquivo SKILL.md é o coração de toda Skill do Claude - um arquivo Markdown que começa com um cabeçalho YAML curto (um name e uma description) e é seguido pelas instruções que o Claude deve seguir. A descrição informa ao Claude quando usar a Skill; o corpo informa como.
Nesta página
Se você já viu o term e ficou se perguntando o que há de fato dentro dele, aqui está a anatomia de um SKILL.md, por que cada parte é importante e como escrever um que funcione.
O que é SKILL.md
Uma Skill do Claude é uma pasta, e SKILL.md é o arquivo obrigatório em sua raiz. É Markdown simples, então pode ser aberto em qualquer editor de texto. O 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 precisa 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 durante uma revisão.
Ver Yuri - Skill de AI para revisão de código →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 "registrar a semana".
---Este bloco é especial: quando uma sessão começa, o 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 normal, escreva o que o Claude deve fazer de fato - idealmente como etapas claras e numeradas, com quaisquer regras ou exemplos:
## Etapas
1. Agrupe as notas em Vitórias, Em andamento e Bloqueios.
2. Mantenha cada marcador 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
A ativação depende inteiramente da descrição. Enquanto você trabalha, Claude compara sua solicitação com a descrição de cada skill e carrega o arquivo completo apenas quando há correspondência. Uma descrição vaga ("ajuda com relatórios") raramente é ativada. Uma descrição específica ("use quando o usuário pedir uma atualização semanal ou um relatório de status") é ativada de forma confiável. Se você se lembrar de uma regra, que seja esta: escreva a descrição indicando quando usar a skill, não apenas o que ela é.
Como Claude usa o arquivo
- Na inicialização: Claude lê o nome + a descrição de cada skill.
-
Durante a tarefa: se a sua solicitação corresponder a uma descrição, Claude carrega o
SKILL.mdcompleto dessa skill (e todos os recursos anexados). - Depois: Claude segue as instruções do corpo para concluir o trabalho.
Essa abordagem de "carregar apenas quando necessário" é chamada de divulgação progressiva e permite manter muitas skills instaladas sem sobrecarregar o contexto do modelo.
Escrevendo um bom SKILL.md
- Capriche na descrição. Diga claramente quando a skill deve ser ativada.
- Mantenha a primeira versão pequena. Cinco a dez linhas de etapas claras são melhores do que um documento enorme.
- Seja específico. Use etapas numeradas, regras explícitas e um exemplo curto.
- Teste em tarefas reais. Expanda apenas onde o Claude falhar.
Você precisa criar uma por conta própria?
Não. Criar o seu próprio é ótimo para fluxos de trabalho exclusivos para você, mas, se você só quer o resultado, as skills prontas já vêm com o SKILL.md elaborado e testado. Explore a biblioteca KissMySkills com mais de 1.000 skills, pacotes de prompts e agentes, ou a coleção de skills do Claude Code. Quer ver uma em ação primeiro? Experimente um gerador gratuito ou pegue uma skill gratuita.
Nem todo SKILL.md é para programadores - o frontmatter e as instruções de Ryan foram escritos para materiais de reunião do conselho, memorandos para toda a empresa e briefings executivos, sem necessidade de edição.
Ver o Skill de AI Ryan - Chief of Staff →Perguntas frequentes
O SKILL.md é apenas Markdown?
Sim - é um arquivo Markdown padrão com um bloco de frontmatter YAML no início. Ele pode ser aberto em qualquer editor de texto; não é necessário nenhum 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 torna 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 .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. A ativação automática por meio do frontmatter é um recurso do Claude.
Em resumo:
Se preferir não escrever o frontmatter YAML por conta própria, Yuri - Code Reviewer é uma ótima escolha para desenvolvedores, e Ryan - Chief of Staff é voltado para textos executivos e empresariais. 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.