Claude Code Skills — Como Criar Comandos Personalizados

Você já se pegou digitando a mesma instrução pela terceira vez no Claude Code? Algo como “refatore este componente seguindo o padrão do projeto, use TypeScript strict, adicione testes unitários e documente com JSDoc”? Esse tipo de repetição consome tempo e energia mental que poderiam estar direcionados ao que realmente importa: resolver problemas complexos. É exatamente aqui que entram as skills — comandos personalizados que encapsulam instruções recorrentes em atalhos reutilizáveis.

Em vez de reescrever prompts longos toda vez, você cria uma skill uma única vez e a invoca com um simples slash command. O resultado é uma rotina de desenvolvimento mais fluida, consistente e rápida.

O que são skills no Claude Code

Skills são arquivos Markdown que funcionam como comandos personalizados dentro do Claude Code. Cada skill contém um conjunto de instruções — escritas em linguagem natural — que o Claude executa quando você a invoca através de um slash command.

Pense nelas como macros inteligentes. Diferente de scripts tradicionais que executam passos rígidos, as skills aproveitam a capacidade de interpretação do Claude para adaptar as instruções ao contexto do código em que você está trabalhando.

Como as skills funcionam na prática

Quando você digita um comando como /project:refactor no terminal do Claude Code, ele:

1. Localiza o arquivo Markdown correspondente à skill
2. Lê as instruções contidas no arquivo
3. Combina essas instruções com o contexto atual do seu projeto
4. Executa a tarefa seguindo as diretrizes que você definiu

A mágica está no fato de que as instruções são interpretadas, não apenas executadas literalmente. Se sua skill diz “adicione tratamento de erros seguindo o padrão do projeto”, o Claude analisa os padrões existentes no código e aplica algo coerente.

Diferença entre skills de projeto e skills globais

Como criar sua primeira skill personalizada

Vamos sair da teoria e colocar a mão no código. Criar uma skill leva menos de dois minutos.

Passo 1: Crie a estrutura de diretórios

Para uma skill de projeto:

mkdir -p .claude/commands

Para uma skill global:

mkdir -p ~/.claude/commands

Passo 2: Crie o arquivo Markdown

Cada skill é um arquivo .md. O nome do arquivo se torna o nome do comando.

touch .claude/commands/refactor.md

Isso criará o comando /project:refactor.

Passo 3: Escreva as instruções

Abra o arquivo e escreva em linguagem natural o que o Claude deve fazer:

Analise o arquivo ou trecho de código selecionado e execute a refatoração seguindo estas regras:

1. Mantenha a interface pública inalterada (mesmos inputs e outputs)
2. Extraia funções com mais de 20 linhas em funções menores
3. Substitua magic numbers por constantes nomeadas
4. Adicione tipagem TypeScript strict onde estiver faltando
5. Preserve todos os testes existentes funcionando

Após a refatoração, liste as mudanças realizadas em formato de bullet points.

Passo 4: Use a skill

No terminal do Claude Code, basta digitar:

/project:refactor

O Claude carrega as instruções e as aplica ao contexto atual.

Organizando skills por projeto e globalmente

À medida que você cria mais skills, a organização se torna fundamental para não perder o controle.

Estrutura recomendada para projetos

.claude/
└── commands/
    ├── refactor.md
    ├── test.md
    ├── review.md
    ├── docs.md
    └── deploy-check.md

Mantenha nomes curtos e descritivos. Você vai digitá-los com frequência, então test é melhor que criar-testes-unitarios-completos.

Estrutura recomendada para skills globais

~/.claude/
└── commands/
    ├── explain.md
    ├── commit-msg.md
    ├── debug.md
    └── optimize.md

Quando usar cada tipo

Use skills de projeto quando: - As instruções dependem de convenções específicas do repositório (padrões de código, estrutura de pastas, stack tecnológica) - Outros membros do time podem se beneficiar do mesmo comando - A skill referencia arquivos ou configurações do projeto

Use skills globais quando: - O comando é genérico o suficiente para funcionar em qualquer projeto - É um fluxo pessoal que não faz sentido compartilhar - Envolve preferências individuais de formatação ou estilo

Exemplos práticos de skills úteis para devs

Aqui estão skills que resolvem problemas reais do dia a dia. Copie, adapte e use.

Skill: Gerador de testes

Arquivo: .claude/commands/test.md

Crie testes unitários para o código indicado em $ARGUMENTS.

Regras:
- Use o framework de testes já configurado no projeto
- Cubra o caminho feliz e pelo menos 2 cenários de erro
- Use nomes descritivos no padrão "should [comportamento] when [condição]"
- Adicione comentários explicando o que cada bloco de teste valida
- Não mocke dependências desnecessariamente

Uso: /project:test src/services/auth.ts

Skill: Mensagem de commit semântica

Arquivo: ~/.claude/commands/commit-msg.md

Analise as mudanças staged no Git (use git diff --staged) e gere uma mensagem de commit seguindo Conventional Commits:

- Formato: tipo(escopo): descrição curta
- Tipos permitidos: feat, fix, refactor, docs, test, chore, style, perf
- Descrição em português, imperativo, máximo 72 caracteres
- Se necessário, adicione um body explicando o "porquê" da mudança

Uso: /user:commit-msg

Skill: Code review automatizado

Arquivo: .claude/commands/review.md

Faça uma revisão de código do arquivo $ARGUMENTS verificando:

1. **Segurança**: inputs não sanitizados, SQL injection, XSS, secrets expostos
2. **Performance**: loops desnecessários, queries N+1, memory leaks potenciais
3. **Manutenibilidade**: funções muito longas, acoplamento excessivo, código duplicado
4. **Tipagem**: tipos any, assertions desnecessárias, generics que poderiam ser mais específicos

Classifique cada achado como: 🔴 Crítico | 🟡 Sugestão | 🟢 Nitpick

Apresente o resultado em formato de tabela.

Uso: /project:review src/controllers/payment.ts

Skill: Documentação de API

Arquivo: .claude/commands/docs.md

Gere documentação para o endpoint ou função em $ARGUMENTS.

Inclua:
- Descrição do propósito
- Parâmetros com tipos e descrição
- Retorno esperado com exemplo JSON
- Possíveis códigos de erro
- Exemplo de uso com curl ou fetch

Formato: Markdown compatível com ferramentas de documentação (Swagger/OpenAPI quando aplicável).

Uso: /project:docs src/routes/users.ts

Dicas avançadas para skills mais poderosas

Combine skills com o arquivo CLAUDE.md

O arquivo CLAUDE.md na raiz do projeto define o contexto geral que o Claude carrega em toda interação. Se você documentar convenções do projeto lá (stack, padrões de código, estrutura de pastas), suas skills automaticamente herdam esse contexto. A skill não precisa repetir informações que já estão no CLAUDE.md.

Itere sobre suas skills

Skills não precisam ficar perfeitas na primeira versão. Use, observe o resultado, ajuste as instruções. Depois de algumas iterações, você terá comandos que produzem exatamente o que precisa com consistência.

Compartilhe com o time

Um dos maiores ganhos das skills de projeto é a padronização. Quando todos no time usam /project:review com os mesmos critérios, a qualidade do código converge para um padrão comum sem depender de documentação que ninguém lê.

O próximo passo na sua produtividade

Skills transformam o Claude Code de uma ferramenta de perguntas e respostas em um assistente que conhece suas rotinas. Comece com duas ou três skills que resolvam suas repetições mais frequentes — geração de testes, mensagens de commit, code review. À medida que sentir confiança, expanda o repertório e compartilhe com seu time. O investimento de dois minutos para criar cada skill se paga na primeira vez que você a usa.

Artigos relacionados

• Claude Code – Guia Completo para Criar Projetos com IA
• Comandos Essenciais do Claude Code para Produtividade
• Claude Code MCPs — Integre Ferramentas Externas

Bruno Bracaioli

Empreendedor e Desenvolvedor

Bruno Bracaioli é especialista em arquitetura de software, ciência de dados e cybersecurity. Além disso, investe em criptomoedas e em investimentos tradicionais como CDBs, Ações, Tesouro e outros. É influenciador digital no instagram (@brunobracaioli) e no Youtube (/brunobracaioli). Contato por: bruno@bracaiolitech.com ou pelo bruno@b2tech.com