Skills Claude: O Que São no Claude Code e Como Criar a Sua

As skills Claude são pastas com um arquivo SKILL.md que ensinam a IA a fazer uma tarefa sempre do mesmo jeito. No Claude Code, você escreve as instruções uma vez e o Claude usa a skill sozinho quando o pedido combina com a descrição, ou quando você chama pelo nome com uma barra. Abaixo, como criar a sua.

Se você ainda não sabe o que é o Claude Code, comece por o que é o Claude Code para quem não é programador. Este post parte do ponto em que você já abriu a ferramenta numa pasta e começou a pedir coisas.

O que é uma skill no Claude Code

Uma skill é um conjunto de instruções guardado num arquivo SKILL.md, dentro de uma pasta com o nome dela, que o Claude Code carrega quando a tarefa pede. A documentação oficial do Claude Code, acessada em outubro de 2026, resume assim: você cria o arquivo com as instruções e o Claude acrescenta aquilo ao que sabe fazer, usando quando for relevante ou quando você chama com /nome-da-skill.

Na prática, é o procedimento que você explicaria para um funcionário novo, escrito num arquivo de texto. Revisar uma proposta comercial, montar o relatório da semana, conferir uma página antes de publicar. Em vez de colar as mesmas regras no chat toda vez, você deixa as regras na pasta.

Quando uma skill faz sentido

A própria documentação dá dois sinais. O primeiro: você se pega colando as mesmas instruções em várias conversas. O segundo: um trecho do seu CLAUDE.md deixou de ser um fato sobre o projeto e virou um procedimento com etapas.

Para não confundir as peças, esta é a divisão que eu uso:

Peça	Para que serve	Quando é lida
CLAUDE.md	Fatos e regras do projeto: o que é, como testar, o que não fazer	No começo de toda sessão
Skill	Um procedimento para uma tarefa específica, com passos e modelos	Só quando a tarefa aparece ou quando você chama
Agente (subagente)	Uma função especializada que trabalha separada da conversa principal	Quando você ou o Claude delega uma parte do trabalho

A diferença que mais pesa no dia a dia está na terceira coluna. Segundo a documentação, o conteúdo de uma skill só é carregado quando ela é usada. Por isso um manual longo dentro de uma skill quase não custa nada até a hora em que é necessário. No CLAUDE.md, tudo entra em toda sessão.

Como o Claude decide usar a skill

O texto de engenharia da Anthropic sobre Agent Skills, publicado em 16 de outubro de 2025, descreve três camadas, que eles chamam de revelação progressiva:

1. Nome e descrição. Ficam sempre visíveis para o Claude. É só o suficiente para ele saber que a skill existe e quando ela se aplica.
2. O corpo do SKILL.md. Entra quando o pedido combina com a descrição.
3. Arquivos extras da pasta. Modelos, exemplos e scripts que o Claude só abre se precisar.

A consequência prática: a descrição é a parte mais importante da skill. Se ela for vaga, o Claude não sabe quando usar. A documentação também avisa que a lista de skills corta descrições longas, então o caso de uso principal vai logo no começo.

Você também pode chamar a skill na mão, digitando a barra e o nome dela no início da mensagem, por exemplo /revisar-proposta. E dá para controlar quem aciona: com disable-model-invocation: true só você chama, e com user-invocable: false só o Claude chama.

Como criar a sua skill em 5 passos

O exemplo abaixo é uma skill para revisar proposta comercial antes de mandar ao cliente. Troque pela tarefa que mais se repete na sua semana.

Passo 1: Escolha uma tarefa que se repete

Uma tarefa só, com começo e fim claros. "Revisar proposta" funciona. "Cuidar do comercial" não funciona, porque não tem passo a passo. Se você não consegue escrever os passos num papel, a skill ainda não está pronta para existir. Mesmo princípio de começar pelo gargalo antes da ferramenta.

Passo 2: Crie a pasta no lugar certo

A documentação lista onde as skills podem morar. As duas que importam para começar:

• Pessoal: ~/.claude/skills/revisar-proposta/SKILL.md. Vale para todos os seus projetos.
• Do projeto: .claude/skills/revisar-proposta/SKILL.md, dentro da pasta do projeto. Vale só ali, e se o projeto estiver num repositório, quem trabalha junto recebe a mesma skill.

Se a tarefa é sua em qualquer projeto, use a pessoal. Se é regra daquele projeto, use a do projeto. Você não precisa criar a pasta na mão: pode pedir ao próprio Claude Code para criar a estrutura e revisar antes de aprovar.

Passo 3: Escreva o cabeçalho com nome e descrição

O SKILL.md começa com um cabeçalho entre duas linhas de três hífens. O campo name vira o comando, e o campo description diz o que a skill faz e quando usar. Segundo a documentação, só a descrição é recomendada, porque é ela que orienta o Claude.

Escreva a descrição como uma frase de gatilho: o que faz e em que situação. "Revisa proposta comercial antes do envio ao cliente. Use quando eu pedir para revisar, conferir ou fechar uma proposta." Isso é melhor do que "skill de propostas".

Passo 4: Escreva as instruções como ordem, não como explicação

O corpo é texto simples em Markdown. A documentação recomenda dizer o que fazer em vez de narrar como ou por quê, porque cada linha carregada custa contexto. Também recomenda manter o SKILL.md abaixo de 500 linhas e mandar material de consulta longo para arquivos separados na mesma pasta.

Aqui o método C.L.A.R.O. de montar um prompt serve de roteiro: Contexto (para quem é a tarefa), Linguagem (tom e formato da saída), Ação (os passos), Referência (um modelo aprovado) e Objetivo (o que conta como pronto).

Passo 5: Teste em sessão nova e ajuste

Abra uma sessão nova e faça um pedido com as palavras da descrição, sem citar a skill. Veja se o Claude usa sozinho. Depois chame com a barra e confira se ele seguiu cada passo. A documentação sugere comparar o resultado com e sem a skill, em sessões novas, para saber se ela de fato melhora a entrega.

Se ele não usou quando devia, o problema quase sempre está na descrição. Se usou e errou, está nas instruções.

Modelo de SKILL.md para copiar

Salve como SKILL.md dentro da pasta revisar-proposta e troque o que estiver entre colchetes:

---
name: revisar-proposta
description: Revisa proposta comercial antes do envio ao cliente. Use quando eu pedir para revisar, conferir ou fechar uma proposta.
disable-model-invocation: false
---

Contexto: a empresa é [descreva em uma frase]. O cliente típico é [quem compra].

Ao revisar a proposta em $ARGUMENTS:

1. Confira se nome do cliente, datas e valores batem em todas as páginas.
2. Marque toda promessa de prazo ou resultado que não esteja no escopo.
3. Aponte termos técnicos que o cliente não vai entender e sugira a troca.
4. Verifique se a proposta diz o que está fora do escopo.
5. Compare o tom com o arquivo referencia.md desta pasta.

Saída: uma lista com o problema, o trecho exato e a correção sugerida.
Não altere o arquivo original. Não invente valor nem prazo.
Pronto quando: os 5 itens foram checados e listados.

O $ARGUMENTS é substituído pelo que você digitar depois do comando. Se você chamar /revisar-proposta proposta-cliente.md, a skill trabalha naquele arquivo. Coloque na mesma pasta um referencia.md com uma proposta que você já aprovou, e a skill passa a ter um padrão para comparar.

Cuidados antes de instalar skills prontas

Existem skills prontas circulando, e muitas economizam tempo. Mas uma skill pode trazer scripts que rodam no seu computador. O texto da Anthropic recomenda instalar skills só de fontes confiáveis e, nas menos confiáveis, ler os arquivos antes, principalmente scripts e qualquer instrução que mande o Claude acessar endereços externos.

Três regras que eu sigo:

• Leia o SKILL.md inteiro antes de usar. Se não entendeu o que um script faz, não rode.
• Skill que publica, envia ou apaga alguma coisa leva disable-model-invocation: true. A documentação usa o exemplo de publicar um sistema: você não quer o Claude decidindo publicar porque o código parece pronto.
• Nunca coloque senha ou chave dentro da skill. Ela é texto e pode ir parar num repositório.

Perguntas frequentes

O que são skills no Claude?

São pastas com um arquivo SKILL.md que contém instruções para uma tarefa específica. O Claude lê o nome e a descrição de cada skill e carrega o resto só quando o pedido combina. Segundo a Anthropic, funcionam no Claude.ai, no Claude Code, no Agent SDK e na plataforma de desenvolvedores.

Preciso saber programar para criar uma skill no Claude Code?

Não. O SKILL.md é texto em Markdown com um cabeçalho de poucas linhas. Você descreve o que quer em passos, e pode pedir ao próprio Claude Code para montar a estrutura. Script é opcional.

Qual a diferença entre skill e CLAUDE.md?

O CLAUDE.md é lido em toda sessão e guarda fatos e regras do projeto. A skill guarda um procedimento e só entra quando a tarefa aparece. Regra que vale sempre vai no CLAUDE.md. Passo a passo de uma tarefa vai numa skill.

Skill e comando com barra são a mesma coisa?

Hoje, quase. A documentação diz que os comandos personalizados foram unificados com as skills: um arquivo em .claude/commands e uma skill em .claude/skills criam o mesmo comando com barra. A skill acrescenta arquivos de apoio, controle de quem aciona e uso automático.

Por que o Claude não usa a minha skill sozinho?

Quase sempre é a descrição. Ela precisa dizer o que a skill faz e em que situação usar, com as palavras que você usa no pedido. Confira também se a skill não está com disable-model-invocation ligado.

Próximo passo

Skill boa nasce de um processo que você já domina no chat. Se você quer sair do chat e construir ferramentas próprias com o Claude Code, com sistemas, agentes e skills prontos para não começar do zero, a trilha Construindo com a IA da Academ.IA cobre esse caminho, do chat ao terminal até colocar um sistema no ar. A primeira aula dá para fazer começando grátis, e as aulas entram conforme são gravadas.