Slash Commands

Slash commands transformam arquivos markdown em templates de prompt reutilizáveis e parametrizados: coloque review-pr.md em .chatcli/commands/ e /review-pr 1326 security vira um prompt completo expandido — no REPL, dentro de uma sessão /coder em andamento, em scripts one-shot -p, pelo gateway de mensagens, e via ACP e MCP. A expansão acontece antes de o request ser montado, então os comandos funcionam de forma idêntica com todos os providers que o ChatCLI suporta. E se o seu time já mantém comandos para Claude Code, Devin, Windsurf, Cursor, opencode, Codex, Gemini CLI, Qwen Code ou GitHub Copilot, esses arquivos funcionam aqui sem mudanças — migração zero.

Comandos vs. skills

	Skill	Slash command
O que é	Conhecimento — “como fazemos X aqui”	Ação — “faça X agora com estes args”
Onde entra	Bloco de guidance no system prompt	Vira o próprio turno do usuário
Ciclo de vida	Persistente, envelhece, re-ativa	One-shot, consumido
Parametrização	Args anexados ao lado	`$ARGUMENTS` / `$1`…`$9` interpolados

Ambos aparecem no completer e no palette /menu.

Onde os comandos moram

Varridos em ordem de precedência — o primeiro nome encontrado vence. Os diretórios nativos do ChatCLI vêm primeiro, depois a matriz de interop: se o seu time já usa qualquer uma dessas CLIs de agente, os arquivos de comando delas funcionam no ChatCLI sem mudanças.

Fonte	Projeto	Global	Formato
ChatCLI	`.chatcli/commands/`	`~/.chatcli/commands/`	md
Claude Code	`.claude/commands/`	—	md
Devin	`.devin/workflows/`	—	md
Windsurf	`.windsurf/workflows/`	—	md
Cursor	`.cursor/commands/`	`~/.cursor/commands/`	md
opencode	`.opencode/commands/`	`~/.config/opencode/commands/`	md
Codex (OpenAI)	—	`~/.codex/prompts/` (só top-level)	md
Gemini CLI	`.gemini/commands/`	`~/.gemini/commands/`	TOML
Qwen Code	`.qwen/commands/`	`~/.qwen/commands/`	TOML
GitHub Copilot	`.github/prompts/*.prompt.md`	—	md

Subdiretórios viram namespaces: frontend/deploy.md → /frontend:deploy (o git/commit.toml do Gemini → /git:commit). Chaves de frontmatter alheias (agent, subtask, mode, auto_execute_steps) são toleradas; o model do opencode mapeia pro hint de modelo do ChatCLI. Frontmatter que nem YAML válido é — como o formato argument-hint: [FILES=<paths>] documentado pelo próprio Codex — cai num parse linha a linha em vez de descartar o arquivo. Um comando nunca pode fazer shadow de um comando built-in — arquivos chamados session.md, config.md etc. são recusados e reportados em /config commands.

Anatomia de um comando

---
description: Revisa um pull request com um foco específico
argument-hint: <numero-do-pr> [foco]
model: claude-sonnet-5
effort: high
allowed-tools: read, search
---
! gh pr view $1 --json title,body

Revise o PR $1 com foco em $ARGUMENTS.
Fundamente cada apontamento no diff acima.

Frontmatter	Efeito
`description`	Aparece no completer, `/menu`, e nas listagens ACP e MCP
`argument-hint`	Dica de uso mostrada quando invocado sem args
`model` / `effort`	Roteiam o turno expandido (mesmo encanamento cross-provider das skills)
`allowed-tools`	Restringe as tools durante o run iniciado pelo comando (veja abaixo)

Placeholders (a sintaxe de cada dialeto funciona em qualquer arquivo):

Placeholder	Significado
`$ARGUMENTS`	String de argumentos crua, verbatim
`{{args}}`	Alias Gemini/Qwen do mesmo
`$1`…`$9`	Argumentos posicionais (tokens `KEY=value` ficam de fora)
`$KEY`	Argumento nomeado estilo Codex: invoque com `/draftpr FILES="a b" PR_TITLE="Add hero"`
`$$`	Um `$` literal

$PALAVRAS desconhecidas passam intactas.

Linhas de pré-execução (`!`)

Uma linha começando com ! executa um comando shell e embute o output no prompt expandido. Os dialetos inline também funcionam — o !{cmd} do Gemini e o !`cmd` do opencode substituem no meio da frase. Toda ocorrência, linha inteira ou inline, passa pelo mesmo gate de segurança das tools do coder:

Comandos safety-immune (rm -rf, sudo, …) sempre exigem aprovação interativa — nunca auto-aprovados, nem pelo automode.
Suas regras de /policy se aplicam (allow / ask / deny), e decisões de aprovação podem persistir regras novas (allow-always / deny-forever).
Em superfícies unattended (gateway, MCP, ACP, scheduler) um “ask” resolve via /policy automode — ou cai em deny fail-safe. Uma linha negada é substituída por um marcador explícito para o modelo saber que o output está faltando, nunca silenciosamente vazio.

Linhas dentro de code fences nunca são executadas — documentação continua documentação.

`allowed-tools`

Quando definido, o run iniciado pelo comando ganha um overlay efêmero no gate de segurança: uma tool fora da lista escala de allow para ask — o humano (ou o policy automode) arbitra a exceção. Nunca amplia permissões silenciosamente e nunca nega silenciosamente.

Superfícies

Superfície	Comportamento
REPL chat	`/nome args` despacha como qualquer comando; completer + `/menu` listam o catálogo
`/coder` mid-run	Follow-ups e type-ahead também expandem; `allowed-tools` re-arma o escopo, `model`/`effort` são ignorados mid-loop
One-shot	`chatcli -p "/review-pr 1326"` expande antes do roteamento
Gateway	Uma mensagem de canal `/deploy prod` expande antes de o coder engine ver o texto
ACP (IDEs)	Comandos são anunciados via `available_commands_update` com hints de input, e expandem no fluxo de prompt
MCP server	Servidos pela primitive `prompts` — `prompts/list` traz o campo `arguments` do spec, `prompts/get` aceita `{"args": "..."}`
O próprio modelo	O builtin `@commands` deixa o agent descobrir (`list`) e expandir (`get`) os playbooks do time mid-task

Gerenciando

/config commands          # painel de diagnóstico (abaixo)
/config commands reload   # força um re-scan (edições de arquivo também são detectadas automaticamente)
/reload                   # também re-escaneia o catálogo

O painel agrupa o catálogo por fonte com contagens e hints de argumento, depois os ledgers de falha — comandos recusados por shadow de built-in e arquivos pulados com o motivo do parse — e cada diretório varrido com marcador ✓/– de existência:

⌘ Slash Commands ─────────────────────────
  9 comando(s) de 4 fonte(s)

  ▸ Projeto (.chatcli/commands) (2)
    /deploy       Deploy service          <env>
    /review-pr    Review a PR             <pr> [foco]

  ▸ Gemini CLI (1)
    /git:commit   Writes a conventional commit

  ⚠ Pulados (falha de parse — corrija o arquivo e ele carrega no próximo scan):
    ~/.gemini/commands/broken.toml
      unterminated """ string

  Diretórios varridos (ordem de precedência):
    ✓ ~/projeto/.chatcli/commands
    – ~/projeto/.claude/commands

O catálogo é servido de um cache com fingerprint por stat: lookups são gratuitos até um arquivo realmente mudar.

Variável de ambiente	Default	Efeito
`CHATCLI_COMMANDS`	`true`	Chave mestra da feature inteira

Exemplo: standup do time

mkdir -p .chatcli/commands
cat > .chatcli/commands/standup.md <<'EOF'
---
description: Resumo de standup a partir dos commits recentes
argument-hint: [dias]
---
! git log --oneline --since="$1 days ago" | head -20

Com base nos commits acima, escreva um resumo de standup em 3 bullets.
EOF

Commite — todo o time (e os agents, via @commands) agora tem /standup 2.

Início

Primeiros Passos

Conceitos Fundamentais

Funcionalidades

Segurança

Suporte

Comandos vs. skills

Onde os comandos moram

Anatomia de um comando

Linhas de pré-execução (`!`)

`allowed-tools`

Superfícies

Gerenciando

Exemplo: standup do time

​Comandos vs. skills

​Onde os comandos moram

​Anatomia de um comando

​Linhas de pré-execução (!)

​allowed-tools

​Superfícies

​Gerenciando

​Exemplo: standup do time

Comandos vs. skills

Onde os comandos moram

Anatomia de um comando

Linhas de pré-execução (`!`)

`allowed-tools`

Superfícies

Gerenciando

Exemplo: standup do time