Mod ou comando personalizado no Claude Code: quando usar cada um?

Fala aí, beleza? O comando que você criou no Claude Code pede um turno do Claude e, se ele estiver no meio de uma resposta, vai pra fila esperar

Já o comando vindo de um mod devolve resultado sem gastar turno do Claude e, com uma configuração a mais (immediate: true), responde na hora mesmo com o Claude trabalhando 😀

Os mods do Claude Code chegaram na versão 2.1.287, anunciada em 1 de outubro de 2026, e vêm ligados por padrão

Então se você vive repetindo tarefa no terminal e quer saber qual caminho dá menos atrito, bora ver a diferença na prática?

O que é um comando personalizado no Claude Code?

O comando personalizado é o jeito clássico de transformar uma tarefa repetida em /alguma-coisa

Hoje os comandos foram unificados com as skills, então o formato recomendado é .claude/skills/<nome>/SKILL.md

O formato antigo, .claude/commands/<nome>.md, continua funcionando, e nele o nome do arquivo vira o comando (se o arquivo se chama revisar.md, você roda /revisar)

Se ficou na dúvida entre os dois formatos, tem um post aqui no blog explicando skill ou comando personalizado em cada caso

Como funciona o arquivo do comando?

O corpo em Markdown é o prompt enviado ao Claude quando o comando roda

E o $ARGUMENTS? É substituído pelo texto que você digita depois do comando

Um exemplo simples no formato legado, em .claude/commands/revisar.md:

Revise o código abaixo procurando bugs, problemas de legibilidade e falhas de segurança

Alvo da revisão: $ARGUMENTS

Aí tu roda /revisar src/auth.js e o Claude recebe esse prompt com o caminho no lugar do $ARGUMENTS

Comando do projeto ou comando pessoal?

Depende de onde o arquivo mora:

• .claude/commands ou .claude/skills dentro do projeto: o comando vale só naquele projeto
• ~/.claude/commands ou ~/.claude/skills: o comando vale em todos os seus projetos

O ponto que pesa: a fila

Se você manda um comando enquanto o Claude está respondendo, o Claude Code coloca na fila e roda depois que o turno atual termina

As exceções são alguns comandos nativos, como /status, /tasks e /usage, que rodam na hora sem interromper a resposta

Ou seja, o seu comando personalizado não tem esse privilégio… e é aqui que o mod entra na história

O que é um mod e como ele cria comandos?

Um mod é um plugin com funções em JavaScript ou TypeScript que rodam dentro do próprio Claude Code

Essas funções ficam ligadas a eventos, como uma chamada de ferramenta, um prompt enviado ou uma requisição ao modelo

E cada função pode fazer três coisas com o evento: observar, alterar ou tratar de um jeito que o comportamento padrão do Claude Code nem roda

Se você já mexeu com hooks ou middleware em algum framework web, a ideia é bem semelhante: teu código entra no meio do fluxo e decide o que acontece 🙂

Estrutura mínima de um mod

Segundo a documentação oficial dos mods, o mínimo é isso aqui:

.claude-plugin/plugin.json   (manifesto do plugin)
hooks/hooks.json             (aponta para o código)
hooks/register.js            (o hooks module, exporta register(on, options))

Como o mod registra um comando

O comando é registrado num hook session.start, com $.command.register({ name, description })

O Claude Code espera esse hook terminar antes do primeiro prompt, então o comando já existe desde o primeiro turno

Quando alguém roda o comando, quem trata é um hook command.run, que retorna um objeto { text: '...' }

Esse texto é impresso direto na transcrição, sem turno do Claude

E pra rodar enquanto o Claude está trabalhando? Adiciona immediate: true no registro do comando, e ele deixa de respeitar a fila

O /diff virou mod

Um detalhe que mostra bem a ideia: o /diff nativo agora é um mod

Dá pra desligar ele no /plugin ou trocar por uma versão sua

E se quiser ver mod de verdade antes de escrever o seu, a Anthropic mantém exemplos na pasta mods do repositório anthropics/claude-code no GitHub

A API também continua evoluindo: a versão 2.1.288 adicionou o $.ui.selection()

Mod x comando personalizado: diferenças lado a lado

Resumindo a tabela: um conversa com o Claude, o outro executa código e devolve resultado 😛

Quando cada um resolve: casos de uso práticos

Use comando personalizado quando…

A tarefa precisa do julgamento do Claude, tipo:

• Revisar código antes de abrir um PR
• Gerar testes pra um arquivo
• Padronizar mensagem de commit
• Qualquer coisa em que o resultado depende do modelo ler, pensar e escrever

Aqui não tem por que complicar: é o prompt que você digitaria toda vez, só que salvo num arquivo

Use mod quando…

A tarefa é execução determinística e precisa ser instantânea:

• Consultar alguma informação no meio de uma resposta longa, sem esperar a fila
• Imprimir na transcrição algo calculado por código, sem gastar turno do Claude
• Trocar o comportamento de um comando nativo, como fazer a sua versão do /diff

O sinal de decisão

Se liga nessa regra simples:

• A tarefa precisa do modelo pensar? É comando personalizado
• A tarefa é código que sempre dá o mesmo resultado e você quer na hora? É mod

Usar mod pra algo que o Claude precisa raciocinar não faz sentido, porque o comando do mod devolve texto sem turno do Claude

E usar comando personalizado pra algo puramente mecânico é gastar turno e esperar fila à toa

Cuidados de segurança antes de instalar um mod

Tome cuidado aqui!

Um mod é código que roda com as suas permissões: lê e grava arquivos, inicia processos e faz requisições de rede

E ele não fica em sandbox: o sandbox isola os comandos Bash do Claude, mas processos iniciados por um mod rodam fora dele

Traduzindo: instalar um mod de origem duvidosa é tipo rodar um script aleatório da internet com acesso a tudo, e aí os rm -rf da vida ficam a um passo de distância haha

A recomendação oficial é instalar só de autores e marketplaces confiáveis

Como desligar os mods

Como eles vêm ligados por padrão, vale saber as três saídas:

• Desativar ou desinstalar o plugin na aba Installed do /plugin
• Iniciar a sessão com --safe-mode
• Definir "disableAllHooks": true em ~/.claude/settings.json

E se você instalou ou atualizou um mod pelo shell com uma sessão aberta, rode /reload-plugins nessa sessão, senão ela não enxerga a mudança

Veredito: qual caminho dá menos atrito?

Pra maioria das tarefas repetidas, o comando personalizado ganha fácil

É um arquivo Markdown, sem código pra manter e sem risco extra de segurança

O mod compensa em dois cenários bem específicos:

• Quando a fila e o turno do Claude são o problema, e você quer resposta instantânea inclusive com ele trabalhando
• Quando você quer mudar comportamento interno do Claude Code, como substituir um comando nativo

Nesses casos, o custo é escrever JS/TS e confiar no código que está rodando com as suas permissões

Se esse custo não se paga, fica no Markdown mesmo, que é MUITO mais simples 🙂

Próximo passo

Comece pelo básico: pega aquela tarefa que você repete todo dia e transforma num SKILL.md

Se em algum momento você esbarrar na espera da fila, aí sim vale olhar os mods do Claude Code com calma

Dá uma olhada nos exemplos oficiais em github.com/anthropics/claude-code/tree/main/mods e confere se o seu Claude Code está na v2.1.287 ou posterior

Faça o teste com uma tarefa pequena primeiro, beleza?

Até o próximo post! 😀