O que são Claude Skills? Guia prático de Agent Skills, SKILL.md e Claude Code

Claude Skills são pacotes reutilizáveis de instruções, scripts e recursos que ensinam Claude a executar tarefas específicas de forma repetível.

Em vez de explicar o mesmo processo toda vez, você transforma esse processo em uma Skill. Claude pode carregar essa Skill quando a tarefa for relevante ou quando você chamar a Skill diretamente.

A forma mais simples de entender:

Claude Skill é um playbook que Claude sabe quando usar.

Ela não é só um prompt salvo. Uma Skill pode ter um arquivo SKILL.md, exemplos, templates, scripts, referências e regras de execução. É por isso que Skills fazem sentido para rotinas como revisar artigo, criar relatório, gerar apresentação, auditar código, seguir brand voice ou validar uma publicação.

Resposta rápida: o que são Claude Skills?

Claude Skills são pastas com instruções e recursos que estendem o que Claude consegue fazer em uma tarefa específica.

Na prática, uma Skill costuma ter:

Parte	Função
Pasta da Skill	Agrupa instruções, recursos e scripts
SKILL.md	Arquivo principal com descrição e passo a passo
description	Ajuda Claude a decidir quando usar a Skill
Referências	Exemplos, templates, padrões e documentos de apoio
Scripts opcionais	Código para tarefas determinísticas, como converter, validar ou extrair dados

Exemplo simples:

“text .claude/ skills/ revisar-artigo-seo/ SKILL.md references/ padrao-editorial.md “

E o SKILL.md poderia começar assim:

---
name: revisar-artigo-seo
description: Use quando o usuário pedir revisão SEO, GEO ou editorial de um artigo antes de publicar.
---

# Revisar artigo SEO

1. Identifique a intenção de busca.
2. Verifique se a introdução responde a pergunta principal.
3. Revise H2, FAQ, links internos, fontes e CTA.
4. Liste problemas antes de sugerir melhorias.
5. Finalize com recomendação: publicar, revisar ou segurar.

1. Identifique a intenção de busca.
2. Verifique se a introdução responde a pergunta principal.
3. Revise H2, FAQ, links internos, fontes e CTA.
4. Liste problemas antes de sugerir melhorias.
5. Finalize com recomendação: publicar, revisar ou segurar.

Esse exemplo já mostra a ideia central: a Skill transforma uma rotina em instrução reutilizável.

Para que servem Claude Skills?

Claude Skills servem para aumentar consistência em tarefas repetidas.

Elas são úteis quando você quer que Claude siga um processo específico, e não apenas responda de forma genérica.

Exemplos:

Antes	Com Claude Skill
Você cola o briefing editorial toda vez	Claude usa a Skill de briefing
Você repete checklist de QA	Claude carrega a rotina salva
Você explica o tom da marca	Claude consulta a Skill de brand voice
Você manda o mesmo modelo de relatório	Claude segue o formato esperado
Você descreve como revisar um PR	Claude aplica a Skill de code review
Você ensina como publicar post	Claude segue o playbook de publicação

O ganho real não é "Claude ficar mais inteligente" no sentido mágico. O ganho é reduzir improviso.

Uma boa Skill ajuda Claude a lembrar:

• o objetivo da tarefa;
• os critérios de qualidade;
• a ordem correta;
• o que evitar;
• o formato final esperado;
• quais arquivos ou scripts usar.

Como Claude Skills funcionam no Claude Code?

No Claude Code, Skills podem ser criadas como arquivos dentro do projeto, normalmente em uma estrutura como .claude/skills/.

O fluxo geral é:

1. Você cria uma pasta para a Skill.
2. Dentro dela, cria um SKILL.md.
3. O SKILL.md tem frontmatter e instruções.
4. Claude descobre os metadados da Skill.
5. Quando a tarefa combina com a descrição, Claude pode carregar a Skill.
6. Você também pode chamar uma Skill diretamente pelo nome.

Segundo a documentação do Claude Code, o diretório da Skill vira o comando que você pode digitar, e a descrição ajuda Claude a decidir quando carregar a Skill automaticamente.

Isso é importante: a descrição não é enfeite. Ela é o gatilho.

Uma descrição vaga faz a Skill falhar antes mesmo de começar.

Progressive disclosure: por que Skills economizam contexto

Um detalhe importante das Claude Skills é o carregamento sob demanda.

Em vez de colocar todo procedimento dentro do contexto principal, Claude primeiro conhece os metadados da Skill, especialmente a descrição. Quando a tarefa combina com aquela descrição, o conteúdo completo do SKILL.md e os arquivos de apoio necessários podem ser carregados.

Esse padrão costuma ser chamado de progressive disclosure: a Skill fica disponível, mas só entra no contexto quando faz sentido.

Na prática, isso ajuda em projetos grandes porque:

• evita encher o CLAUDE.md com todos os checklists;
• reduz ruído em tarefas simples;
• permite ter Skills específicas sem carregar tudo sempre;
• deixa cada rotina mais fácil de testar e melhorar.

Por isso, uma Skill boa precisa de descrição clara. Se a descrição é ruim, Claude pode não saber quando carregar o resto.

O que vai dentro de um SKILL.md?

O SKILL.md tem duas partes principais:

1. YAML frontmatter: fica entre --- e informa nome, descrição e metadados.
2. Markdown de instruções: explica o que Claude deve fazer quando a Skill for usada.

Exemplo:

---
name: relatorio-cliente
description: Use quando o usuário pedir um relatório de marketing para cliente com resumo executivo, métricas, leitura e próximos passos.
---

# Relatório de marketing para cliente

## Objetivo

Transformar métricas em uma leitura clara para decisão.

## Processo

1. Identifique o período analisado.
2. Separe métricas de resultado e diagnóstico.
3. Explique o que melhorou.
4. Explique o que piorou.
5. Liste hipóteses.
6. Recomende próximos passos.

## Saída

Entregue:

- resumo executivo;
- números principais;
- leitura;
- próximos passos;
- riscos.

• resumo executivo;
• números principais;
• leitura;
• próximos passos;
• riscos.

Esse tipo de estrutura é melhor do que um texto solto, porque orienta execução.

Claude Skills são só para programadores?

Não.

Claude Code é muito usado por devs, mas Skills fazem sentido para qualquer rotina que tenha processo.

Em marketing, por exemplo, uma Skill pode ajudar em:

• briefing de conteúdo;
• revisão SEO/GEO;
• relatório para cliente;
• análise GSC;
• copy de Meta Ads;
• auditoria de criativos;
• QA de landing page;
• checklist de publicação WordPress;
• proposta comercial;
• funil de WhatsApp.

Para agência e consultor, isso é interessante porque a qualidade da entrega depende menos de memória improvisada e mais de processo documentado.

Skill é a mesma coisa que prompt?

Não.

Um prompt é uma instrução pontual. Uma Skill é uma instrução empacotada, nomeada e reutilizável.

Recurso	Use quando
Prompt	O pedido é único, curto ou experimental
Skill	O processo se repete e precisa de consistência
CLAUDE.md	O contexto vale para o projeto inteiro
MCP	Claude precisa acessar ferramenta, sistema ou dado externo
Subagent	A tarefa deve ser delegada a uma função especializada
Hook	Uma ação deve rodar automaticamente em um evento

Regra simples:

Prompt pede. Skill ensina. MCP conecta. CLAUDE.md contextualiza.

Claude Skills vs MCP

Skills e MCP se complementam.

Uma Skill diz como trabalhar. MCP permite Claude acessar com o que trabalhar.

Exemplo:

• Skill: checklist de auditoria de landing page.
• MCP: navegador, arquivos, GitHub, banco, n8n ou documentação externa.

Com a Skill, Claude sabe o processo. Com MCP, Claude tem acesso controlado às ferramentas.

Se você ainda está entendendo MCP, leia também: o que é MCP e melhores servidores MCP.

Claude Skills vs CLAUDE.md

Essa é uma dúvida comum.

CLAUDE.md é melhor para contexto geral do projeto:

• comandos;
• estrutura de pastas;
• convenções;
• padrões globais;
• cuidados de segurança;
• como rodar testes.

Skill é melhor para uma rotina específica:

• revisar artigo;
• publicar post;
• fazer QA de tracking;
• gerar relatório;
• revisar PR;
• criar briefing.

Se uma seção do CLAUDE.md virou um checklist grande, com vários passos e exceções, ela provavelmente deveria virar uma Skill.

Quando criar uma Claude Skill?

Crie uma Skill quando a tarefa tem uma destas características:

• você repete a instrução com frequência;
• existe checklist;
• existe formato de saída;
• existem critérios de qualidade;
• há arquivos de referência;
• a tarefa tem risco se Claude esquecer uma etapa;
• a equipe precisa seguir o mesmo processo;
• a rotina ficou grande demais para o CLAUDE.md.

Exemplos bons:

Skill	Por que faz sentido
qa-publicacao-wordpress	Publicação tem checklist e risco técnico
briefing-conteudo	Conteúdo precisa de padrão e estrutura
relatorio-cliente	Relatório precisa de formato recorrente
copy-meta-ads	Copy precisa de ângulo, promessa e variações
analise-gsc	Dados precisam virar decisão
review-diff	Mudanças de código precisam de revisão ordenada

Quando não criar uma Skill?

Nem tudo precisa virar Skill.

Evite criar Skill quando:

• você ainda não sabe o processo certo;
• a tarefa aconteceu uma vez só;
• o pedido é simples;
• a informação muda diariamente;
• uma ferramenta resolveria melhor;
• a Skill ficaria grande e genérica demais.

Um erro comum é criar uma Skill chamada "marketing" que tenta fazer tudo. Isso quase sempre fica pior do que criar Skills menores, como briefing-conteudo, copy-meta-ads e relatorio-cliente.

Como escrever uma Skill boa?

Uma boa Skill é curta, focada e testável.

Checklist:

• nome curto;
• descrição específica;
• objetivo claro;
• quando usar;
• quando não usar;
• processo passo a passo;
• critérios de qualidade;
• formato de saída;
• exemplos curtos;
• referências separadas quando necessário.

O ponto mais importante é a descrição.

Compare:

Descrição ruim	Descrição melhor
Ajuda com SEO	Use quando o usuário pedir revisão SEO, GEO ou editorial de artigo antes de publicar
Relatórios	Use quando o usuário pedir relatório de marketing para cliente com métricas e próximos passos
Marketing	Use quando o usuário pedir briefing de conteúdo para blog com intenção de busca, H2, FAQ e fontes

Claude precisa entender quando usar a Skill.

Exemplo prático: Skill para marketing

Imagine uma Skill para revisar conteúdo antes da publicação.

---
name: qa-publicacao-blog
description: Use quando o usuário pedir validação final de um artigo de blog antes ou depois de publicar.
---

# QA de publicação de blog

## Objetivo

Validar se o artigo está pronto para publicação e se não há riscos de SEO, conversão ou estrutura.

## Checklist

1. Confirmar intenção de busca.
2. Verificar resposta direta no início.
3. Checar H1, H2 e FAQ.
4. Confirmar CTA contextual.
5. Validar links internos.
6. Conferir fontes.
7. Verificar schema quando aplicável.
8. Conferir URL pública, canonical e indexabilidade.

## Saída

Liste:

- bloqueios críticos;
- melhorias recomendadas;
- decisão final: publicar, revisar ou segurar.

• bloqueios críticos;
• melhorias recomendadas;
• decisão final: publicar, revisar ou segurar.

Essa Skill é simples, mas já resolve uma dor real: não esquecer etapas na hora de publicar.

Cuidados de segurança com Claude Skills

Skills podem incluir scripts e instruções que orientam Claude a usar ferramentas.

Por isso, não instale qualquer Skill de qualquer lugar sem revisar.

Boas práticas:

• use Skills próprias ou de fonte confiável;
• leia o SKILL.md antes de instalar;
• revise scripts incluídos na pasta;
• evite Skills com instruções vagas demais;
• não coloque segredos, tokens ou senhas em Skills;
• teste em tarefas pequenas antes de usar em fluxo crítico.

Essa cautela é ainda mais importante quando a Skill pode acionar ferramentas, código, arquivos ou integrações.

Vale a pena usar Claude Skills?

Vale quando você já tem processos repetidos.

Para uso casual, talvez prompts normais bastem. Para operação de marketing, agência, conteúdo, programação ou automação, Skills ajudam bastante porque viram uma camada de processo.

Minha recomendação:

1. Comece com uma Skill pequena.
2. Use em tarefa real.
3. Ajuste a descrição.
4. Melhore o checklist.
5. Só depois crie a próxima.

Skills boas nascem de trabalho real, não de uma lista gigante criada no vazio.

Perguntas frequentes

O que são Claude Skills?

Claude Skills são pacotes de instruções, recursos e scripts opcionais que ensinam Claude a executar tarefas específicas de forma repetível.

Claude Skills funcionam no Claude Code?

Sim. Claude Code suporta Skills, que podem ser usadas automaticamente quando relevantes ou chamadas diretamente pelo nome.

O que é SKILL.md?

SKILL.md é o arquivo principal de uma Skill. Ele contém metadados, como descrição, e instruções em Markdown para Claude seguir.

Claude Skills substituem prompts?

Não. Prompts são bons para pedidos pontuais. Skills são melhores para processos repetíveis e padronizados.

Claude Skills substituem MCP?

Não. Skill ensina Claude como agir. MCP conecta Claude a ferramentas, dados e sistemas externos. Eles podem ser usados juntos.

Preciso saber programar para criar uma Skill?

Para uma Skill simples, não. Você pode criar uma Skill só com Markdown. Código e scripts entram quando a tarefa precisa de automação mais precisa.

Onde ficam as Skills no Claude Code?

Em muitos casos, Skills de projeto ficam em .claude/skills/, cada uma em sua própria pasta com um SKILL.md.

Qual é o erro mais comum ao criar Skills?

Criar uma descrição vaga. A descrição ajuda Claude a decidir quando usar a Skill, então ela precisa dizer claramente a tarefa e o contexto.

Fontes consultadas

• Anthropic Support – O que são habilidades?
• Claude Code Docs – Extend Claude with skills
• Claude Code Docs – Best practices for Claude Code
• Claude Code Docs – Agent Skills in the SDK
• Claude Platform Docs – Agent Skills overview
• Claude Platform Docs – Skill authoring best practices
• Anthropic Skills – repositório público