Você usa o Claude há uma semana e continua digitando a mesma coisa. Toda vez que faz um commit de código, você cola as mesmas três regras sobre o formato do commit. Toda vez que escreve um documento, reexplica seu estilo. O Claude faz bem, mas 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 se aplique em toda sessão sem você precisar pedir.
Veja 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 puxa as instruções completas apenas quando sua solicitação corresponde. Esse é o mecanismo inteiro.
Neste guia, construímos 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 etapa.
O que você terá no final
No seu núcleo, uma skill é uma pasta com um arquivo obrigatório, SKILL.md. Três pastas opcionais aparecem conforme a skill cresce:
1your-skill-name/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 ele 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 dela.
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/your-skill-name
No Windows, abra o PowerShell e execute:
1New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills\your-skill-name"
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 underscores: 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 você escrever uma linha do arquivo. Ambas parecem puláveis e nenhuma é.
Primeiro, decida exatamente quando a skill deve ser ativada. 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"
- "stages e commitar"
Isso não é trabalho inútil. 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 ser acionada.
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 funciona, mas falhou em seu trabalho real. Vale a pena observar junto com isso: se ela termina a tarefa sem você corrigi-la no meio do caminho, e se dá o mesmo formato de resultado em sessões separadas.
A descrição é o que faz ou quebra tudo
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 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 falham.
Uma descrição forte responde a duas perguntas em uma frase: o que a skill faz, e quando o Claude deve recorrer a ela. Essa segunda metade é a que as pessoas deixam de fora.
Aqui está a diferença:
1# fraco - 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 ser acionada5description: 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 stage e commitar 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 dela.
Quando uma skill não dispara, o conserto está quase sempre aqui. Adicione as frases que você realmente usa. Se você diz "salvar meu trabalho" mas a descrição só menciona "commit", o Claude não tem como ligar as duas coisas. 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 em suas próprias palavras. Se isso não estiver alinhado com quando você realmente quer que a skill seja acionada, você encontrou seu problema, e 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 puro. É aqui que seu fluxo de trabalho real vive, e dois hábitos separam as instruções que o Claude segue daquelas que ele silenciosamente ignora.
O primeiro é ser específico. O Claude age sobre 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
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 tempo presente: "adiciona", não "adicionou"
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 identicamente toda vez. Quando uma verificação precisa realmente passar em toda execução, não a descreva em prosa, mova-a para um script e faça as instruções executá-lo. O código faz a mesma coisa toda vez; uma frase, não. (É para isso que serve a pasta scripts/, abordada a seguir.)
Uma estrutura que se sustenta na maioria das skills se parece com isso:
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 para 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>"` e corrija qualquer coisa que ele sinalizar.
Agora a regra de formato é aplicada por código que funciona 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 ocupem duas páginas de escopos, rodapés e casos extremos. Coloque tudo isso no SKILL.md e ele carrega em cada commit, mesmo um de uma linha. Mova para um arquivo de referência:
1your-skill-name/2├── SKILL.md3└── references/4 └── conventions.md
E aponte para ele a partir do arquivo principal:
1Para a lista completa de convenções, veja references/conventions.md
O Claude abre esse arquivo apenas quando a tarefa o exige. Esta é a razão principal 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.
Juntos, esses 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 em que você trabalhou. É a descrição. O Claude decide se carrega a skill a partir dessa única linha, antes de ler o trabalho abaixo. Acertar a descrição e tudo abaixo dela finalmente é usado.
Se isso foi útil, vá ao meu perfil e siga-me. Eu escrevo sobre tecnologia, IA e sistemas que realmente funcionam.
