Criando sua primeira skill do Claude Code, do zero (com um exemplo real)

Criar uma skill do Claude Code é mais simples do que parece — é uma pasta e um arquivo de texto. O que quase ninguém conta é a parte chata: a primeira versão quase sempre não dispara, e o motivo não é o código, é o cabeçalho. Vou fazer uma skill de verdade aqui, incluindo o erro, porque é ele que ensina.

Se você ainda está em dúvida se vale criar uma, comece por quando skill vale a pena (e quando não). Se já sabe que quer, segue comigo.

O exemplo: uma skill de mensagem de commit

Vou usar um caso real e sem graça de propósito, porque é justamente o tipo de coisa que rende: toda vez que eu commito, quero a mensagem no mesmo formato — um resumo curto no imperativo, uma linha em branco, e um parágrafo explicando o porquê, não o o quê. Eu explicava isso pro Claude toda vez. Terceira vez, virou skill.

Passo 1: a pasta e o arquivo

Skills pessoais (valem em todos os seus projetos) moram em ~/.claude/skills/. Cada skill é uma pasta com o nome dela, e dentro um SKILL.md:

~/.claude/skills/
└── mensagem-de-commit/
    └── SKILL.md

Se você quer que a skill valha só num projeto e vá junto no git pro time, o caminho é .claude/skills/ dentro do projeto, em vez de ~/.claude/. O resto é idêntico.

Passo 2: o cabeçalho (a parte que decide tudo)

O SKILL.md começa com um bloco entre três traços — o frontmatter — com dois campos: name e description. Minha primeira versão foi essa:

---
name: mensagem-de-commit
description: Ajuda com mensagens de commit.
---

Escreva a mensagem no imperativo, curta na primeira linha,
depois uma linha em branco e um parágrafo com o motivo da mudança.

Parece razoável. E não funcionou — o Claude nunca puxava a skill sozinho. Eu commitava, ele escrevia a mensagem do jeito genérico dele, e a skill ficava lá parada. Levei um tempo pra entender o porquê.

Passo 3: por que não disparou

A description não é um resumo bonitinho — é o gatilho. É por ela que o Claude decide, no meio da conversa, se aquela skill é relevante agora. "Ajuda com mensagens de commit" é vago: não diz quando ativar. O Claude não tinha como saber que "vou commitar isso" deveria acordar a skill.

Escreva a descrição pensando "em que situação eu quero que isso apareça?" — e cite essas situações com as palavras que você realmente usa. A descrição é para a máquina decidir, não para um humano ler.

A versão que funcionou foi essa:

---
name: mensagem-de-commit
description: >
  Use ao criar um commit, escrever mensagem de commit, ou quando o
  usuário pedir para commitar, "faz o commit", "gera a mensagem".
  Aplica o padrão da casa: imperativo no resumo, porquê no corpo.
---

Ao escrever a mensagem de commit, siga este formato:

1. Primeira linha: resumo no imperativo, até ~50 caracteres.
   "Corrige X", "Adiciona Y" — nunca "Corrigido" nem "Adicionando".
2. Uma linha em branco.
3. Corpo: explique o MOTIVO da mudança, não o que o diff já mostra.
   Se a mudança conserta um bug, descreva o comportamento errado.

Nunca invente escopo que não está no diff. Se o commit faz duas
coisas sem relação, sugira separar em dois.

Repare no que mudou. A descrição agora lista gatilhos concretos — inclusive as frases que eu digito de verdade ("faz o commit"). E as instruções ficaram específicas e com um limite claro ("nunca invente escopo"), porque instrução vaga produz resultado vago.

Passo 4: testar

Skill não tem botão de "salvar e ativar" — ela passa a valer assim que o arquivo existe. Pra testar, eu faço a coisa que deveria acionar o gatilho e observo se a skill entra. No caso: deixo uma mudança pronta e peço "faz o commit". Se a mensagem sai no formato certo, disparou. Se sai genérica, a descrição ainda não está boa.

Quando quiser forçar a skill sem depender do gatilho — útil justamente pra testar —, dá pra chamar pelo nome com barra: /mensagem-de-commit. Se funciona na chamada direta mas não dispara sozinha, o problema está confirmado na description, não nas instruções.

Passo 5: iterar sem inchar

A tentação depois que funciona é adicionar regra em cima de regra. Resisti. Uma skill enorme tem dois problemas: fica difícil pra você manter, e afoga a instrução que importa no meio de dez que não importam. A minha tem menos de vinte linhas e resolve o que precisa.

Se a skill começa a crescer, geralmente é sinal de que ela está tentando fazer duas coisas — e duas coisas pedem duas skills, cada uma com seu gatilho. Uma skill, um trabalho.

O resumo que cabe num post-it

• Skill = pasta + SKILL.md com name e description.
• A descrição é o gatilho — escreva-a listando quando ativar, com as palavras que você usa.
• Instrução específica e com limites ("nunca faça X") rende melhor que instrução genérica.
• Teste chamando pelo nome (/skill) pra isolar se o problema é gatilho ou conteúdo.
• Pequena e focada. Cresceu demais? Vira duas.

É só isso. A primeira você cria em cinco minutos; o que leva jeito é escrever a descrição pensando na máquina que vai lê-la. Depois dessa, dá uma olhada na seleção de skills do site pra roubar ideias de gatilho e de estrutura de quem já testou bastante.