🎯 Escolha um caso pequeno e real
A primeira skill de todo mundo deveria ser chata e útil, não ambiciosa. Uma convenção que você repete toda hora e detesta repetir. O exemplo perfeito: o padrão de mensagens de commit do seu time. É concreto, tem regras claras, e você vai notar na hora se funcionou.
✗ Casos ruins de estreia
- ✗"Uma skill que faz deploy completo" — grande demais
- ✗"Uma skill genérica de boas práticas" — vaga, não dispara
- ✗Algo que você não consegue testar em 1 minuto
✓ Casos bons de estreia
- ✓Padrão de commits (Conventional Commits)
- ✓Convenções de nomes de arquivo/branch do projeto
- ✓Tom de voz das respostas em PT-BR
💡 Vamos construir esta
Nosso caso: uma skill conventional-commits que faz o agente escrever mensagens de commit no formato tipo(escopo): descrição sempre que ele for commitar. Pequena, testável, imediatamente útil.
🧬 A anatomia mínima de um SKILL.md
Uma skill é um arquivo só: SKILL.md. Duas partes. Em cima, um frontmatter YAML com dois campos obrigatórios — name e description. Embaixo, o corpo Markdown com as instruções no imperativo. Só isso.
name — o identificador
Curto, minúsculo, com hífens. Vira o nome da pasta e o jeito de referenciar a skill. Ex.: conventional-commits.
description — o gatilho
O campo mais importante. Diz O QUE a skill faz E QUANDO usá-la. É por aqui que o agente decide disparar. Seja explícito e até um pouco "pushy" — o agente tende a subdisparar.
corpo — as instruções
Markdown no imperativo: "Escreva...", "Use...", "Evite...". Explique o porquê em vez de gritar MUSTs em maiúscula. Mantenha enxuto (<500 linhas).
✍️ Escreva o SKILL.md (copie isto)
Aqui está a skill inteira, pronta para colar. Crie o arquivo em skills/conventional-commits/SKILL.md e cole o conteúdo abaixo. Repare: frontmatter entre ---, description que diz o quê e quando, corpo curto e imperativo.
skills/conventional-commits/SKILL.md
--- name: conventional-commits description: Escreve mensagens de commit no padrão Conventional Commits. Use SEMPRE que for criar um commit, sugerir uma mensagem de commit, ou rodar git commit neste repositório. --- # Conventional Commits Ao criar qualquer commit, escreva a mensagem no formato: tipo(escopo): descrição no imperativo Use estes tipos: - feat nova funcionalidade - fix correção de bug - docs só documentação - refactor mudança sem alterar comportamento - test testes - chore build, deps, config Regras: - Descrição em minúscula, no imperativo ("adiciona", não "adicionado"). - Sem ponto final. Máximo ~72 caracteres na primeira linha. - escopo é opcional; use o módulo afetado quando ajudar. Exemplo bom: feat(auth): adiciona login via magic link Exemplo ruim: Adicionei o login.
💡 A description carrega o peso
Note o "Use SEMPRE que..." com três gatilhos concretos (criar commit, sugerir mensagem, rodar git commit). Isso é deliberado: uma description vaga ("ajuda com commits") quase nunca dispara. Diga ao agente exatamente quando agir.
📥 Instale local e veja funcionar
Você não precisa publicar nada para usar. Skills instalam de um caminho local com npx skills add ./.... Siga a timeline: do arquivo criado ao agente respeitando a regra.
Crie a pasta e o arquivo
O caminho importa: a pasta vira o nome da skill.
$ mkdir -p skills/conventional-commits
$ $EDITOR skills/conventional-commits/SKILL.md # cole o conteúdo
Instale a partir do caminho local
$ npx skills add ./skills/conventional-commits
Isso registra a skill no agente (em .claude/skills/ ou equivalente). O name + description passam a viver no contexto.
Dispare com um pedido real
Peça ao agente para commitar. A description bate com o contexto e a skill ativa sozinha.
você: "commita as mudanças do login"
agente: feat(auth): adiciona login via magic link ✓
Confirme que disparou
Se a mensagem saiu no formato tipo(escopo): ... sem você pedir o formato, a skill funcionou. Pronto — você criou e rodou sua primeira skill.
10 minutos, de verdade
Escolher o caso (1 min) → escrever o SKILL.md (4 min) → instalar (1 min) → testar e ajustar (4 min). Nenhum build, nenhum deploy, nenhuma dependência. Só um arquivo de texto.
🚫 Erros comuns de iniciante
Quase todo problema de primeira skill cai em um destes baldes. Compare os dois lados e ajuste antes de culpar o agente.
✗ O que mata uma skill
- ✗description vaga: "ajuda com git" — não dispara nunca
- ✗sem QUANDO usar: descreve o quê mas não o gatilho
- ✗corpo gigante: 800 linhas que o agente não lê inteiro
- ✗frontmatter quebrado: faltou um
---ou indentação errada - ✗tudo em MAIÚSCULA gritada: regras sem explicar o porquê
✓ O que faz funcionar
- ✓description específica: verbo + objeto + 2-3 gatilhos
- ✓"Use quando...": diz exatamente em que situação agir
- ✓corpo enxuto: só o essencial, exemplos curtos
- ✓YAML válido: dois
---, dois espaços de indentação - ✓imperativo + porquê: "Use feat para X porque Y"
💡 Não disparou? É quase sempre a description
Se a skill existe mas o agente a ignora, 9 em 10 vezes o problema está na description fraca, não no corpo. Adicione os gatilhos concretos ("ao commitar", "ao rodar git commit") e teste de novo. Esse ciclo de afinar a description é o coração da Trilha 4.
🌱 Evolua a partir do mínimo
Você tem uma skill funcionando. Agora resista à vontade de inflar. A evolução saudável é incremental: ajuste a description com base no que falhou, adicione exemplos só quando precisar, e extraia recursos pesados para arquivos separados (progressive disclosure) só quando o corpo crescer.
Afinar a description
Disparou demais (em conversas que não eram sobre commit)? Restrinja. Disparou de menos? Adicione gatilhos. A description é o que você mais mexe.
Adicionar exemplos sob demanda
Errou um caso específico? Acrescente um par "bom/ruim" para aquele caso. Não tente prever tudo de antemão — deixe os erros guiarem.
Versionar com o repo
SKILL.md é texto: comite junto com o projeto. O time inteiro passa a herdar a convenção, e a skill evolui no histórico do git como qualquer arquivo.
o ciclo, em uma linha:
escrever mínimo → instalar → testar → ajustar description → repetir
💡 Pequeno e vivo > grande e morto
Uma skill de 30 linhas que você usa todo dia e ajusta toda semana vale mais que uma de 500 linhas escrita "completa" e nunca testada. Comece mínimo, deixe o uso real podar e crescer.
✅ Resumo do Módulo
Próximo:
1.5 — 🚀 Dicas Avançadas: Lendo o Ecossistema como um Pro. Como interpretar install count, achar nichos vazios e decidir quando NÃO instalar.