commands - SKILL.md Agent Skill

name: commands description: | Gerencia Ravi Commands. Use quando precisar: - Criar, listar, mostrar, validar ou previewar comandos `#nome` - Editar arquivos Markdown em `.ravi/commands` ou `$RAVI_HOME/commands` - Entender como `#command` vira prompt composto antes do runtime - Debugar por que um comando foi expandido, falhou ou passou como chat normal - Usar o CLI `ravi commands`

Ravi Commands

Ravi Commands sao atalhos de prompt invocados pelo usuario com #nome. Eles nao sao slash commands, nao sao shell commands e nao concedem permissao extra ao agent.

Modelo Mental

Um Ravi Command e um arquivo Markdown que vira prompt composto.

Fluxo de mensagem de canal:

Omni recebe o texto cru do usuario.
Ravi resolve rota, sessao e agent.
Se o texto cru comeca com #command, Ravi tenta expandir o command.
Ravi monta o envelope do canal, por exemplo [WhatsApp ...] Luis: ....
O prompt composto entra no SESSION_PROMPTS via NATS.
O runtime despacha normalmente, com as mesmas regras de fila, debounce, interrupcao, barriers e provider.

ravi commands run e diferente: ele so renderiza e retorna o prompt composto para preview. Ele nao publica em sessao e nao executa runtime.

Locais

Commands sao arquivos Markdown em:

<agent.cwd>/.ravi/commands/<name>.md
$RAVI_HOME/commands/<name>.md

$RAVI_HOME normalmente e ~/.ravi.

Ordem de resolucao:

Agent command em <agent.cwd>/.ravi/commands.
Global user command em $RAVI_HOME/commands.

Um command do agent sobrescreve um global com o mesmo nome canonico.

Sintaxe de Invocacao

#review-pr 123 high
#restart "ativar commands"
#daily-summary

Regras:

O token precisa estar no primeiro caractere nao-espaco da mensagem.
O nome aceita letras, numeros e -: #[A-Za-z0-9][A-Za-z0-9-]{0,63}.
Lookup e deteccao de conflito usam lowercase.
#word no meio de uma frase e texto normal.
Um #command valido mas inexistente passa como chat normal.
Um token invalido que comeca com # deve falhar com erro claro.

CLI

ravi commands list --agent <agent> --json
ravi commands show <name> --agent <agent> --json
ravi commands validate --agent <agent> --json
ravi commands run <name> --agent <agent> --json -- <arguments>

Use --agent quando precisar resolver commands do workspace daquele agent.

Formato do Arquivo

---
title: Restart Ravi daemon
description: Restart the Ravi daemon with a contextual reason.
argument-hint: "<reason>"
arguments:
  - reason
---

Restart the Ravi daemon now.

Use this reason: $reason

Frontmatter suportado:

title
description
argument-hint
arguments
disabled

Frontmatter como allowed-tools, model, effort, shell, hooks, context ou agent nao concede capabilities nem altera runtime. Trate como aviso de validacao, nao como regra efetiva.

Argumentos

Placeholders suportados:

$ARGUMENTS: string crua apos o token do command.
$ARGUMENTS[N]: argumento posicional, zero-based.
$N: atalho zero-based.
$name: argumento posicional nomeado em arguments.

Argumentos posicionais usam parsing shell-like. Para passar texto com espaco como um argumento:

#restart "ativar Ravi Commands"

Se argumentos forem fornecidos e o corpo nao usar nenhum placeholder, o renderer adiciona ARGUMENTS: <raw arguments> para nao descartar input do usuario silenciosamente.

Edicao Segura

Editar um arquivo de command nao requer restart do daemon.
Criar ou alterar a implementacao de Ravi Commands no codigo requer build e restart para o daemon vivo usar o patch.
Nao execute snippets de shell contidos no Markdown durante render.
Nao transforme Ravi Command em mecanismo de permissao. Permissoes continuam no runtime, context keys e skill gates.

Debug

Para inspecionar commands:

ravi commands validate --agent dev --json
ravi commands show restart --agent dev --json
ravi commands run restart --agent dev --json -- "ativar Ravi Commands"

Para ver se um command foi expandido em uma mensagem real:

ravi sessions trace <session> --message <message_id> --explain --json

Eventos e metadata relevantes:

command.invoked: command expandido antes do runtime.
command.failed: command invalido, duplicado, disabled ou com erro de validacao.
prompt.published: prompt ja publicado para SESSION_PROMPTS.
adapter.request.commands: metadata dos commands que produziram o prompt.