Você usou o Claude por uma semana e continua digitando a mesma coisa. Toda vez que faz commit de código, cola as mesmas três regras sobre o formato do commit. Toda vez que escreve um documento, reexplica seu estilo. O Claude faz bem, depois esquece no momento em que o chat termina, e amanhã você digita tudo de novo.
Uma skill resolve isso. É uma pequena pasta que você escreve uma vez e ensina ao Claude um fluxo de trabalho permanentemente, para que ele aplique em toda sessão sem você precisar pedir.
Aqui está como funciona, de forma resumida: uma skill é uma pasta com um arquivo dentro. O Claude mantém um resumo de uma linha dela visível o tempo todo, e carrega as instruções completas apenas quando sua solicitação corresponde. Esse é o mecanismo inteiro.
Neste guia, criamos uma skill real do zero: commit-messages, que escreve commits git no seu formato exato. Se você tem o Claude instalado e mais nada, pode seguir cada passo.
O que você vai ter no final
No núcleo, uma skill é uma pasta com um arquivo obrigatório, SKILL.md. Três pastas opcionais entram depois, conforme a skill cresce:
1seu-nome-da-skill/2├── SKILL.md # Obrigatório - o arquivo principal da skill3├── scripts/ # Opcional - código executável4├── references/ # Opcional - documentação5└── assets/ # Opcional - modelos, etc.
O SKILL.md em si tem duas partes: um cabeçalho curto que diz ao Claude quando usar a skill, e instruções abaixo que dizem ao Claude o que fazer. O motivo da divisão é importante. O Claude lê o cabeçalho constantemente, então sempre sabe que a skill existe, mas só carrega as instruções quando sua solicitação corresponde. Mantenha essa distinção em mente, porque quase tudo o mais neste guia decorre disso.
Crie-a
As skills ficam em uma pasta chamada .claude/skills dentro do seu diretório home, que tanto o Claude Code quanto o aplicativo desktop leem. Ela está oculta e provavelmente ainda não existe, então a maneira mais rápida de criá-la, junto com a pasta da sua skill, é um único comando.
No Mac, abra o Terminal e execute:
1mkdir -p ~/.claude/skills/seu-nome-da-skill
No Windows, abra o PowerShell e execute:
1New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills\seu-nome-da-skill"
O nome da pasta não é cosmético. O Claude o usa como identificador da skill, e uma regra de formatação pega mais pessoas do que qualquer outra:
- Use kebab-case: notion-project-setup ✔
- Sem espaços: Notion Project Setup ✖
- Sem sublinhados: notion_project_setup ✖
- Sem maiúsculas: NotionProjectSetup ✖
Dentro dessa pasta, crie um arquivo chamado exatamente SKILL.md e abra-o em qualquer editor de texto. Tudo daqui em diante é o que vai nesse arquivo.
Projete-a antes de escrevê-la
As skills que funcionam começam com duas decisões, tomadas antes de escrever uma linha do arquivo. Ambas parecem dispensáveis e nenhuma é.
Primeiro, decida exatamente quando a skill deve disparar. Escreva duas ou três situações reais nas palavras que um usuário realmente digitaria:
- "commitar essas alterações"
- "escrever uma mensagem de commit para este diff"
- "stage e commit"
Isso não é trabalho à toa. Essas frases se tornam o material bruto para sua descrição e seus testes mais tarde, e uma skill projetada sem elas tende a ser vaga exatamente da maneira que a impede de disparar.
Segundo, decida como saberá que funciona. O critério que importa acima de todos os outros é se a skill carrega sozinha, sem você nomeá-la. Se você tiver que invocá-la manualmente toda vez, a skill tecnicamente executa, mas falhou em seu trabalho real. Vale a pena observar junto com isso: se ela conclui a tarefa sem você corrigir no meio do caminho, e se ela dá o mesmo formato de resultado em sessões separadas.
A descrição é o que faz ou quebra
De tudo no arquivo, a descrição no cabeçalho é a que mais trabalha, porque é a única parte que o Claude lê ao decidir se carrega a skill ou não. Suas instruções podem ser impecáveis e isso não importaria, já que o Claude nunca chega até elas se a descrição não corresponder. É aqui que a maioria das skills que "não funcionam" realmente falha.
Uma descrição forte responde a duas perguntas em uma frase: o que a skill faz e quando o Claude deve usá-la. Essa segunda metade é a que as pessoas deixam de fora.
Aqui está a diferença:
1# fraca - diz o que é, não dá ao Claude nada para corresponder a uma solicitação2description: Ajuda com commits git.34# forte - nomeia os momentos em que deve disparar5description: Escreve mensagens de commit git no formato Conventional Commits. Use quando o usuário pedir para commitar alterações, escrever uma mensagem de commit ou fazer stage e commit de arquivos.
A versão fraca diz ao Claude que a skill existe, mas nunca a conecta a nada que você diria. A versão forte nomeia as frases reais, então quando você digita "commitar essas alterações", o Claude tem algo para corresponder. Nomeie as palavras que um usuário realmente usaria, mantenha tudo abaixo de 1024 caracteres e não coloque < ou > dentro.
Quando uma skill não dispara, a correção está quase sempre aqui. Adicione as frases que você realmente usa. Se você diz "salvar meu trabalho" mas a descrição menciona apenas "commit", o Claude não tem como ligar os dois. E se o oposto acontecer e a skill disparar quando não deveria, restrinja a descrição ou adicione um gatilho negativo:
1description: Escreve mensagens de commit git no formato Conventional Commits. Use ao commitar alterações. Não use para escrever comentários de código ou documentação.
Há uma maneira rápida de verificar seu trabalho antes de confiar nele. Pergunte diretamente ao Claude:
"Quando você usaria a skill commit-messages?"
O Claude lerá sua descrição de volta com suas próprias palavras. Se isso não estiver alinhado com quando você realmente quer que a skill dispare, você encontrou seu problema, e ele está na descrição, não nas instruções abaixo.
Escreva instruções que o Claude realmente segue
Abaixo do cabeçalho vem o corpo, em Markdown simples. É aqui que seu fluxo de trabalho real vive, e dois hábitos separam instruções que o Claude segue daquelas que ele silenciosamente ignora.
O primeiro é ser específico. O Claude age com instruções concretas e ignora as vagas, então quanto mais exato você for, mais confiavelmente ele se comporta:
1# Ruim2Valide o commit antes de finalizar.34# Bom5Execute `python scripts/validate.py "<mensagem>"`.6Se falhar, corrija estes:7- Tipo inválido: use feat, fix, docs, refactor, test, chore8- Resumo com mais de 60 caracteres: encurte
O segundo é a ordem. O Claude dá peso ao que lê primeiro, então uma regra enterrada no final de um arquivo longo é uma regra que é perdida. Coloque qualquer coisa que não deve ser quebrada no topo, sob um título que a sinalize:
1## Importante2- Linha de resumo com menos de 60 caracteres, sempre3- Apenas presente: "add", não "added"
Há também um limite para o que a linguagem pode garantir. Instruções são interpretadas, o que significa que o Claude as segue bem, mas não de forma idêntica toda vez. Quando uma verificação realmente precisa passar em toda execução, não a descreva em prosa, mova-a para um script e faça as instruções executá-lo. Código faz a mesma coisa toda vez; uma frase não. (É para isso que serve a pasta scripts/, coberta a seguir.)
Uma estrutura que se sustenta na maioria das skills se parece com isto:
1# Nome da Skill23## Importante4Regras críticas que não devem ser perdidas.56## Instruções7Passo a passo, específicas e acionáveis.89## Exemplos10Entrada e saída concretas. O Claude copia exemplos de forma mais confiável do que segue regras.
Mantenha o arquivo enxuto. No momento em que começar a crescer além de suas instruções principais, é hora de mover os detalhes extras para fora, que é exatamente para o que servem as pastas opcionais.
Scripts, referências, assets
Tudo até agora produz uma skill que dá instruções ao Claude. As três pastas opcionais a transformam em uma skill que dá ferramentas ao Claude, e é aqui que uma skill faz coisas que um prompt simples não consegue.
scripts/ contém código que o Claude executa, para qualquer coisa que precise ser exata. Em vez de confiar que o Claude vai avaliar visualmente se um commit está formatado corretamente, você entrega a ele um script que verifica:
1# scripts/validate.py2import sys3msg = sys.argv[1]4types = ("feat", "fix", "docs", "refactor", "test", "chore")56if msg.split(":")[0] not in types:7 print(f"Tipo inválido. Use: {', '.join(types)}")8elif len(msg.split("\n")[0]) > 60:9 print("Resumo muito longo (mais de 60 caracteres)")10else:11 print("OK")
Então você diz ao Claude para usá-lo no SKILL.md:
1Antes de finalizar, execute `python scripts/validate.py "<mensagem>"`2e corrija qualquer coisa que ele sinalizar.
Agora a regra de formato é aplicada por código que roda da mesma forma toda vez, em vez de depender do Claude lembrar de verificar.
references/ contém documentação que carrega apenas quando necessário. Digamos que suas convenções de commit tenham duas páginas de escopos, rodapés e casos extremos. Coloque tudo isso no SKILL.md e ele carrega em todo commit, até mesmo em uma linha. Mova para um arquivo de referência:
1seu-nome-da-skill/2├── SKILL.md3└── references/4 └── conventions.md
E aponte para ele no arquivo principal:
1Para a lista completa de convenções, veja references/conventions.md
O Claude abre esse arquivo apenas quando a tarefa pede. Essa é a razão pela qual as skills permanecem baratas de executar: os detalhes pesados ficam no disco até serem realmente relevantes, em vez de viajarem no contexto toda vez.
assets/ contém arquivos que a skill usa em sua saída, em vez de ler para orientação, como um modelo, um arquivo de configuração ou um logotipo. Uma skill de commit não precisa de nenhum, mas uma skill que gera relatórios pode manter um template.md aqui e preenchê-lo a cada vez, para que todo relatório saia com a mesma estrutura.
Juntas, essas três pastas são a diferença entre uma skill que diz ao Claude como você trabalha e uma que entrega ao Claude as ferramentas exatas para fazer o trabalho do seu jeito.
A única coisa para lembrar
Uma skill não está ensinando ao Claude uma nova habilidade. Ele já sabe como escrever um commit. O que a skill faz é fazê-lo fazer o trabalho do seu jeito, toda vez, sem você precisar explicar novamente.
E quando uma skill não funciona, a causa quase nunca são as instruções que você elaborou. É a descrição. O Claude decide se carrega a skill a partir dessa única linha, antes de ler o trabalho abaixo. Acerte a descrição e tudo abaixo dela finalmente será usado.
Se isso foi útil, vá ao meu perfil e siga. Escrevo sobre tecnologia, IA e sistemas que realmente funcionam.
