Escrevendo Seu Primeiro Comando de Barra Personalizado com Frontmatter Markdown
Um comando de barra personalizado é um prompt salvo que você invoca pelo nome em vez de digitar novamente.
//
Busque em todas as páginas da documentação
Um comando de barra personalizado é um prompt salvo que você invoca pelo nome em vez de digitar novamente.
Ele é armazenado como um arquivo markdown simples com um cabeçalho frontmatter e um corpo de prompt abaixo dele.
Um arquivo de comando tem exatamente duas partes: frontmatter YAML entre marcadores ---, e um corpo de prompt abaixo dele.
O frontmatter carrega metadados: uma breve descrição e, opcionalmente, quais ferramentas o comando tem permissão para usar.
O corpo é o texto literal enviado para a conversa no momento em que alguém digita /nome-do-comando.
Os comandos são com escopo de projeto, em .claude/commands/, ou de usuário, para que estejam disponíveis em todos os projetos que o usuário abrir.
Como um comando é apenas um arquivo, criá-lo e compartilhá-lo se resumem a operações git normais, não existe uma etapa de registro separada.
---
description: Resumo de uma linha mostrado no autocompletar de comandos
---
O texto do prompt que é enviado quando este comando é invocado. Escreva-o exatamente
como você mesmo digitaria a solicitação.Salve isso em .claude/commands/<nome-do-comando>.md e ele estará disponível como /<nome-do-comando> no próximo prompt, sem necessidade de reinicialização.
Quando usar isso:
$ARGUMENTS.---
description: Revise um pull request em busca de problemas comuns antes de solicitar um revisor humano
allowed-tools: Bash(git diff:*), Bash(git log:*), Read, Grep
---
Revise as alterações do branch atual em relação ao main antes que eu solicite um revisor humano.
1. Execute `git diff main...HEAD` para ver tudo o que mudou.
2. Verifique: tratamento de erros ausente, logs de depuração deixados para trás e quaisquer comentários TODO
que devam ser resolvidos antes do merge.
3. Confirme se as alterações correspondem ao que o nome do branch ou a última mensagem de commit implicam.
4. Relate as descobertas como uma lista curta com marcadores, classificada por gravidade. Se nada se destacar,
diga isso claramente em vez de inventar pequenas críticas.Salve isso como .claude/commands/pre-review.md. Digitar /pre-review executa a lista de verificação contra qualquer branch que esteja atualmente selecionado.
O que isso demonstra:
description aparece no autocompletar para que os colegas de equipe possam descobrir o comando sem abrir o arquivo.allowed-tools restringe o que o comando pode fazer, aqui limitando o acesso git a operações de diff e log somente leitura, além da leitura de arquivos.$ARGUMENTS é usado aqui; o comando sempre opera em "qualquer branch que esteja atualmente selecionado", o que é uma forma de comando válida e sem argumentos./nome-do-comando disponível.| Campo | Obrigatório | Propósito |
|---|---|---|
description | Recomendado | Resumo de uma linha mostrado no autocompletar e nas listagens de comandos. |
allowed-tools | Opcional | Restringe quais ferramentas o prompt deste comando tem permissão para usar, mais restrito que o padrão da sessão. |
argument-hint | Opcional | Uma dica curta mostrada no autocompletar descrevendo o que $ARGUMENTS espera, por exemplo, <caminho-do-arquivo>. |
model | Opcional | Fixa este comando em um modelo específico em vez de herdar o modelo atual da sessão. |
---
description: Explique o que um arquivo específico faz e quem depende dele
argument-hint: <caminho-do-arquivo>
---
Leia $ARGUMENTS e explique seu propósito, suas exportações públicas e quaisquer arquivos
neste repositório que importam dele. Mantenha a resposta com menos de 150 palavras.$ARGUMENTS é substituído por tudo o que foi digitado após o nome do comando, então /explain-file lib/auth.ts envia lib/auth.ts no lugar de $ARGUMENTS.$ARGUMENTS se resolve como uma string vazia, então escreva o prompt de forma que ainda faça sentido (ou declare explicitamente que um destino é necessário).argument-hint é puramente cosmético. Ele mostra ao leitor o que digitar, mas não valida nem impõe nada no momento da invocação.---
description: Mantenha o frontmatter mínimo - apenas os campos que o comando realmente usa
---
Prefira um corpo curto e direto em vez de um longo. O corpo do prompt é lido a cada
vez que o comando é executado, então a verbosidade aqui é um custo recorrente, não um
custo único.---; campos desconhecidos geralmente são ignorados em vez de causar um erro, mas atenha-se aos campos documentados para evitar surpresas.description - o comando ainda funciona, mas torna-se muito mais difícil para os colegas de equipe descobrirem o que ele faz apenas pelo autocompletar. Correção: sempre inclua uma description de uma linha, mesmo para comandos que você escreveu apenas para si mesmo.$ARGUMENTS como obrigatório - se o corpo do prompt assume que um destino foi sempre passado e um não foi, o comando é executado em uma string vazia e produz um resultado confuso. Correção: instrua explicitamente o prompt a solicitar um destino, ou declare um comportamento padrão, quando $ARGUMENTS estiver vazio..claude/commands/ em busca de nomes existentes antes de adicionar um pessoal.allowed-tools excessivamente amplo - deixar isso indefinido significa que o comando herda todo o acesso a ferramentas da sessão, mesmo para um comando que só precisa ler arquivos. Correção: escopo allowed-tools para exatamente o que as etapas do comando exigem.$ARGUMENTS; é uma substituição de string bruta. Correção: escreva o prompt de forma defensiva, dizendo ao Claude o que fazer se o argumento parecer malformado ou ausente.| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| Digitar a solicitação do zero a cada vez | A solicitação é verdadeiramente única e improvável de se repetir. | Você se pega digitando um prompt quase idêntico mais de duas vezes. |
| Um hook PostToolUse ou PreToolUse | A ação deve ocorrer automática e deterministicamente, sem envolvimento de julgamento. | A tarefa requer raciocínio, coleta de contexto ou uma decisão, pois os hooks não podem raciocinar. |
| Um subagente gerado ad hoc | A tarefa é um trabalho de pesquisa ou exploração único e isolado. | O mesmo padrão de delegação será necessário repetidamente, o que é melhor capturado como um comando que gera um subagente. |
Não. Claude Code descobre comandos escaneando o diretório de comandos; criar o arquivo markdown é toda a etapa de configuração.
.claude/commands/ dentro de um repositório e são compartilhados com qualquer pessoa que clone esse repositório.Sim. O corpo é texto simples enviado para a conversa, portanto, qualquer formatação markdown, incluindo cercas de código e listas numeradas, é preservada e interpretada normalmente.
$ARGUMENTS se resolve como uma string vazia. O prompt ainda é executado, portanto, deve ser formulado para lidar com esse caso de forma graciosa em vez de assumir que um valor está sempre presente.
Sim, através do campo frontmatter allowed-tools, que restringe o acesso a ferramentas para a execução desse comando, independentemente das permissões mais amplas da sessão.
Não há um limite rígido documentado, mas um corpo longo é enviado na íntegra toda vez que o comando é executado, então prompts concisos são mais baratos e fáceis de manter do que os extensos.
O corpo do prompt de um comando pode instruir o Claude a executar as mesmas etapas que outro comando faria, mas os comandos não se invocam diretamente como uma função chama uma função; o corpo é apenas texto.
Não. O arquivo é lido no momento da invocação, portanto, as edições entram em vigor na próxima vez que o comando for chamado.
Defina o campo frontmatter description com um resumo claro de uma linha; é o que aparece no autocompletar quando um colega de equipe está navegando pelos comandos disponíveis.
Sim, usando o campo frontmatter model, que substitui o modelo atual da sessão apenas para a invocação desse comando.
Não. É uma substituição de string bruta sem esquema, portanto, qualquer validação da forma ou conteúdo do argumento deve ser escrita no próprio prompt.
Não necessariamente. Um comando vale o overhead assim que uma solicitação se repete o suficiente para que salvá-la e nomeá-la se pague; uma solicitação verdadeiramente única é mais simples de digitar do zero.
Versões da Pilha: Escrito com base na linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5. Nomes de modelos, preços e recursos do produto mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.
Revisado por Chris St. John·Última atualização: 16 de jul. de 2026