Padrões e boas práticas para skills
Padrões comuns, antipadrões e hábitos de quem cria skills excelentes
⏱ Estim. ~8 min
01 · Ler
Agora que você sabe como skills funcionam, vamos ver os padrões que os devs realmente usam no dia a dia.
As skills mais populares caem em algumas categorias: - Estilo de código — aplicam convenções de nomes, regras de formatação, padrões de estrutura - Code review — checklists consistentes para revisar PRs e mudanças de código - Mensagens de commit — aplicam formatos como Conventional Commits - Testes — alinham com o framework e os padrões de teste do seu projeto - Documentação — padronizam como documentação, comentários e README são escritos
Cada padrão segue a mesma estrutura: regras claras, exemplos específicos e formato de saída explícito. Vamos ver os dois mais úteis.
Pontos-chave
- Skills de estilo de código aplicam convenções de nomes, formatação e estrutura
- Skills de review oferecem checklists consistentes de revisão de código
- Skills de mensagem de commit aplicam formatos como Conventional Commits
- Skills de teste se alinham com os padrões de teste que seu projeto já usa
- Skills de documentação padronizam como a documentação é escrita
02 · Exemplo de código
Abaixo está uma skill que faz todas as mensagens de commit usarem o formato Conventional Commits.
commit-style/SKILL.md
---
name: Commit Message Style
description: Enforces Conventional Commits format
instructions: Use when creating git commits
---
## Format
All commits must follow Conventional Commits:
```
<type>(<scope>): <description>
[optional body]
```
## Types
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation only
- `refactor`: Code change that neither fixes nor adds
- `test`: Adding or updating tests
- `chore`: Maintenance (dependencies, CI, build)
## Rules
- Description must be lowercase, no period at the end
- Scope is optional but encouraged
- Body should explain WHY, not WHAT (the diff shows what)
- Max 72 characters for the first line
## Examples
Good: `feat(auth): add password reset flow`
Good: `fix(api): handle null response from payment gateway`
Bad: `Fixed stuff`
Bad: `Update code`
Repare como tudo é explícito — formato exato, tipos enumerados, limite de caracteres, exemplos bons e ruins. Quanto mais explícitas as suas regras, mais consistentes ficam os commits do Claude. Instruções vagas como "escreva boas mensagens de commit" não funcionam.
03 · Exemplo de código
Abaixo está uma skill que diz ao Claude para seguir as convenções de teste que seu projeto já usa.
test-writer/SKILL.md
---
name: Test Writer
description: Writes tests matching project conventions
instructions: Use when writing or updating tests
---
## Conventions
- Use `describe` / `it` blocks (not `test`)
- Test file goes next to source: `Foo.ts` → `Foo.test.ts`
- Use `vi.fn()` for mocks (Vitest, not Jest)
- Arrange-Act-Assert pattern in every test
## What To Test
- Happy path first
- Error cases and edge cases
- Boundary values (0, 1, -1, empty string, null)
- Never test implementation details — test behavior
## Naming
`it('should return 404 when user not found')`
Not: `it('test user')`
Essa skill referencia o framework de teste específico do projeto (Vitest) e os padrões (describe/it, vi.fn). Uma instrução genérica como "escreva bons testes" não serve — o Claude já está tentando escrever bons testes. Essa skill conta para ele quais são as suas convenções específicas.
04 · Quiz
Lembre: skills devem adicionar regras que o Claude sozinho não conheceria. Qual das instruções abaixo é específica o suficiente para realmente mudar o comportamento do Claude?
- Seja um assistente prestativo que escreve um bom código
- Ao escrever endpoints de API, devolva JSON com chaves em camelCase, use URLs em kebab-case e códigos de erro do nosso arquivo error-codes.ts
- Use sempre boas práticas ao escrever código
- Escreva código como um engenheiro sênior
05 · Classificar arrastando
Pense no que faz mais diferença na qualidade de uma skill. Uma skill vaga sem exemplos rende muito menos do que uma específica — ordene estas práticas do maior para o menor impacto.
(Esta seção é interativa — ative o JavaScript para usar.)
06 · Ler
Algumas skills, em vez de ajudar, pioram o Claude. Veja o que evitar: Vago demais: "Escreva código bom e limpo." O Claude já está tentando. Sua skill deve adicionar regras específicas que o Claude sozinho não conheceria.
Longo demais: Uma skill de 500 linhas, com regras para todo cenário possível, sobrecarrega o contexto do Claude. Mantenha a skill focada em um único fluxo. Várias skills focadas batem uma gigante.
Duplicar comportamento padrão: O Claude já sabe formatar código, escrever markdown, usar git. Não gaste espaço da skill com coisas que ele já faz bem por padrão.
Regras contraditórias: "Comente sempre" + "mantenha o código mínimo" gera confusão. Antes de testar, confira se suas regras não brigam entre si.
Pontos-chave
- Não escreva skills vagas — ou seja explícito ou nem escreva
- Não escreva skills gigantes — uma skill, um fluxo focado
- Não duplique o que o Claude já faz bem por padrão
- Verifique se a skill não tem regras que se contradizem
07 · Ler
Agora você tem um superpoder que a maioria dos usuários do Claude Code não tem: a capacidade de ensinar ao Claude exatamente como você trabalha.
Todo time tem suas convenções. Todo dev tem suas preferências. Skills transformam essas regras implícitas em instruções permanentes, compartilháveis e versionadas.
Comece pequeno. Pegue a única coisa que você mais repete para o Claude e vire skill. Teste, refine, faça commit. Depois adicione outra. Com o tempo, sua coleção de skills vira um multiplicador de força — cada skill que você escreve faz o Claude ficar melhor no seu trabalho específico.
A diferença entre um assistente de IA genérico e um fluxo de IA personalizado? Skills.
Pontos-chave
- Comece pela skill da instrução que você mais repete
- Itere: teste, refine, faça commit
- Compartilhe skills de projeto via git para o time inteiro ganhar
- Acumule uma coleção ao longo do tempo — cada skill deixa o Claude mais esperto sobre o seu trabalho
- Skills são a diferença entre um assistente de IA genérico e um fluxo de IA personalizado
08 · Quiz
Você escreveu uma skill que diz "escreva código bom e limpo". Depois de testar, a saída do Claude parece igual. Por quê?
- O arquivo SKILL.md tem um erro de sintaxe
- Skills só funcionam com o modelo Opus
- A instrução é vaga demais — o Claude já está tentando escrever código bom
- É preciso reiniciar o Claude Code depois de adicionar uma skill
09 · Preencher
Uma skill de 500 linhas que cobre todos os cenários possíveis é um antipadrão. Você deve escrever várias skills _____, cada uma cobrindo um único fluxo.
Outras lições deste capítulo
⚠ A experiência interativa completa precisa de JavaScript. Ative-o e recarregue a página.
※ Este é um projeto educacional independente — não é um produto oficial da Anthropic. Claude™ é uma marca registrada da Anthropic, PBC.