Construa sua primeira skill
Planeje, escreva e organize um arquivo SKILL.md
⏱ Estim. ~7 min
01 · Ler
Antes de escrever uma linha, você precisa identificar um fluxo repetível.
Pense nas coisas que você fica falando para o Claude Code: "Use componentes funcionais." "Escreva testes primeiro." "Use conventional commits." "Não comente código óbvio."
Cada uma dessas é uma candidata a skill. As melhores skills capturam fluxos que você segue toda vez — não pedidos pontuais.
Pergunte a si mesmo: "Qual é a instrução que eu digito para o Claude Code pelo menos uma vez por semana?" Essa é a sua primeira skill.
Pontos-chave
- Boas skills capturam fluxos repetíveis, não tarefas pontuais
- Pense nas instruções que você digita em toda sessão do Claude Code
- Comece por um fluxo concreto, não tente fazer tudo de uma vez
- Skills devem tomar posição — regras claras, não sugestões vagas
02 · Exemplo de código
Todo SKILL.md começa com um frontmatter YAML entre ---. Abaixo estão os três campos principais.
Frontmatter YAML
---
name: Code Reviewer
description: Reviews code for bugs, style, and best practices
instructions: Use this skill when reviewing pull requests or code changes
---
name é o nome que aparece na lista de /skill. description diz ao Claude (e a você) o que essa skill faz. instructions dá uma dica ao Claude sobre quando ativar essa skill. Os três são opcionais, mas é fortemente recomendado preencher todos.
03 · Quiz
Você acabou de ver os três campos padrão do frontmatter YAML. Qual destes não é um deles?
- name
- description
- language
- instructions
04 · Passo a passo
Vamos construir uma skill real passo a passo. Vamos criar uma skill "Code Reviewer" que aplica o padrão de revisão do seu time.
1. Crie a pasta da skill
Crie a estrutura de diretórios dentro do seu projeto. Rode: mkdir -p .claude/skills/code-reviewer. A flag -p cria os diretórios pais se eles não existirem. Isso coloca a skill dentro do seu projeto, pronta para commit no git.
2. Escreva o frontmatter YAML
Abra .claude/skills/code-reviewer/SKILL.md e adicione o bloco de metadados. Comece com uma linha ---, adicione os campos name, description e instructions e finalize com outra linha ---.
3. Adicione o corpo das instruções
Abaixo do --- final, escreva suas regras de revisão em linguagem natural. Use cabeçalhos markdown para organizar seções e listas para regras específicas. Seja explícito — "verifique entrada de usuário em busca de SQL injection" é muito melhor que "revise o código".
4. Teste com /skill
Em uma conversa do Claude Code, digite /skill e veja sua nova skill aparecer na lista. Selecione para ativar. Agora peça ao Claude que revise um trecho de código — ele deve seguir suas regras. Se não seguir, refine e tente de novo.
05 · Exemplo de código
Abaixo está a skill "Code Reviewer" completa — um SKILL.md inteiro, pronto para produção.
code-reviewer/SKILL.md
---
name: Code Reviewer
description: Reviews code changes for bugs, security, and style
instructions: Use when asked to review code, PRs, or diffs
---
## Review Checklist
When reviewing code, check for:
- **Security**: SQL injection, XSS, command injection, hardcoded secrets
- **Error handling**: Are errors caught? Are they logged? Do they fail gracefully?
- **Edge cases**: What happens with empty input? Null values? Very large data?
- **Naming**: Are variables and functions named clearly?
- **Tests**: Are there tests for the new code? Do existing tests still pass?
## Output Format
Structure your review as:
1. **Summary** — one sentence overview
2. **Issues** — bullet list, severity (high/medium/low)
3. **Suggestions** — optional improvements (not blockers)
O corpo usa markdown padrão — cabeçalhos, negrito, listas. O Claude trata isso como instruções a seguir. A checklist de revisão diz ao Claude o que olhar, e o formato de saída garante que toda revisão seja consistente e estruturada.
06 · Preencher
O frontmatter YAML em um arquivo SKILL.md é cercado por duas linhas de _____
07 · Classificar arrastando
Um arquivo SKILL.md tem uma estrutura específica. Pense no que o Claude lê primeiro quando carrega uma skill e ordene as partes de cima para baixo.
(Esta seção é interativa — ative o JavaScript para usar.)
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.