Command Development
A slash command is a Markdown file whose body is a prompt. When the user types
/<name> <arguments>, Navin expands the file (arguments, referenced files,
shell output) and runs the result as one agent turn. Commands package a
repeatable workflow behind a short name: a review checklist, a release routine,
a scaffold.
Commands are instructions for Navin
The body is written for Navin, not for the user. It gives instructions ("Review the staged diff and report..."), never a message ("This command will review your code"). The user sees the result of the turn, not the prompt.
Correct:
Review the staged changes for security issues: injection, unsafe file access,
secrets in code. Report each finding with file, line and severity.
Wrong:
This command reviews your code for security issues and you will get a report.
Where commands live
| Scope | Folder | Notes |
|---|---|---|
| Project | <workspace>/.navin/commands/ |
shared with the repository |
| Personal | ~/.navin/commands/ |
every workspace of this user |
| Plugin | <plugin>/commands/ (or the commands paths of plugin.json) |
while the plugin is enabled |
| Shipped | inside Navin (/create-plugin) |
always available |
Rules:
- The command name is the file stem in lower case:
review-pr.mdgives/review-pr. The stem must start with a letter or digit (letters, digits,_,.,-). - Built-in commands of Navin (
/help,/new,/goal...) always win; a file named after one of them is never reached. - On a name clash: project, then personal, then plugin, then shipped.
- Plugin commands are also reachable as
/<plugin>:<name>, which avoids clashes. - Subfolders are namespaces for humans:
.navin/commands/git/sync.mdis still/sync. Mention the namespace in the description. README.mdfiles are ignored, so are files over 128 KB and files with an empty body.- Commands are read when invoked, so an edit takes effect on the next call.
Create a project command:
mkdir -p .navin/commands
cat > .navin/commands/review.md <<'EOF'
Review the staged diff for bugs, missing tests and unclear names.
EOF
File format
The smallest command is plain Markdown with no frontmatter; the whole file is the prompt:
Run the test suite, then summarize failures grouped by module with the most
likely cause for each.
With frontmatter:
---
description: Review a pull request branch against the project checklist
argument-hint: <branch> [focus]
allowed-tools: Read, Grep, Bash(git:*)
---
Review the branch $1 against main. Focus on ${2:-correctness and tests}.
Changed files:
!`git diff --stat main...$1`
Apply the checklist in @docs/review-checklist.md and report findings as a
table: file, line, severity, fix.
Frontmatter fields
| Field | Effect in Navin |
|---|---|
description |
shown in the command list and in the system prompt index; keep it under 80 characters |
argument-hint |
shown next to the name, e.g. <file> [mode] |
allowed-tools |
restricts the tools of the turn (see below) |
model |
accepted for compatibility; the turn runs on the session model |
disable-model-invocation |
accepted for compatibility; Markdown commands only run when typed |
description
---
description: Generate release notes from commits since the last tag
---
Start with a verb, say what the command produces. Without it the list shows only the name.
allowed-tools
---
allowed-tools: Read, Grep, Bash(git:*)
---
or as a YAML list:
---
allowed-tools:
- read_file
- grep
- exec
---
Common names from other harnesses are mapped to Navin tools (Bash to exec,
Read to read_file, Write to write_file, Edit to edit_file and
apply_patch, Grep, Glob to find_files, WebFetch to web_fetch,
Task to spawn). Navin tool names work directly. Argument filters such as
Bash(git:*) are accepted; the filter is documentation, the whole tool is
granted. skill and read_file are always kept so the command can load
playbooks and read its own references. Omit the field to inherit every tool of
the session.
model
---
model: haiku
---
Navin parses the key but ignores it: the command runs on the model of the
current session. Choose the model per session or per subagent
(spawn model_preset=...) instead.
argument-hint
---
argument-hint: <environment> [version] [--dry-run]
---
Use <required> and [optional], in the same order as $1, $2... The hint
appears in the command list so the user knows what to type.
disable-model-invocation
---
disable-model-invocation: true
---
Accepted and ignored. Navin never invokes Markdown commands on its own: they run only when the user types them, so every command already behaves as if this flag were set.
See references/frontmatter-reference.md for YAML pitfalls and the full
tool-name mapping.
Dynamic arguments
| Placeholder | Replaced by |
|---|---|
$ARGUMENTS |
everything after the command name, verbatim |
$1 .. $9 |
positional arguments, split like a shell (quotes group words) |
${1:-text} |
positional argument, or text when it is missing |
A missing positional becomes an empty string. When the body uses no
placeholder at all, Navin appends the arguments as a final Arguments: ...
line, so a command never silently drops what the user typed.
$ARGUMENTS
---
description: Explain a piece of the codebase
argument-hint: <topic>
---
Explain how $ARGUMENTS works in this repository. Cite files and functions.
/explain the retry logic of the gateway gives "Explain how the retry logic
of the gateway works...".
Positional arguments
---
description: Compare two git refs
argument-hint: <base> <head>
---
Compare $1 with $2. List changed modules, risky edits and missing tests.
/compare main "feature/login form" sets $1=main and
$2=feature/login form (quotes group words, as in a shell).
Defaults and combinations
---
argument-hint: <file> [level]
---
Review @$1 at strictness ${2:-normal}. Extra notes from the user: $ARGUMENTS
${N:-default} is resolved first, then $ARGUMENTS, then $1..$9. Only
digits 1 to 9 are positional; $10 is not.
File references
@path inlines a file before the turn starts, wrapped in a <file path="...">
block. Paths are relative to the workspace; plugin commands may use
@${NAVIN_PLUGIN_ROOT}/templates/report.md. Arguments work too: @$1.
---
argument-hint: <file>
---
Review @$1 for readability and error handling. Suggest concrete edits.
Several files at once:
Compare the old and new configuration:
@config/settings.old.yaml
@config/settings.yaml
List every changed key and its impact.
Static references, always the same file:
Check the code against our rules in @docs/coding-standards.md and
@docs/security-checklist.md.
Only files inside the workspace or the plugin folder are inlined, up to 20 000
characters each. A reference that cannot be inlined (missing file, outside
those roots) stays as literal text, so the turn can still read the file with
read_file. Email addresses and code spans are not treated as references.
Inline shell output
!`command` runs a shell command before the turn and inlines its output in a
fenced block. Use it to hand fresh context to the prompt (git status, test
lists, versions).
---
description: Write a commit message for the staged changes
allowed-tools: Bash(git:*)
---
Staged files:
!`git diff --cached --stat`
Diff:
!`git diff --cached`
Write a conventional commit message for these changes. Do not commit.
- It runs only when
allowed-toolsgrants the shell (Bash,Bash(...)orexec). Otherwise the snippet stays as text and nothing executes. - Working directory: the workspace. Environment:
NAVIN_PROJECT_DIR, andNAVIN_PLUGIN_ROOTfor plugin commands. - Timeout 30 seconds; output capped at 20 000 characters. On a non-zero exit stderr is appended, so the turn sees the error.
- The snippet must fit on one line and contain no backtick.
- Keep these commands read-only and fast. Anything that changes state belongs in the instructions, where the user sees the tool call.
Organizing commands
Flat, for a handful of commands:
.navin/commands/
├── review.md
├── test.md
└── release.md
Namespaced, for many commands:
.navin/commands/
├── git/
│ ├── sync.md -> /sync
│ └── changelog.md -> /changelog
└── docs/
└── api.md -> /api
The folder does not prefix the name, so keep stems unique across folders and mention the group in the description ("git: rebase the branch on main").
Best practices
- One job per command; a clear verb in the name (
/review-pr,/bump-version). - Always set
descriptionand, when arguments are expected,argument-hint. - Grant the fewest tools; add the shell only for
!snippets you need. - Handle the empty-argument case and give defaults with
${N:-...}. - Prefer
@filefor stable context and!for live state. - Keep the body under 150 lines; move long checklists into a referenced file.
- Document non-obvious commands with an HTML comment at the top; it stays in the prompt but is harmless:
---
description: Deploy to an environment
argument-hint: <staging|production> [version]
---
<!--
Usage: /deploy staging 1.4.2
Requires: a clean working tree, gh authenticated.
-->
Deploy version ${2:-latest} to $1 following docs/deploy.md.
Common patterns
Review
---
description: Review changed files
allowed-tools: Read, Grep, Bash(git:*)
---
Changed files:
!`git diff --name-only HEAD`
Review each file for bugs, security issues and missing tests. Report a table
with file, line, severity and fix.
Testing
---
description: Run tests for one file
argument-hint: <test-file>
allowed-tools: Bash(pytest:*)
---
Test output:
!`python -m pytest $1 -q`
Explain each failure and propose the smallest fix.
Documentation
---
description: Document a module
argument-hint: <source-file>
---
Write reference documentation for @$1: purpose, public functions with
parameters and return values, one usage example each.
Workflow
---
description: Prepare a release
argument-hint: <version>
allowed-tools: Bash(git:*), Read, Edit
---
Current tag: !`git describe --tags --abbrev=0`
1. If $1 is empty, ask the user for the version with ask_user and stop.
2. Update the version in pyproject.toml to $1.
3. Add a CHANGELOG entry from the commits since the current tag.
4. Show the diff and wait for confirmation before tagging.
Interactive commands
When a choice cannot be guessed, tell Navin to ask with ask_user instead of
assuming:
---
description: Configure the review strictness of this project
---
Ask the user with ask_user: "Which strictness level?" with the options
lenient, normal, strict. Then write the answer to
.navin/review.local.md as `strict: <answer>` and confirm.
Ask few, closed questions, and only when the answer changes what happens. More
patterns: references/interactive-commands.md.
Commands in plugins
Put files in <plugin>/commands/ (next to plugin.json at the pack root).
Use ${NAVIN_PLUGIN_ROOT} for every path inside the plugin: Navin replaces it
in the body, in @ references and in the environment of inline shell
commands. Never hard-code ~/.navin/plugins/....
---
description: Analyze the project with the plugin script
allowed-tools: Bash(python:*), Read
---
Analysis:
!`python "${NAVIN_PLUGIN_ROOT}/scripts/analyze.py" .`
Report template: @${NAVIN_PLUGIN_ROOT}/templates/report.md
Fill the template with the analysis above.
Typical uses of the plugin root:
Run the plugin script: !`bash ${NAVIN_PLUGIN_ROOT}/scripts/check.sh`
Load plugin configuration: @${NAVIN_PLUGIN_ROOT}/config/defaults.json
Use the plugin template: @${NAVIN_PLUGIN_ROOT}/templates/pr.md
Read a plugin resource on demand: ${NAVIN_PLUGIN_ROOT}/docs/rules.md
Plugin layout:
my-plugin/
├── plugin.json
├── commands/
│ ├── analyze.md -> /analyze or /my-plugin:analyze
│ └── report.md
├── scripts/
│ └── analyze.py
└── templates/
└── report.md
Users who have another /analyze can always type /my-plugin:analyze.
Script and template patterns
---
description: Validate the configuration with the plugin validator
argument-hint: <config-file>
allowed-tools: Bash(bash:*)
---
!`bash "${NAVIN_PLUGIN_ROOT}/scripts/validate.sh" "$1"`
Explain each reported error and how to fix it.
---
description: Generate a report from the plugin template
argument-hint: <topic>
---
Using the structure of @${NAVIN_PLUGIN_ROOT}/templates/report.md, write a
report about $ARGUMENTS and save it to reports/$1.md.
Details: references/plugin-features-reference.md. Before publishing, read
references/marketplace-considerations.md.
Integration with other components
Agents
---
description: Deep review with the plugin reviewer agent
argument-hint: <path>
---
Use spawn with agent=code-reviewer to review $1. Ask it for findings with file,
line and severity, then summarize them for the user.
Skills
---
description: Document the public API
---
Load the technical-writer skill with the skill tool and follow it to document
the public API of this package.
Hooks
Commands and hooks do not call each other directly. Coordinate through a file:
the command writes .navin/<plugin>.local.md, a command hook (the only hook
type in Navin) reads it on its next event. See the plugin-settings skill.
Multi-component workflow
---
description: Full quality pass
allowed-tools: Bash(bash:*), Read
---
Lint results: !`bash "${NAVIN_PLUGIN_ROOT}/scripts/lint.sh"`
1. Spawn agent=test-writer for uncovered modules.
2. Load the code-reviewer skill and review the result.
3. Write a summary to .navin/quality-report.md.
More patterns: references/advanced-workflows.md.
Validation patterns
Argument validation
---
argument-hint: <staging|production>
---
If "$1" is not exactly staging or production, reply with the usage
"/deploy <staging|production>" and stop. Otherwise deploy to $1.
File existence
---
argument-hint: <file>
allowed-tools: Bash(test:*)
---
Check: !`test -f "$1" && echo found || echo missing`
If the check says missing, tell the user the file $1 does not exist and stop.
Otherwise review it.
Plugin resource validation
---
allowed-tools: Bash(test:*)
---
!`test -x "${NAVIN_PLUGIN_ROOT}/scripts/run.sh" && echo ok || echo "run.sh missing"`
If the line above is not ok, report that the plugin install is broken and stop.
Error handling
---
allowed-tools: Bash(make:*)
---
Build output:
!`make build 2>&1 || echo "BUILD FAILED"`
If the output contains BUILD FAILED, explain the first error and suggest a fix.
Do not continue to the deploy step.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
/name does nothing special |
a built-in command has the same name; rename the file |
| Wrong file runs | a project or personal command shadows it; use /<plugin>:<name> |
! snippet shown as text |
allowed-tools does not grant Bash/exec |
@file not inlined |
path outside workspace or plugin root, or file missing |
| Arguments ignored | no placeholder used; they arrive as an Arguments: line |
| Command not listed | empty body, file over 128 KB, or named README.md |
Testing
- Create the file, then run
/<name>with no argument, one argument, and a quoted multi-word argument. - Check the expanded prompt at the top of the turn (
[Command /name ...]). - Confirm
!snippets ran only with the shell granted. - Validate a plugin with the
plugin-validatoragent, or with the validator script shipped in theplugin-structureskill.
The full checklist is in references/testing-strategies.md.
Additional resources
references/frontmatter-reference.md- every field, YAML rules, tool mappingreferences/advanced-workflows.md- multi-step, state, agents, skillsreferences/interactive-commands.md- asking the user with ask_userreferences/documentation-patterns.md- usage blocks, help outputreferences/plugin-features-reference.md- plugin root, namespacing, componentsreferences/marketplace-considerations.md- portability and distributionreferences/testing-strategies.md- test matrix and debuggingexamples/simple-commands.md- complete standalone commandsexamples/plugin-commands.md- commands that use plugin files and scripts
