O que é um arquivo SKILL.md? (Anatomia de uma Skill Claude)

Um arquivo SKILL.md é o coração de toda Skill Claude — um arquivo Markdown que começa com um cabeçalho YAML curto (um nome e uma descrição) e é seguido pelas instruções que Claude deve seguir. A descrição é o que diz a Claude quando usar a skill; o corpo diz como.

Se você já viu o termo e se perguntou o que realmente tem dentro de um, aqui está a anatomia de um SKILL.md, por que cada parte importa e como escrever um que funcione.

O que é SKILL.md

Uma Skill Claude é uma pasta, e o SKILL.md é o arquivo obrigatório em sua raiz. É Markdown simples, então abre em qualquer editor de texto. Claude o lê para aprender uma capacidade — os passos, regras e melhores práticas para um tipo de tarefa. Extras opcionais (modelos, scripts, arquivos de referência) podem ficar junto na mesma pasta, mas o SKILL.md é o único arquivo que toda skill deve ter.

As duas partes de um SKILL.md

1. O frontmatter (metadados)

---. Ele carrega os metadados essenciais — no mínimo um nome e uma descrição:

---
name: weekly-report
description: Formata notas brutas no nosso relatório semanal padrão. Use quando o usuário pedir uma atualização semanal, relatório de status ou para "resumir a semana."
---

Esse 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 é por isso que a descrição faz tanto trabalho pesado.

2. O corpo (instruções)

Abaixo do frontmatter, em Markdown normal, você escreve o que Claude deve realmente fazer — idealmente como passos claros e numerados com quaisquer regras ou exemplos:

## Passos
1. Agrupe as notas em Ganhos, Em Progresso e Bloqueios.
2. Mantenha cada item em uma frase, no passado.
3. Termine com um resumo de uma linha "Próxima semana".
4. Nunca invente métricas que não estejam nas notas.

Por que a descrição é a linha mais importante

O disparo depende inteiramente da descrição. Conforme você trabalha, Claude compara seu pedido 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 dispara. Uma específica ("use quando o usuário pedir uma atualização semanal ou relatório de status") dispara de forma confiável. Se lembrar de uma regra, que seja esta: escreva a descrição para quando usar a skill, não apenas o que ela é.

Como Claude usa o arquivo

• Na inicialização: Claude lê o nome + descrição de cada skill.
• Durante a tarefa: se seu pedido corresponder a uma descrição, Claude carrega o SKILL.md completo dessa skill (e quaisquer recursos anexados).
• Então: Claude segue as instruções do corpo para completar o trabalho.

Essa abordagem de "carregar só quando necessário" é chamada de divulgação progressiva, e é o que permite manter muitas skills instaladas sem sobrecarregar o contexto do modelo.

Como escrever um bom SKILL.md

1. Capriche na descrição. Declare claramente quando a skill deve ser acionada.
2. Mantenha a primeira versão pequena. Cinco a dez linhas de passos claros são melhores que um documento extenso.
3. Seja concreto. Passos numerados, regras explícitas, um exemplo curto.
4. Teste em tarefas reais. Expanda só quando Claude errar.

Você precisa escrever um por conta própria?

Não. Escrever o seu é ótimo para fluxos de trabalho únicos para você, mas se quiser só o resultado, skills prontas já vêm com seu SKILL.md criado e testado. Navegue pela biblioteca KissMySkills com mais de 300 skills, pacotes de prompt e agentes, ou pela coleção Claude Code skills. Quer ver um em ação primeiro? Experimente um gerador gratuito ou pegue uma skill gratuita.

Perguntas frequentes

SKILL.md é só Markdown?

Sim — é um arquivo Markdown padrão com um bloco YAML frontmatter no topo. Abre em qualquer editor de texto, sem necessidade de software especial.

O que é necessário em um SKILL.md?

No mínimo, um bloco frontmatter com nome e descrição. O corpo com instruções é o que torna a skill útil, mas os metadados são o que a tornam descobrível e acionável.

Onde fica o arquivo SKILL.md?

Na raiz da pasta da skill. No Claude Code, as skills ficam em ~/.claude/skills/<nome>/ para uso pessoal ou .claude/skills/<nome>/ dentro de um projeto, com o 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 o mesmo comportamento. O disparo automático via frontmatter é um recurso do Claude.

Comece com um exemplo funcional

A maneira mais rápida de entender o SKILL.md é ler um bom. Pegue uma skill gratuita, abra o arquivo e veja a estrutura frontmatter-mais-passos em ação — depois leia como instalá-la em três minutos.