Como criar uma Skill no Claude Code: guia prático com SKILL.md, teste e exemplo

Para criar uma Skill no Claude Code, crie uma pasta dentro de .claude/skills/ e coloque nela um arquivo SKILL.md com nome, descrição e instruções em Markdown.

Mas a parte que separa uma Skill boa de um prompt salvo é o teste: Claude precisa saber quando usar a Skill, quando não usar e qual saída entregar.

Resposta rápida

O caminho básico é:

.claude/
  skills/
    revisar-artigo-seo/
      SKILL.md

E o arquivo principal pode ser:

Depois, você testa com pedidos reais. Se Claude não acionar a Skill no momento certo, ajuste a descrição.

O que muda na prática depois que a Skill existe?

Uma Skill boa deixa de depender de você colar o mesmo checklist toda vez.

No Claude Code, a descrição da Skill funciona como sinal de acionamento: Claude pode usar a Skill quando a tarefa combina com o que foi descrito, e você também pode chamar a Skill diretamente pelo nome.

O ganho não é só organização. É consistência:

• o mesmo processo aparece em tarefas parecidas;
• o checklist não fica perdido em conversas antigas;
• exemplos e referências podem ficar junto da Skill;
• a rotina pode evoluir sem reescrever prompts do zero.

Se a Skill não muda o resultado prático, ela provavelmente ainda está genérica demais.

Antes de criar: Skill é a solução certa?

Crie uma Skill quando você tem uma rotina repetível.

Exemplos bons:

• revisar artigo antes de publicar;
• criar briefing de conteúdo;
• auditar landing page;
• gerar relatório para cliente;
• revisar campanha de Meta Ads;
• validar tracking;
• revisar PR;
• gerar documentação.

Não crie Skill só porque a tecnologia é nova.

Se a tarefa é rara, pequena ou ainda não tem processo claro, comece com prompt normal. Depois que o processo amadurecer, transforme em Skill.

Passo 1: escolha um nome curto

O nome deve ser fácil de lembrar e chamar.

Use letras minúsculas, hífen e foco na ação.

Bons nomes:

• briefing-conteudo;
• revisar-artigo-seo;
• qa-publicacao;
• relatorio-cliente;
• copy-meta-ads;
• auditar-tracking.

Passo 2: crie a pasta

Dentro do projeto:

“text .claude/skills/nome-da-skill/SKILL.md “

Exemplo:

“text .claude/skills/qa-publicacao/SKILL.md “

Para começar, não precisa de mais nada. Uma Skill mínima pode ter só SKILL.md.

Depois, se a rotina crescer, você adiciona referências, exemplos ou scripts.

Passo 3: escreva o frontmatter

O frontmatter fica no topo do SKILL.md, entre ---.

Exemplo:

<pre><code>— name: qa-publicacao description: Use quando o usuário pedir validação final de artigo, página ou landing page antes ou depois de publicar. —</code></pre>

A descrição é o ponto mais importante. Ela funciona como gatilho para Claude decidir quando carregar a Skill.

Passo 4: escreva uma descrição específica

Descrição vaga é o erro mais comum.

Uma descrição boa diz:

• qual tarefa;
• em qual contexto;
• quando usar;
• às vezes, quando não usar.

Exemplo ainda melhor:

<pre><code>description: Use quando o usuário pedir revisão SEO, GEO ou editorial de artigo antes de publicar. Não use para criar artigo do zero.</code></pre>

Esse "não use" ajuda a reduzir acionamento errado.

Passo 5: escreva instruções operacionais

Uma Skill não precisa parecer artigo. Ela precisa orientar Claude.

Inclua:

• objetivo;
• processo;
• checklist;
• critérios de qualidade;
• formato de saída;
• limites;
• exemplos curtos.

Modelo:

<pre><code># Nome da Skill

Objetivo

Explique o que esta Skill resolve.

Quando usar

Liste situações em que a Skill deve ser usada.

Quando não usar

Liste limites para evitar acionamento errado.

Processo

1. Primeiro passo.
2. Segundo passo.
3. Terceiro passo.

Saída esperada

Entregue no formato:

• riscos;
• melhorias;
• decisão final.</code></pre>

Quanto mais objetiva a Skill, melhor.

Passo 6: adicione referências só quando precisar

Se o SKILL.md ficar longo demais, separe materiais de apoio.

Exemplo:

“text .claude/skills/briefing-conteudo/ SKILL.md references/ padrao-editorial.md exemplos-de-titulos.md checklist-fontes.md “

No SKILL.md, oriente Claude quando abrir cada arquivo:

<pre><code>Antes de criar o briefing, leia references/padrao-editorial.md. Use references/exemplos-de-titulos.md apenas se o usuário pedir ideias de title.</code></pre>

Isso economiza contexto e deixa a Skill mais organizada.

Passo 7: use scripts quando a tarefa precisa de precisão

Skills podem incluir scripts quando a tarefa precisa de algo mais determinístico.

Exemplos:

• contar palavras;
• validar JSON;
• converter arquivo;
• checar links;
• gerar tabela;
• extrair dados;
• renderizar PDF.

Estrutura:

“text .claude/skills/qa-publicacao/ SKILL.md scripts/ checar-links.py “

Mas não comece por script. Primeiro valide o processo.

Passo 8: teste a Skill com pedidos reais

Teste é o que quase todo mundo pula.

Crie uma lista de pedidos:

Se a Skill aciona demais, deixe a descrição mais restrita.

Se aciona de menos, deixe a descrição mais clara.

Exemplo completo: Skill de QA de publicação

Esse é um bom primeiro exemplo porque tem escopo claro e resultado prático.

Como usar uma Skill depois de criada?

No Claude Code, Claude pode usar a Skill quando a tarefa combina com a descrição.

Você também pode chamar diretamente pelo nome da Skill, usando o comando correspondente ao diretório da Skill.

Exemplo:

/qa-publicacao

O nome exato depende de como você nomeou a pasta.

Como compartilhar uma Skill?

Para Claude Code, a forma mais simples é versionar a pasta da Skill junto do projeto ou copiar a pasta para outro ambiente.

Para Claude.ai, a documentação da Anthropic também descreve fluxo de upload de Skill empacotada, normalmente como ZIP, na área de Skills. Esse uso é diferente do fluxo local do Claude Code, mas a ideia de pasta com SKILL.md continua parecida.

Se você trabalha em equipe, documente:

• nome da Skill;
• objetivo;
• onde ela fica;
• quem mantém;
• exemplos de uso;
• quando revisar.

Erros comuns ao criar Skills

Criar uma Skill genérica demais

marketing é amplo demais. briefing-conteudo é melhor.

Colocar tudo dentro do SKILL.md

Se o arquivo ficou gigante, use references/.

Escrever descrição vaga

Claude precisa saber quando usar a Skill. A descrição é o gatilho.

Não dizer quando não usar

Adicionar limite na descrição ou no corpo reduz acionamento errado.

Guardar dado perecível

Não coloque preço, token, meta mensal ou credencial dentro da Skill.

Não testar

Skill sem teste é só um prompt com pasta.

Checklist final

Antes de considerar pronta, confira:

• [ ] Nome curto e claro.
• [ ] Descrição específica.
• [ ] Escopo definido.
• [ ] Processo em passos.
• [ ] Formato de saída.
• [ ] Limites do que não fazer.
• [ ] Exemplos úteis.
• [ ] Sem credenciais.
• [ ] Testada com pedidos reais.

Perguntas frequentes

Como criar uma Skill no Claude Code?

Crie uma pasta dentro de .claude/skills/, adicione um arquivo SKILL.md e escreva frontmatter com nome e descrição, seguido das instruções da Skill.

Onde ficam as Skills no Claude Code?

Em projetos, uma estrutura comum é .claude/skills/nome-da-skill/SKILL.md, com uma pasta para cada Skill.

O que colocar no SKILL.md?

Coloque nome, descrição, objetivo, processo, critérios de qualidade, formato de saída e exemplos. Adicione referências e scripts só quando necessário.

A descrição da Skill importa?

Sim. A descrição ajuda Claude a decidir quando usar a Skill automaticamente.

Posso chamar uma Skill manualmente?

Sim. No Claude Code, você pode chamar uma Skill diretamente pelo nome associado à pasta.

Uma Skill pode ter scripts?

Sim. Skills podem incluir scripts, referências e arquivos de apoio quando a tarefa exige precisão ou automação.

Skill é melhor que prompt?

Skill é melhor para processos repetíveis. Prompt é melhor para pedidos pontuais ou experimentais.

Fontes consultadas

• Claude Code Docs – Extend Claude with skills
• Claude Platform Docs – Agent Skills overview
• Claude Platform Docs – Skill authoring best practices
• Claude Code Docs – Agent Skills in the SDK
• Anthropic Skills – skill-creator
• Claude Support – Use skills in Claude