Madureira
← Todas as edições

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.

Abrir no ChatGPTAbrir no Claude

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.