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.
Ele é armazenado como um arquivo markdown simples com um cabeçalho frontmatter e um corpo de prompt abaixo dele.
Resumo
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.
Receita
---
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:
- Uma solicitação que você digita mais de duas ou três vezes.
- Uma instrução de várias etapas que é fácil de esquecer um passo se digitada de memória.
- Uma convenção de equipe que você deseja que todos os contribuidores fraseiem da mesma maneira (uma lista de verificação de revisão de PR, um formato de mensagem de commit).
- Um prompt que deve aceitar um destino (um arquivo, um número de PR, um nome de recurso) via
$ARGUMENTS.
Exemplo de Trabalho
---
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:
- O frontmatter
descriptionaparece no autocompletar para que os colegas de equipe possam descobrir o comando sem abrir o arquivo. allowed-toolsrestringe 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.- O corpo é lido como uma lista de verificação numerada porque é exatamente o que é executado, em ordem, quando o comando é executado.
- Nenhum
$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.
Mergulho Profundo
Como Funciona
- Claude Code escaneia o diretório de comandos (com escopo de projeto ou de usuário) e lista cada arquivo markdown que encontra como um
/nome-do-comandodisponível. - Digitar o comando insere o corpo do arquivo na conversa exatamente como escrito, naquele ponto da vez.
- O frontmatter nunca é enviado como parte do prompt; ele configura como o comando se comporta e aparece, não o que é dito.
- Se um comando com escopo de projeto e um com escopo de usuário compartilharem o mesmo nome de arquivo, o com escopo de projeto tem precedência para esse projeto.
- Editar o arquivo altera o comportamento do comando na próxima vez que ele for executado; não há cache para limpar ou processo para reiniciar.
Campos de Frontmatter em Resumo
| 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. |
Passando Argumentos
---
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.tsenvialib/auth.tsno lugar de$ARGUMENTS.- Se o comando for invocado sem texto adicional,
$ARGUMENTSse 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.
Notas de Markdown
---
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.- O Frontmatter é YAML padrão entre cercas
---; campos desconhecidos geralmente são ignorados em vez de causar um erro, mas atenha-se aos campos documentados para evitar surpresas. - O corpo pode ser tão longo quanto qualquer outro prompt, incluindo formatação markdown, cercas de código e listas numeradas; ele é enviado como texto simples, não renderizado.
Armadilhas
- Esquecer o campo
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 umadescriptionde uma linha, mesmo para comandos que você escreveu apenas para si mesmo. - Tratar
$ARGUMENTScomo 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$ARGUMENTSestiver vazio. - Colisões de nomes entre comandos de projeto e de usuário - um comando com escopo de projeto ofusca silenciosamente um comando com escopo de usuário de mesmo nome, o que pode surpreender alguém que tenha ambos. Correção: use nomes de arquivo distintos e descritivos, e verifique
.claude/commands/em busca de nomes existentes antes de adicionar um pessoal. allowed-toolsexcessivamente 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: escopoallowed-toolspara exatamente o que as etapas do comando exigem.- Confirmar um comando com segredos incorporados no prompt - um arquivo de comando verificado no git é visível para todos com acesso ao repositório, portanto, incorporar uma chave de API ou URL interna como "conveniência" a vaza. Correção: referencie variáveis de ambiente ou configuração externa do prompt em vez de codificar valores confidenciais.
- Esperar que o comando valide seus próprios argumentos - um comando não tem esquema ou sistema de tipos para
$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.
Alternativas
| 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. |
FAQs
Preciso registrar um comando em algum lugar além de criar o arquivo?
Não. Claude Code descobre comandos escaneando o diretório de comandos; criar o arquivo markdown é toda a etapa de configuração.
Qual é a diferença entre comandos com escopo de projeto e com escopo de usuário?
- Comandos com escopo de projeto vivem em
.claude/commands/dentro de um repositório e são compartilhados com qualquer pessoa que clone esse repositório. - Comandos com escopo de usuário estão disponíveis em todos os projetos que um determinado usuário abre, independentemente do repositório.
- Um comando com escopo de projeto com o mesmo nome de arquivo tem precedência sobre um comando com escopo de usuário de mesmo nome.
O prompt de um comando pode incluir blocos de código ou etapas numeradas?
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.
O que acontece se eu invocar um comando sem argumentos, mas o prompt usa $ARGUMENTS?
$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.
Um comando pode restringir quais ferramentas o Claude tem permissão para usar durante sua execução?
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.
Existe um limite para o quão longo o corpo do prompt de um comando pode ser?
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.
Um comando pode chamar outro comando?
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.
A edição do arquivo markdown de um comando requer a reinicialização do Claude Code?
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.
Como faço para tornar o propósito de um comando descoberto por minha equipe?
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.
Posso fixar um comando em um modelo específico?
Sim, usando o campo frontmatter model, que substitui o modelo atual da sessão apenas para a invocação desse comando.
O $ARGUMENTS é validado ou verificado quanto ao tipo de alguma forma?
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.
Toda solicitação repetida deve se tornar um comando personalizado?
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.
Relacionados
- Comandos Personalizados, Hooks e Subagentes: Para Que Serve Cada Um - como os comandos se encaixam ao lado de hooks e subagentes.
- Noções Básicas de Comandos Personalizados e Subagentes - um primeiro comando e um primeiro subagente, lado a lado.
- Disparando um Comando Shell no PostToolUse com Hooks - a contraparte automática de um comando que um usuário precisa digitar.
- Melhores Práticas para Comandos Personalizados, Hooks e Subagentes - convenções de nomenclatura e escopo para comandos.
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.