Como criar uma skill personalizada do Claude Code (com um exemplo real que funciona)

este artigo é baseado no Claude Code CLI. Skills são um recurso que muda rápido e alguns detalhes podem mudar; cito minhas fontes no final.

O que é uma skill personalizada no Claude Code? (definição rápida)

Uma skill personalizada é um pacote de instruções - uma pasta mais um arquivo SKILL.md - que ensina o Claude Code a fazer um fluxo de trabalho repetível exatamente do jeito que você quer. Em vez de redigitar todo aquele prompt "formate este post do blog no padrão X, adicione um índice, escreva a meta..." toda vez, você empacota essa receita uma única vez como uma skill. A partir daí, o Claude Code reconhece quando usá-la e segue os seus passos.

Quem está começando costuma confundir uma skill com outras duas coisas, então vamos separá-las rapidinho:

• Skill - conhecimento ou um fluxo de trabalho que o Claude Code invoca automaticamente quando o contexto combina com a sua description. Você não digita nenhum comando.
• Slash command - um atalho que você digita de propósito (por exemplo /commit). Veja os detalhes em slash commands no Claude Code.
• Subagent - um "subassistente" que roda tarefas pesadas no seu próprio contexto separado. Veja o guia de subagents.

Se os quatro conceitos ainda se misturam na sua cabeça, o artigo sobre skills vs subagents vs hooks vs MCP destrincha tudo com mais cuidado. E se você ainda não tem clareza sobre o que fundamentalmente é uma skill, leia primeiro o que são as Skills do Claude Code e depois volte aqui para de fato construir uma. Este artigo é 100% focado em colocar uma skill de verdade para rodar no Claude Code CLI.

Como uma skill funciona? (divulgação progressiva)

Entenda esse mecanismo e você vai escrever skills corretamente desde o início. O Claude Code não enfia o conteúdo inteiro de cada skill no contexto - isso queimaria tokens e adicionaria ruído. Ele usa divulgação progressiva (carregar sob demanda), em três camadas:

• Camada 1 - sempre residente: o Claude Code mantém apenas o name e a description de cada skill no contexto. É a "placa de sinalização" que diz quais skills existem e para que servem.
• Camada 2 - carregada ao combinar: só quando o contexto da conversa combina com a description é que o corpo do SKILL.md é lido para o contexto.
• Camada 3 - carregada sob demanda: arquivos de apoio como reference.md ou scripts/ só são abertos quando o Claude realmente precisa deles.

A consequência mais importante: a description é o interruptor de invocação automática. Se a sua description não contém as palavras-chave de contexto que um usuário realmente vai dizer, o Claude Code nunca vai abrir o corpo da sua skill para lê-lo - por melhor que esse corpo esteja escrito. É por isso que a maioria das skills que "não rodam" falha logo na linha da description, não no conteúdo.

Configuração: onde a skill mora (pessoal vs projeto)

É aqui que a maioria dos tutoriais em inglês pula etapas, porque eles falam do app web claude.ai. Com o Claude Code CLI, uma skill mora no sistema de arquivos e você tem dois lugares para colocá-la, escolhidos pela finalidade:

A regra simples: o seu próprio fluxo vai em ~/.claude/skills/; uma convenção de time ou projeto inteiro vai em .claude/skills/ dentro do repositório, e aí você faz commit no git para todo mundo receber.

O único pré-requisito é ter o Claude Code instalado (se ainda não tiver, veja o guia de instalação do Claude Code). Você pode conferir suas skills existentes perguntando direto numa sessão do Claude Code - por exemplo o prompt "liste as skills que você tem agora" - ou abrindo a pasta ~/.claude/skills/. Depois de criar uma skill nova, lembre de reiniciar para que ela seja escaneada.

Como criar uma skill personalizada do Claude Code em 5 passos

Aqui está o fluxo completo. Vou usar um exemplo fixo o tempo todo - uma skill blog-formatter que arruma um post de blog em Markdown cru - para ficar fácil de visualizar, mas a abordagem serve para qualquer fluxo.

Passo 1 - Escolha um fluxo repetível

Não tenha pressa de escrever uma skill para algo que você nunca fez na mão. Dica prática: faça manualmente com o Claude Code algumas vezes até ele produzir exatamente o resultado que você quer, e só então destile aquele prompt/fluxo em uma skill. Uma boa skill é a cristalização de um processo comprovado, não um chute.

Alguns bons candidatos para começar: formatar um post de blog no seu padrão, gerar mensagens de commit na convenção do projeto, escrever testes unitários a partir de um template existente, ou revisar docs de API. Escolha algo que você faz pelo menos uma vez por semana - é aí que o ROI aparece.

Passo 2 - Crie a árvore de pastas + o arquivo SKILL.md

Uma skill mínima precisa apenas de uma pasta e de um arquivo SKILL.md. Você adiciona arquivos de apoio quando precisar. A árvore de pastas completa fica assim:

~/.claude/skills/
 blog-formatter/
 SKILL.md # required - the main instructions
 reference.md # optional - long details, loaded on demand
 scripts/
 format.py # optional - a bundled script

Crie a pasta pelo terminal:

mkdir -p ~/.claude/skills/blog-formatter
cd ~/.claude/skills/blog-formatter

Nomeie a pasta em kebab-case, curto e descritivo do que a skill faz (blog-formatter, commit-msg). Para uma skill pequena, um único SKILL.md já basta - só separe em reference.md ou scripts/ quando o corpo começar a ficar longo.

Passo 3 - Escreva o front matter YAML (name + description)

Abra o SKILL.md. Bem no topo há um bloco de front matter YAML entre duas linhas ---, contendo dois campos obrigatórios: name e description. Esta é a parte que decide se a skill se autoinvoca ou não, então escreva com cuidado.

A fórmula de uma boa description: o que ela faz + QUANDO usá-la + palavras-chave de gatilho que o usuário realmente vai falar em voz alta. Compare:

A da esquerda é vaga, não tem contexto, e o Claude não faz ideia de quando chamá-la. A da direita deixa claro o quê, quando, e as frases exatas que os usuários costumam digitar. Escreva a description como se estivesse dizendo a um colega novo "é nessas horas que você me chama".

Passo 4 - Escreva o corpo de instruções

Logo abaixo do front matter está o corpo em Markdown - é o fluxo que o Claude Code lê e segue quando a skill é chamada. Um bom corpo deve incluir:

• Propósito - qual problema esta skill resolve.
• Quando usar - reafirme o contexto (reforça a description).
• Entradas a pedir - se faltar informação, o que perguntar ao usuário.
• Os passos - um procedimento claro e numerado.
• Padrão de saída - como é um resultado correto.
• Erros a evitar + um exemplo de entrada/saída.

Regra de ouro: ser conciso é essencial. Um corpo inchado queima contexto e distrai o Claude. Quando as instruções ficarem longas (tabelas de consulta, muitos exemplos), separe-as em reference.md e aponte para ele a partir do corpo - graças à divulgação progressiva, o arquivo de apoio só carrega quando necessário.

Passo 5 - Recarregue & teste a skill

O Claude Code escaneia a pasta de skills na inicialização, então depois de criar ou editar o SKILL.md você precisa reiniciar: digite /exit e reabra a sessão do Claude Code. Depois teste com um prompt natural que combine com a description - por exemplo: "Formate para mim o post do blog em draft.md." Se você escreveu bem, o Claude Code reconhece e chama a skill blog-formatter. Confirme que ele usou a skill certa (o Claude costuma informar qual skill foi invocada) e depois verifique se o resultado atende ao padrão que você definiu no Passo 4.

Um exemplo completo de skill personalizada (copie, cole e rode)

Aqui está um SKILL.md completo que eu realmente escrevi e usei. Copie tudinho para ~/.claude/skills/commit-msg/SKILL.md, reinicie e experimente na hora:

---
name: commit-msg
description: Generate a Conventional Commits message from the currently staged changes. Use when the user says "write a commit", "commit message", "make a commit message", or right before committing code.
---

# Generate a Conventional Commits message

## Purpose
Read the staged diff and write a short, standards-compliant commit message.

## When to use
When the user is about to commit or asks for a commit message.

## Inputs to ask for
If nothing is staged, run `git diff --staged` to see the changes.
If it's still empty, ask the user: "Have you run `git add` yet?"

## Steps
1. Run `git diff --staged` to read the changes.
2. Determine the type: feat / fix / docs / refactor / test / chore.
3. Determine the scope (the main module/folder changed).
4. Write the subject line: `type(scope): short description` - max 72 chars, present tense.
5. If the change is complex, add 1-3 bullet points in the body explaining "why".

## Output standard
- Subject ≤ 72 chars, no trailing period.
- Description is clear and matches what was actually done.
- Do NOT invent changes that aren't in the diff.

## Mistakes to avoid
- Don't use the wrong type (adding a feature but labeling it `fix`).
- Don't write vague messages like "update code", "misc fixes".

## Example
Input diff: add an email validation function in `src/auth/`.
Output:
feat(auth): add email format validation on signup

Resultado real: uma vez carregada, eu só digito "write a commit" e o Claude Code roda git diff --staged, classifica certo e devolve uma mensagem que segue o padrão - sem eu reafirmar a convenção toda vez.

Uma limitação observada (com sinceridade): se o diff for enorme ou misturar vários tipos de mudança, a mensagem combinada às vezes escolhe um type que não é o mais adequado - aí você ainda deve dividir o commit ou corrigir na mão. A skill acerta 90% dos casos; ela não substitui totalmente o seu julgamento.

Teste & depure quando uma skill não dispara

Uma skill pronta que o Claude Code "ignora" é bem comum. Aqui está o checklist que eu percorro, em ordem, quando uma skill se recusa a disparar:

1. Sintaxe YAML quebrada. Um --- faltando, indentação errada ou um caractere perdido no front matter fazem a skill inteira ser silenciosamente ignorada. Confira o bloco de front matter primeiro.
2. Description vaga / faltando palavras-chave de contexto. Esse é o culpado número um. Se o seu prompt não tem nenhuma expressão que coincida com a description, a skill não é chamada. Adicione as palavras exatas que um usuário real diria.
3. Não reiniciou o Claude Code. A pasta de skills só é escaneada na inicialização. Depois de editar, você precisa dar /exit e reabrir.
4. Nome duplicado ou caminho errado. Duas skills com o mesmo name, ou um SKILL.md na pasta errada (maiúsculas/minúsculas trocadas, nível errado) não carregam.
5. Corpo longo demais, gerando ruído. Um corpo inchado pode dificultar que o Claude siga o procedimento. Enxugue e mova o excesso para reference.md.

Dica rápida de diagnóstico: force uma chamada manual para isolar o problema. Peça direto: "Use a skill blog-formatter para fazer isto." Se a chamada forçada funcionar bem, o bug está na description (ela não consegue autoinvocar). Se a chamada forçada ainda falhar, o bug está no YAML ou no caminho.

Compartilhe & publique sua skill

Depois de escrever uma boa skill, você deveria compartilhá-la - e essa é a parte que quase nenhum tutorial em inglês cobre. Há três formas, da mais simples à mais caprichada:

1. Faça commit no repositório para o time inteiro. Coloque a skill em .claude/skills/ dentro do projeto e dê git commit. Quem clonar o repositório recebe aquela skill na hora - o jeito mais rápido de padronizar um processo para um time.
2. Publique no GitHub para a comunidade. Crie um repositório de skills; outras pessoas clonam ou copiam a pasta da skill para o próprio ~/.claude/skills/. Inclua um README descrevendo o que cada skill faz.
3. Empacote como um plugin. Com várias skills relacionadas, você pode agrupá-las em um plugin para uma distribuição mais organizada (tenho um artigo separado sobre plugins do Claude Code).

Bônus: skills usam um padrão aberto (Markdown + front matter YAML), então um SKILL.md escrito para o Claude Code muitas vezes é reutilizável, ou facilmente convertível, em outras ferramentas como Cursor ou Copilot - escreva uma vez, use em vários lugares.

Não quer escrever as suas? Use mais de 108 skills prontas

Escrever suas próprias skills é uma habilidade que vale a pena aprender - ela te dá controle total para ajustar tudo ao seu fluxo exato, e eu recomendo a qualquer pessoa que use o Claude Code a sério. Mas se você quer um conjunto de skills pronto para produção agora mesmo, sem construir cada uma, o Engineer Kit vem com mais de 60 skills prontas (frontend, backend, banco de dados, DevOps, code review) e é um atalho que vale considerar.

Pegue o atalho: o pacote de skills prontas do AgentKit — agora $149 (de $198) reúne mais de 108 skills para o Claude Code - usáveis na hora em vez de escrever cada arquivo você mesma. Sendo honesta: você ainda deveria saber escrever skills (como neste artigo) para customizar as partes especializadas; o kit cuida do trabalho braçal repetitivo.

Perguntas frequentes (FAQ)

Como uma skill difere de um subagent?

Uma skill é um pacote de instruções que o Claude Code carrega no contexto atual quando o contexto combina, rodando na mesma sessão. Um subagent é um subassistente que roda tarefas pesadas no seu próprio contexto separado, de forma independente. Trabalho leve e repetível vai para uma skill; trabalho grande que precisa de isolamento vai para um subagent.

Onde fica o SKILL.md?

Coloque em ~/.claude/skills/<name>/SKILL.md se quiser usá-lo em todos os projetos (pessoal), ou em .claude/skills/<name>/SKILL.md dentro de um repositório se quiser versionar e compartilhar com o time (projeto). Cada skill é a sua própria pasta contendo um arquivo SKILL.md.

Por que minha skill não roda automaticamente?

Geralmente porque a description está vaga e faltam as palavras-chave que você de fato diz no seu prompt. Verifique também: se o front matter YAML tem erro de sintaxe, se você reiniciou o Claude Code, e se o caminho da pasta está correto.

Preciso reiniciar depois de criar ou editar uma skill?

Sim. O Claude Code só escaneia a pasta de skills na inicialização, então depois de criar ou editar o SKILL.md você precisa dar /exit e reabrir a sessão para a skill ser carregada.

Uma skill escrita para o Claude Code também pode ser usada no claude.ai?

O padrão de skill (Markdown + front matter YAML) é aberto, então o conteúdo costuma ser reutilizável. Porém, o carregamento é diferente: o Claude Code usa uma pasta de arquivos local (~/.claude/skills/), enquanto o app web claude.ai as carrega do seu próprio jeito. Trate um arquivo SKILL.md como um ativo reutilizável, não como algo idêntico e plug-and-play em todo lugar.

Existem skills prontas que eu possa usar já?

Sim. Se você não quer começar do zero, kits como o AgentKit reúnem mais de 108 skills para o Claude Code em vários domínios. Você ainda deveria saber escrever as suas para customizar, mas um kit te poupa o trabalho braçal repetitivo.

Conclusão + próximos passos

Skills personalizadas são a forma mais eficaz de "ensinar" o Claude Code a trabalhar exatamente no seu padrão sem repetir prompts. Comece pequeno: escolha um fluxo que você faz toda semana, destile-o em um SKILL.md, escreva uma description bem clara, teste e itere. Leia o que são as Skills do Claude Code em seguida para fixar os fundamentos, e slash commands no Claude Code para combinar skills com atalhos deliberados. E quando você precisar de um conjunto de skills pronto para produção agora, em vez de escrever cada uma, considere um kit pronto (veja o quadro abaixo).

Fontes: Claude Code Docs - Skills (Anthropic, atualizado em 2026) para a estrutura do SKILL.md e o mecanismo de carregamento. Skills são um recurso em evolução; os detalhes podem mudar entre versões.