Como Criar suas Proprias Skills para Claude Code — Tutorial Completo

Skills sao o recurso mais poderoso do Claude Code -- e tambem o menos explorado. Enquanto a maioria dos usuarios fica nos prompts avulsos, quem domina skills transforma o Claude Code em um assistente personalizado que conhece seus padroes, segue suas regras e entrega resultados consistentes.

Neste tutorial, voce vai aprender a criar uma skill do zero. Nao precisa saber programar. Skills sao escritas em Markdown, com instrucoes em linguagem natural. Se voce sabe explicar uma tarefa por escrito, voce sabe criar uma skill.

Ao final, voce tera uma skill funcional instalada e pronta para usar. Vamos construir juntos uma skill de code review automatizado como exemplo pratico.

1. O que sao skills no Claude Code

Uma skill e um conjunto de instrucoes persistentes que o Claude Code segue quando voce a invoca. Diferente de um prompt que voce digita e descarta, uma skill fica salva no seu projeto e pode ser reutilizada infinitas vezes.

Na pratica, funciona assim:

1. Voce cria um arquivo Markdown com instrucoes detalhadas
2. Salva no diretorio correto (.claude/commands/)
3. Invoca com /nome-da-skill no Claude Code
4. O Claude segue as instrucoes da skill com precisao

Skills resolvem tres problemas fundamentais dos prompts avulsos:

• Inconsistencia: prompts geram outputs diferentes a cada execucao. Skills padronizam o formato e a qualidade
• Esquecimento: voce nao precisa lembrar todos os detalhes do prompt toda vez. Esta tudo documentado na skill
• Reusabilidade: escreva uma vez, use para sempre. Compartilhe com sua equipe ou entre projetos

2. Estrutura de pastas e arquivos

A estrutura de uma skill no Claude Code e simples:

seu-projeto/
  .claude/
    commands/
      code-review.md        # A skill principal
      deploy-checklist.md   # Outra skill
      seo-audit.md          # Mais uma skill

Cada arquivo .md dentro de .claude/commands/ se torna automaticamente um slash command disponivel no Claude Code. O nome do arquivo (sem a extensao) e o nome do comando.

Arquivo	Comando
code-review.md	/code-review
deploy-checklist.md	/deploy-checklist
seo-audit.md	/seo-audit

Para skills mais complexas com evals e referencias, a estrutura pode ser expandida:

seu-projeto/
  .claude/
    commands/
      code-review.md
    evals/
      code-review/
        test-1.md
        test-2.md
    references/
      coding-standards.md
      style-guide.md

3. Anatomia de uma skill: o arquivo .md

O arquivo Markdown de uma skill tem uma estrutura simples mas poderosa. Vamos dissecar cada parte:

# Code Review Automatizado

## Contexto
Voce e um code reviewer senior com 10+ anos de experiencia.
Seu objetivo e revisar o codigo do projeto focando em qualidade,
seguranca, performance e boas praticas.

## Instrucoes
1. Analise todos os arquivos modificados recentemente (ultimos commits)
2. Para cada arquivo, verifique:
   - Bugs potenciais ou logica incorreta
   - Vulnerabilidades de seguranca (SQL injection, XSS, etc)
   - Problemas de performance (loops desnecessarios, queries N+1)
   - Codigo duplicado que poderia ser abstraido
   - Nomes de variaveis/funcoes pouco claros
   - Falta de tratamento de erros
   - Testes ausentes para logica critica

## Formato de Saida
Para cada arquivo revisado, gere:

### [nome-do-arquivo]
**Severidade:** CRITICO | ALERTA | INFO
**Problema:** [descricao clara do problema]
**Linha:** [numero da linha]
**Sugestao:** [como corrigir, com codigo exemplo]

## Restricoes
- NAO sugira mudancas apenas cosmeticas (formatacao, espacos)
- Foque em problemas que afetam funcionalidade, seguranca ou performance
- Limite a 10 issues por arquivo para nao sobrecarregar
- Se nao encontrar problemas, diga "Codigo aprovado" com uma nota breve

Elementos-chave de uma boa skill

• Contexto: define o "papel" que o Claude deve assumir. Isso influencia drasticamente a qualidade do output
• Instrucoes: o passo a passo do que fazer. Quanto mais especifico, melhor
• Formato de saida: define exatamente como o resultado deve ser apresentado. Garante consistencia entre execucoes
• Restricoes: limites e regras negativas (o que NAO fazer). Evita que o Claude divague ou gere ruido

4. Exemplo passo a passo: criando uma skill de code review

Vamos criar a skill completa, do zero ate a primeira execucao.

Passo 1: Criar a estrutura de pastas

Passo 2: Criar o arquivo da skill

Passo 3: Escrever as instrucoes

Abra o arquivo .claude/commands/review.md e escreva:

# Code Review Focado

## Contexto
Voce e um reviewer senior. Revise o codigo com foco em bugs,
seguranca e performance. Seja direto e acionavel.

## O que revisar
Analise os arquivos modificados nos ultimos 3 commits.

Para cada arquivo, verifique:
1. Bugs logicos ou edge cases nao tratados
2. Vulnerabilidades de seguranca
3. Problemas de performance
4. Tratamento de erros ausente
5. Testes que deveriam existir mas nao existem

## Formato de saida
Use este formato para cada issue encontrada:

**[ARQUIVO]** linha [N]
- Severidade: CRITICO / ALERTA / INFO
- Problema: [descricao em 1-2 frases]
- Fix sugerido: [codigo ou descricao da correcao]

## Resumo final
No final, gere um resumo:
- Total de issues: X (Y criticas, Z alertas, W info)
- Nota geral: APROVADO / APROVADO COM RESSALVAS / REPROVADO
- Acao recomendada: [o que fazer primeiro]

## Regras
- Maximo 10 issues por arquivo
- Ignore problemas de formatacao/estilo
- Se o codigo estiver bom, diga "Aprovado" sem inventar problemas

Passo 4: Testar a skill

Pronto. Sua skill esta funcionando. Toda vez que voce digitar /review, o Claude Code vai seguir exatamente essas instrucoes.

5. Pasta evals: testando sua skill

A pasta evals/ permite que voce teste sua skill de forma sistematica. Cada eval e um cenario de teste que verifica se a skill produz o resultado esperado.

.claude/
  evals/
    review/
      test-sql-injection.md
      test-clean-code.md
      test-performance.md

Exemplo de eval

# Test: SQL Injection Detection

## Input
Dado um arquivo com este codigo:

```javascript
app.get('/users', (req, res) => {
  const name = req.query.name;
  db.query(`SELECT * FROM users WHERE name = '${name}'`);
});
```

## Resultado esperado
A skill deve:
1. Identificar SQL injection como CRITICO
2. Sugerir parametros preparados como fix
3. Apontar a linha correta

Evals servem para duas coisas: validar que a skill funciona como esperado e documentar o comportamento desejado para quando voce precisar atualizar as instrucoes.

6. Pasta references: contexto adicional

A pasta references/ armazena documentos que a skill pode consultar durante a execucao. Isso permite que skills tenham acesso a contexto especializado sem sobrecarregar o arquivo principal.

.claude/
  references/
    coding-standards.md     # Padroes de codigo da sua empresa
    security-checklist.md   # Checklist de seguranca
    api-conventions.md      # Convencoes de API

Na skill, voce referencia esses arquivos:

# Code Review

## Contexto
Revise o codigo seguindo os padroes documentados em:
- .claude/references/coding-standards.md
- .claude/references/security-checklist.md

Consulte esses arquivos antes de iniciar a revisao.

O Claude Code le os arquivos referenciados e usa como contexto adicional. Isso e especialmente util para regras especificas da sua empresa ou projeto que nao cabem no arquivo da skill.

7. Onde salvar: projeto vs global

Existem dois locais para salvar skills:

Local	Caminho	Escopo	Quando usar
Projeto	.claude/commands/	Disponivel so neste projeto	Skills especificas do projeto (review, deploy, etc)
Global	~/.claude/commands/	Disponivel em todos os projetos	Skills genericas que voce usa em qualquer projeto

Recomendacao

• Skills de projeto: code review (cada projeto tem padroes diferentes), deploy checklist, testes especificos
• Skills globais: gerador de README, criacao de .gitignore, analise de dependencias, formatacao de commit messages

Se uma skill de projeto funciona tao bem que voce quer usar em tudo, copie para o diretorio global. Simples.

8. Boas praticas para skills profissionais

Depois de criar dezenas de skills, esses sao os padroes que diferenciam skills amadoras de profissionais:

1. Seja especifico no contexto

Ruim: "Voce e um desenvolvedor". Bom: "Voce e um desenvolvedor senior de Node.js com experiencia em APIs REST, familiarizado com Express, Prisma e PostgreSQL. Voce prioriza seguranca sobre conveniencia."

2. Defina o formato de saida explicitamente

Nao deixe o Claude decidir como formatar. Se voce quer uma tabela, especifique as colunas. Se quer bullets, especifique o padrao. Consistencia de formato e essencial para skills que voce vai usar repetidamente.

3. Inclua restricoes (o que NAO fazer)

Skills sem restricoes tendem a produzir output verboso e com ruido. Adicione regras negativas: "Nao explique conceitos basicos", "Nao sugira mudancas cosmeticas", "Limite a 10 items no output".

4. Use exemplos de input/output

Se possivel, inclua na skill um exemplo de como o output deve ser. Isso reduz ambiguidade drasticamente:

## Exemplo de output esperado

**src/auth.js** linha 23
- Severidade: CRITICO
- Problema: Token JWT sem expiracao permite acesso indefinido
- Fix: Adicionar `expiresIn: '24h'` na chamada jwt.sign()

5. Itere e refine

Sua primeira versao nao vai ser perfeita. Use a skill 5-10 vezes, observe onde o output diverge do esperado e ajuste as instrucoes. As melhores skills passam por varias iteracoes.

6. Documente parametros opcionais

Skills podem aceitar argumentos. Documente isso no inicio do arquivo:

# Code Review

## Uso
/review              - revisa ultimos 3 commits
/review --full       - revisa todos os arquivos do projeto
/review src/api/     - revisa apenas o diretorio especificado