IA e Automações · 18 de novembro de 2026 · 4 min
Como criar uma skill no Claude Code: o passo a passo que eu sigo
Uma skill é uma pasta com um SKILL.md: cabeçalho com nome e descrição, instruções embaixo. O passo a passo, onde ela mora e o erro que desligou as minhas.
- O problema
- Você escreveu instruções boas para a IA e elas não são usadas, ou nem sabe onde colocar uma skill para o Claude Code achar.
- Para aplicar
- Crie uma pasta em ~/.claude/skills/ com um SKILL.md para a instrução que você mais colou esta semana, escreva a descrição com três frases que você usaria para pedir aquilo e teste numa sessão nova.
Para criar uma skill no Claude Code, você cria uma pasta com um arquivo SKILL.md dentro. O arquivo começa com um cabeçalho com name e description e, embaixo, as instruções. A pasta vai em ~/.claude/skills/ para valer em todos os seus projetos, ou em .claude/skills/ dentro de um projeto para valer só nele. O Claude lê a descrição de todas as skills no começo e só carrega o corpo quando a tarefa combina com a descrição.
Já escrevi sobre quais skills valem numa operação de marketing. Este texto é o lado mecânico: como a skill é montada, onde ela mora e o erro bobo que deixou as minhas desligadas por meses.
O que é uma skill do Claude?
Um pacote de instrução que a IA carrega sozinha quando precisa. Pode ser só texto, como a voz de uma marca ou a régua de um formato, ou texto com arquivos de apoio: exemplos, modelos, até um script que a skill manda rodar.
Passo a passo
1. Crie a pasta e o arquivo
~/.claude/skills/revisar-legenda/
SKILL.md
O nome da pasta é o nome da skill. Use minúsculas e hífen.
2. Escreva o cabeçalho
---
name: revisar-legenda
description: Revisa legenda de Instagram antes de publicar. Usar quando o pedido for "revisa essa legenda", "confere a legenda", "legenda pronta?" ou quando um carrossel estiver para subir.
---
A descrição é o gatilho. Ela precisa ter as palavras que você realmente digita quando quer aquilo, porque é por ela que o Claude decide se a skill entra.
3. Escreva o corpo
Embaixo do cabeçalho, em markdown: o processo, as regras, um exemplo bom e um exemplo ruim. Regra com motivo funciona melhor que regra solta, porque o modelo consegue aplicar o motivo num caso que você não previu.
4. Teste com as suas palavras
Abra uma sessão nova e peça a tarefa do jeito que você pediria numa terça corrida, sem citar o nome da skill. Se a resposta vier sem as suas regras, a descrição está vaga. Reescreva e teste de novo.
5. Deixe o material de apoio fora do corpo
Exemplo longo, tabela e modelo vão em arquivos separados na mesma pasta, com o corpo dizendo quando abrir cada um. O corpo fica curto, e o detalhe só entra quando precisa.
O erro que deixou as minhas desligadas
Minhas skills moram dentro do vault, a pasta de texto da agência, porque é ali que elas são editadas e versionadas junto com o resto das regras. Só que o Claude Code procura skill em ~/.claude/skills/, e não no vault.
Durante meses, as skills de voz dos clientes existiram, foram editadas e melhoradas, e nunca dispararam. Não apareceu aviso nenhum. A peça saía sem elas e parecia só um dia ruim da IA.
Em 19 de agosto escrevi um instalador de poucas linhas que cria um atalho (um symlink) de cada skill do vault para a pasta que o Claude lê. Rodei, e as 20 passaram a resolver. Hoje skill nova do vault só existe depois de passar por esse instalador, e isso está escrito no índice das skills: nome que não está lá não dispara.
Como eu organizo muitas skills
- Um índice de roteamento. Um arquivo que diz, por cliente e por formato, qual skill chamar. Quando duas disputam o mesmo pedido, é ali que eu resolvo.
- Desligar em vez de apagar. Skill que não uso mais vai para uma pasta de arquivo datada e fica desligada na configuração. Em 11 de novembro arquivei de uma vez dezenas que estavam paradas.
- Uma skill que reprova. A última que roda antes de qualquer peça sair é um validador: procura travessão, hashtag, aberturas e fechos que viraram tique, e peça sem nenhum detalhe concreto. Ela não escreve nada. Só barra.
Quanto texto cabe numa skill?
O suficiente para alguém do time fazer a tarefa do seu jeito sem te perguntar nada. A minha de voz pessoal tem linha editorial, pontuação, gancho, ritmo e um checklist no fim. A de validar cabe numa página. Tamanho bom é o que a tarefa pede, e o que passar disso vai para arquivo de apoio.
O que fazer amanhã
Escolha a instrução que você mais colou no chat esta semana, crie a pasta em ~/.claude/skills/ com um SKILL.md e escreva a descrição com três frases que você usaria para pedir aquilo. Abra uma sessão nova, peça do seu jeito e veja se ela dispara. Se não disparar, o problema está na descrição.