O que são skills no Claude Code e como criar uma

O que são skills no Claude Code?

Skills no Claude Code são pacotes reutilizáveis de instruções que ensinam a ferramenta a executar uma tarefa específica do seu jeito. Cada skill fica numa pasta com um arquivo SKILL.md, que diz quando usá-la e qual procedimento seguir, e pode incluir scripts, modelos e referências de apoio.

Na prática, uma skill transforma um procedimento que você repete em algo que o Claude Code consulta sozinho. Em vez de colar as mesmas orientações a cada conversa, como revisar uma integração, preparar uma proposta ou conferir um agente de WhatsApp, você escreve o procedimento uma vez e ele passa a fazer parte do repertório da ferramenta.

O Claude Code lê a descrição de cada skill disponível e carrega o conteúdo completo só quando a tarefa pede. Você também pode chamar uma skill diretamente pelo nome, com uma barra, como /revisar-atendimento. Isso mantém o contexto enxuto e permite ter muitas skills instaladas sem sobrecarregar cada conversa. Quanto melhor a descrição, mais certeira é essa escolha.

• Uma skill é uma pasta com um arquivo SKILL.md escrito em Markdown.
• A descrição diz quando usar; o corpo explica o procedimento passo a passo.
• Pode reunir scripts, modelos de documento e arquivos de referência.
• É carregada quando relevante ou chamada diretamente com /nome-da-skill.

Como uma skill funciona por dentro

O SKILL.md começa com um cabeçalho curto em formato YAML, com pelo menos o nome e a descrição da skill. A descrição é a parte mais importante, porque é ela que o Claude Code usa para decidir se a skill se aplica ao pedido. Uma descrição vaga faz a skill nunca ser usada; uma descrição clara, com as situações e as palavras que o usuário costuma usar, faz ela aparecer na hora certa.

Abaixo do cabeçalho vem o corpo, com o procedimento: o que consultar, em que ordem agir, o que verificar e o que entregar no final. Arquivos auxiliares, como scripts e referências longas, podem ficar na mesma pasta e ser citados no corpo, para que o Claude Code os leia apenas quando precisar deles.

• Cabeçalho YAML com nome e descrição da skill.
• Descrição clara, com as situações em que a skill deve ser usada.
• Corpo com o passo a passo, os critérios de verificação e o formato da entrega.
• Arquivos auxiliares na mesma pasta, lidos sob demanda.

Onde ficam as skills: pessoais e de projeto

Existem dois lugares principais para guardar skills. As skills pessoais ficam na pasta de configuração do Claude Code no seu usuário e valem para qualquer projeto em que você trabalhe. As skills de projeto ficam dentro do repositório, na pasta .claude/skills, e acompanham o código, o que permite que toda a equipe use o mesmo procedimento.

A escolha depende de quem precisa da skill. Um procedimento do seu jeito de trabalhar, como o formato dos seus relatórios, faz sentido como skill pessoal. Um procedimento ligado a um sistema específico, como a revisão do agente de WhatsApp de um cliente, faz mais sentido dentro do projeto desse cliente, versionado junto com o código.

• Skills pessoais: valem para todos os seus projetos.
• Skills de projeto: ficam em .claude/skills, dentro do repositório.
• Skills de projeto versionadas permitem que a equipe siga o mesmo procedimento.
• Plugins podem distribuir conjuntos de skills prontas para instalar.

Como criar uma skill passo a passo

O melhor ponto de partida é uma tarefa que você já repete e cujo resultado você sabe conferir. Vamos usar como exemplo uma skill chamada revisar-atendimento, que verifica se um agente de WhatsApp consulta o catálogo antes de informar preço e se passa a conversa para uma pessoa quando não sabe a resposta.

Você pode pedir ao próprio Claude Code para criar a estrutura da skill a partir da sua descrição. O trabalho que continua sendo seu é definir o critério de sucesso: o que conta como revisão bem feita e quais casos de teste provam isso. Sem critério, a skill vira um texto bonito que ninguém consegue avaliar.

• 1. Crie a pasta .claude/skills/revisar-atendimento no projeto.
• 2. Escreva o SKILL.md com nome, uma descrição clara e o procedimento em passos.
• 3. Liste o que a skill deve consultar, como o catálogo e as regras de passagem para humano.
• 4. Defina o que a entrega final precisa conter, como as divergências encontradas e as evidências.
• 5. Teste com dados fictícios, incluindo um caso de preço errado, e ajuste a descrição se a skill não for acionada.

Skill, prompt, CLAUDE.md e MCP: qual a diferença

Skills convivem com outros recursos do Claude Code, e é comum confundir os quatro. A forma mais simples de separar é pensar no que cada um guarda: o prompt guarda um pedido, o CLAUDE.md guarda regras permanentes do projeto, a skill guarda um procedimento reutilizável e o MCP dá acesso a uma ferramenta externa.

Eles se complementam. Uma skill de relatório de anúncios pode usar uma conexão MCP para buscar os dados, seguir as regras de estilo do CLAUDE.md e ser disparada por um prompt curto. Nenhum deles substitui o outro, e entender o papel de cada um evita colocar tudo no mesmo arquivo.

• Prompt — guarda um pedido pontual; vale só para aquela conversa.
• CLAUDE.md — guarda regras do projeto; é lido no início de cada sessão.
• Skill — guarda um procedimento reutilizável; é carregada quando a tarefa pede.
• MCP — dá acesso a ferramentas e dados externos; a skill orienta quando e como usar esse acesso.

Exemplos de skills úteis no dia a dia

As skills que mais rendem são as que codificam um procedimento com etapas de verificação. Na ZX LAB, Rafael Castro organiza em skills tarefas como publicação de páginas, revisão de código, análise de campanhas e atendimento, cada uma com o que precisa ser consultado e conferido antes de o trabalho ser dado como concluído.

Para quem presta serviço com IA, skills também viram parte da entrega: um procedimento de proposta comercial, um checklist de implantação de agente ou um roteiro de manutenção mensal. O curso Agência IA Automatizada com Claude Code, da ZX LAB, inclui um Toolkit com 12 skills justamente para acelerar esse tipo de rotina.

• Proposta comercial: coleta escopo, prazo e entregáveis antes de montar o documento.
• Revisão de atendimento: compara as respostas do agente com o catálogo e aponta divergências.
• Publicação de página: confere domínio, links e rastreamento antes de colocar no ar.
• Manutenção: define arquivos a consultar, testes a rodar e evidências a registrar.

Erros comuns e limites das skills

O erro mais comum é escrever uma descrição genérica, como ajuda com tarefas de marketing. O Claude Code não consegue saber quando acionar uma skill assim, e ela fica esquecida. O segundo erro é criar uma skill gigante que tenta cobrir tudo; procedimentos menores e bem delimitados são mais fáceis de acionar, testar e corrigir.

Também vale lembrar o limite: a skill não treina o modelo nem garante execução correta. Ela orienta, mas a verificação do resultado real continua necessária. Uma skill que integra com WhatsApp ainda depende de credenciais, permissões e de alguém conferindo se a mensagem de fato saiu como deveria. A skill reduz o retrabalho, mas não elimina a conferência.

• Descrição vaga faz a skill nunca ser acionada.
• Skill grande demais é difícil de testar; divida em procedimentos menores.
• Skill não retreina o modelo nem substitui a verificação do resultado.
• Quando a skill falhar numa tarefa, corrija o procedimento no próprio SKILL.md.