Como criar sua própria skill no Claude Code passo a passo

Toda vez que tu repete a mesma tarefa chata num projeto, tem uma skill esperando pra nascer ali

A ideia é essa: em vez de explicar a mesma coisa pro Claude Code toda santa sessão, tu empacota aquilo numa skill própria e ele passa a saber sozinho quando usar

E o melhor, uma skill não é bicho de sete cabeças

É literalmente uma pasta com um arquivo SKILL.md dentro, mais uns arquivos de apoio opcionais (templates, scripts, documentos de referência) quando o caso pede. Nada de API, nada de upload, é tudo no seu sistema de arquivos

No fim deste post tu sai sabendo montar a tua do zero, entender cada campo e testar na prática

O que você precisa antes de começar

Antes de sair criando pasta, três coisas na cabeça

1) Claude Code instalado e rodando no seu terminal, porque é ele quem vai enxergar e carregar a skill

2) Saber onde a skill mora, e isso muda tudo. Tem dois lugares:

• ~/.claude/skills/ é a skill pessoal, fica disponível em TODOS os seus projetos
• .claude/skills/ (dentro do repositório) é a skill de projeto, vale só naquele projeto

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

A regra prática é simples: se é algo do seu jeito de trabalhar, vai na pessoal. Se é regra específica daquele repo (a stack, os padrões do time), vai na de projeto e sobe junto no Git

3) Uma noção básica de Markdown e YAML, nada avançado. Se tu já escreveu um README, tu já sabe Markdown. E o YAML aqui é só um cabecerinho com dois ou três campos, tu vai ver que é tranquilo

Se tu quiser entender melhor a diferença entre skills e os antigos comandos de barra antes de pôr a mão na massa, dá uma olhada em como migrar slash commands para skills, ajuda a situar

Passo a passo para criar sua skill personalizada

Bora montar uma skill do zero. Vou usar como fio condutor uma skill que resume mudanças do projeto, mas o esqueleto serve pra qualquer coisa

1. Escolha o escopo e crie a pasta

Primeiro tu decide: pessoal ou de projeto? Depois cria a pasta. O nome da pasta importa MUITO, guarda isso

mkdir -p ~/.claude/skills/summarize-changes

O exemplo oficial da documentação segue exatamente esse caminho: ~/.claude/skills/summarize-changes/SKILL.md

O erro comum deste passo: achar que o nome da pasta é só organização. Não é. Numa skill pessoal ou de projeto, o comando que tu vai invocar vem do NOME DA PASTA, então escolhe um nome curto e que faça sentido de digitar

2. Crie o SKILL.md com frontmatter e corpo

Dentro da pasta, cria o arquivo SKILL.md. Ele tem duas partes bem separadas: o frontmatter YAML, que fica entre os marcadores ---, e o corpo em Markdown logo abaixo, com as instruções que o Claude vai seguir quando a skill rodar

---
name: Resumir mudanças
description: Use quando o usuário quiser um resumo das alterações recentes do projeto, do diff ou do que mudou desde o último commit
---

# Resumir mudanças

Quando esta skill rodar:

1. Verifique o estado do repositório e o diff atual
2. Agrupe as mudanças por área (o que mexeu e por quê)
3. Entregue um resumo curto, em tópicos, sem enrolação

O erro comum deste passo: esquecer um dos --- ou grudar o frontmatter no corpo. Os dois marcadores têm que existir, um abrindo e um fechando, senão o cabeçalho não é lido como YAML

3. Preencha name e description direito

Esses dois campos fazem trabalhos diferentes

O name é só o rótulo exibido na listagem de skills. Repetindo pra não esquecer: ele NÃO é o comando, o comando vem da pasta

Já a description é a peça mais importante do arquivo. É ela que informa ao Claude QUANDO usar a skill, é o que ele lê pra decidir se puxa aquilo ou não. Quanto mais clara a description sobre o gatilho, melhor o carregamento automático funciona

O erro comum deste passo: description vaga tipo "ajuda com o projeto". Assim o Claude não sabe quando acionar e a skill nunca entra sozinha. Descreve a SITUAÇÃO que dispara a skill, com as palavras que o usuário usaria

4. Opcional: restrinja com disable-model-invocation e allowed-tools

O frontmatter aceita mais dois campos além de name e description

O allowed-tools limita quais ferramentas a skill pode usar. Se a tua skill só lê arquivos e roda um comando, tu trava ali e pronto:

---
name: Resumir mudanças
description: Use quando o usuário quiser um resumo das alterações recentes do projeto
allowed-tools: Bash, Read, Edit
---

Tem também o disable-model-invocation, pra quando tu NÃO quer que o Claude decida sozinho puxar a skill, deixando ela só pra invocação manual

O erro comum deste passo: apertar demais o allowed-tools e a skill não conseguir fazer o que precisa. Se ela vai editar arquivo, Edit tem que estar na lista

5. Adicione arquivos de apoio (se precisar)

A skill não vive só do SKILL.md. Tu pode jogar na mesma pasta templates, scripts e documentos de referência que o corpo do Markdown manda usar. É aqui que uma skill vira algo sob medida pro teu projeto, com os padrões que só ele tem

O erro comum deste passo: encher a pasta de arquivo e não referenciar no SKILL.md. Arquivo de apoio que o corpo não menciona é peso morto, o Claude não adivinha que ele existe

6. Teste a skill

Com o arquivo salvo, volta pro Claude Code. Digitando / no prompt tu vê o menu de skills disponíveis e seleciona a tua na mão pra conferir se roda

O outro jeito é deixar o carregamento automático agir: as skills são puxadas sob demanda, o modelo decide o momento com base na description. Descreve a situação que dispara a skill e vê se ele aciona sozinho quando tu pede algo do tipo

O erro comum deste passo: a skill não aparecer no menu por causa de pasta no lugar errado. Confere se ela está em ~/.claude/skills/ (pessoal) ou em .claude/skills/ do projeto certo

Na prática: por que vale montar suas próprias skills

Eu uso skills em TODOS os meus projetos com Claude Code, e é aí que a coisa fica interessante

No vídeo abaixo eu mostro esse fluxo rodando de ponta a ponta: uma skill pra fazer brainstorm e planejar, outra pra virar aquilo num plano de implementação, a execução com subagentes e TDD, e no fim uma skill de frontend redesenhando a interface

Numa dessas execuções, uma tarefa ficou rodando quase 10 minutos na minha máquina, sozinha, e o plano de implementação fechou com 14 tarefas concluídas. Ou seja, tu monta o trilho e vira as costas

Agora, o pulo do gato pra mim são as skills customizadas. Baixar skill pronta de repositório é ótimo pra começar, mas cada projeto varia de tecnologia, então eu prefiro criar skills sob medida pro que aquele projeto precisa

Um exemplo que eu curto: uma skill de segurança, que junta vários requisitos e faz uma análise detalhada adaptada àquele código específico, e não uma checagem genérica que serve pra todo mundo e pra ninguém

E tem um atalho preguiçoso (do bom): dá pra pedir pro próprio Claude Code criar a skill pra ti. Tu descreve o que quer que ela faça e ele monta o SKILL.md

Ideias de skills para automatizar seu projeto

Se tu ficou sem saber por onde começar, aqui vão pautas de skill que valem o esforço

• Resumir mudanças no estilo summarize-changes, pra ela varrer o diff e te devolver um resumo do que mexeu antes de tu commitar
• Padronizar tarefas repetitivas do repo, aquele passo a passo que tu explica toda vez (como nomear branch, como estruturar um módulo novo, o padrão de teste do time)
• Análise de segurança sob medida, com os requisitos que importam pra AQUELA stack, não uma lista genérica
• Rotina de release ou de commit, empacotando a sequência que tu sempre faz na mão

Pra essa última, aliás, vale cruzar com o jeito de usar o Claude Code junto com o Git, porque muita tarefa repetitiva do projeto acaba passando por commit, PR e histórico

O segredo é olhar pro teu próprio fluxo e perguntar: o que eu explico pro Claude toda semana? Aquilo ali é a tua próxima skill

Conclusão

Criar skill Claude Code é basicamente isso: uma pasta, um SKILL.md com frontmatter e corpo, e um teste rápido digitando / no prompt

O resto é escolher bem o escopo (pessoal em ~/.claude/skills/ ou de projeto em .claude/skills/) e caprichar na description, que é o que faz o Claude saber a hora de usar

Quando quiser acelerar, tem dois caminhos oficiais que ajudam. O plugin Skill Creator, que traz modos de criar, avaliar, melhorar e testar skills, instalável com:

/plugin install skill-creator@claude-plugins-official

E o repositório público anthropics/skills da Anthropic, ótimo pra abrir uns exemplos reais e ver como as skills são escritas por dentro

Agora escolhe uma tarefa chata do teu projeto e transforma ela na tua primeira skill… até o próximo post!