Por que criar o seu próprio /comando?
Slash commands são o investimento de menor fricção e maior retorno no Claude Code. Cinco minutos para escrever um arquivo markdown economizam 30 segundos por invocação — e quando você invoca dez vezes por dia, todo dia, a conta fecha na primeira semana.
Este artigo é um tutorial passo a passo. Vou assumir que você já sabe a diferença entre slash commands e skills — se não, passe antes por Slash Commands e Skills: personalizando seu fluxo no Claude Code. Aqui o foco é prático: criar, testar, debugar e compartilhar seu primeiro comando.
Onde os arquivos vivem
Slash commands são arquivos markdown em uma de três pastas:
| Escopo | Caminho | Quando usar |
|---|---|---|
| Projeto | .claude/commands/ | Comandos versionados, compartilhados com o time |
| Pessoal | ~/.claude/commands/ | Seus próprios atalhos, em todos os projetos |
| Plugin | ~/.claude/plugins/<nome>/commands/ | Distribuídos via plugin |
O nome do arquivo vira o nome do comando. .claude/commands/deploy.md fica disponível como /deploy. Você pode aninhar pastas para criar namespaces: .claude/commands/git/review.md vira /git:review. Namespaces ajudam a organizar quando você tem mais de 10 comandos — o autocomplete agrupa por prefixo.
Se é a primeira vez criando algo em .claude/, a pasta provavelmente não existe. Crie manualmente com mkdir -p .claude/commands e comece pelo primeiro arquivo.
O arquivo mínimo viável
Um slash command não precisa nem de frontmatter. O arquivo markdown mais simples já funciona:
Rode os testes com `npm test` e me mostre quais falharam. Não tente arrumar ainda — só relate.
Salve isso em .claude/commands/test-report.md e digite /test-report no prompt. O Claude Code injeta esse conteúdo como se você tivesse colado manualmente. Pronto, já é um slash command.
A partir daí, dá para enriquecer. Com frontmatter você ganha três coisas úteis:
---
description: Roda os testes e reporta falhas sem tentar arrumar
argument-hint: "[padrão opcional ex: auth.test]"
allowed-tools: Bash(npm test*), Read, Grep
---
Rode `npm test ${ARGUMENTS:-}` e reporte apenas quais testes falharam. Use Read e Grep para mostrar as linhas relevantes. Não edite nada.
Os três campos importantes:
description— aparece no autocomplete quando você digita/. Escreva curto e imperativo.argument-hint— a dica mostrada ao lado do comando enquanto você digita. Não é obrigatório, mas ajuda a lembrar o que o comando aceita.allowed-tools— restringe quais ferramentas o agente pode usar enquanto o comando está ativo. Útil para comandos "seguros" que não deveriam editar arquivos.
Argumentos: como passar contexto
Quando você digita /test-report auth, o texto auth fica disponível como argumento. Existem duas formas de referenciar:
$ARGUMENTS— toda a string depois do nome do comando.$1,$2,$3— argumentos posicionais separados por espaço.
Use $ARGUMENTS quando o input é texto livre (uma mensagem, uma query). Use $1, $2 quando você espera posições fixas (um arquivo e uma função, por exemplo). A sintaxe ${ARGUMENTS:-default} aceita fallback quando nada é passado — útil para comandos que rodam com ou sem filtro.
Exemplo 1: um /commit de verdade
Um dos primeiros comandos que vale escrever é um /commit padronizado. Salve isto em .claude/commands/commit.md:
---
description: Analisa o diff staged e cria um commit conventional
argument-hint: "[escopo opcional]"
allowed-tools: Bash(git *)
---
Rode `git status` e `git diff --cached` em paralelo para entender o que está staged.
Analise as mudanças e redija uma mensagem de commit seguindo Conventional Commits:
- Tipo: feat, fix, refactor, docs, test, chore, perf
- Escopo: ${1:-detecte automaticamente}
- Descrição: imperativo, 1 linha, máximo 72 caracteres
Se houver mudanças que não cabem em um só tipo, pare e me mostre — eu separo os commits manualmente.
Depois crie o commit usando HEREDOC para preservar a formatação. Não use --amend. Não pule hooks.
Digite /commit e o agente lê o diff, decide o tipo, escreve a mensagem e faz o commit. Em cinco linhas de config, você codificou a convenção do seu time.
Exemplo 2: /review-pr
Outro clássico — revisar um PR sem abrir o navegador:
---
description: Revisa um PR do GitHub por número
argument-hint: "<número do PR>"
allowed-tools: Bash(gh *), Read, Grep
---
Pegue o PR #$1 do repositório atual:
1. `gh pr view $1 --json title,body,files,additions,deletions`
2. `gh pr diff $1`
Leia o diff com olhar crítico de code-reviewer sênior. Para cada problema encontrado, reporte:
- Arquivo e linha
- O que está errado
- Sugestão de correção (não edite — só sugira)
Se estiver tudo ok, diga explicitamente "looks good to merge".
Invoque com /review-pr 123. O agente busca o PR, lê o diff e devolve uma revisão textual. Você compara com o que já tinha visto e bate o martelo.
Debugando quando o comando não funciona
Três armadilhas comuns no começo:
1. O comando não aparece no autocomplete. Quase sempre é path errado. Confirme .claude/commands/<nome>.md (no projeto) ou ~/.claude/commands/<nome>.md (pessoal). Depois reinicie o Claude Code se já estava aberto — ele carrega a lista no start.
2. O argumento não está sendo interpretado. Se você usou $ARGUMENTS mas está vazio, o argumento provavelmente ficou colado no nome do comando. Deve ser /test-report auth, não /test-reportauth.
3. O comando parece ignorado. Se você escreveu um comando muito longo misturado com instruções conflitantes, o agente pode priorizar o prompt do usuário sobre o conteúdo injetado. Mantenha cada comando com uma intenção única — se precisar de dois comportamentos, faça dois comandos.
Compartilhando com o time
A beleza dos slash commands de projeto é que eles são versionados. Quando você comita .claude/commands/commit.md, todo desenvolvedor novo do repo herda o comando automaticamente. Isso resolve um problema clássico: você ensina a convenção uma vez, no arquivo, e ela passa a ser executada pelo agente de quem nunca a leu.
Um bom primeiro commit é criar 3-5 comandos do time e um README.md curto dentro de .claude/commands/ explicando o que cada um faz. Para um arsenal pessoal além dos comandos de time, vale investir nas skills mais fortes — veja 10 Skills essenciais para produtividade no Claude Code para ideias prontas. E quando você perceber que um ritual fica grande demais para um slash command único, é sinal de que virou um subagent ou uma skill — vale a comparação antes de inflar o arquivo.
Próximos passos
Comece agora: crie .claude/commands/commit.md com o exemplo acima, comite no repo, e use por três dias. Nas próximas tarefas grandes, combine esse slash command com plan mode ligado — é o par que mais acelera trabalho real. Quando quiser a visão completa do ecossistema e onde slash commands se encaixam, volte ao guia definitivo do Claude Code.
