77 lines
2.7 KiB
Markdown
77 lines
2.7 KiB
Markdown
|
# Custom slash commands
|
||
|
|
|
||
|
|
A Markdown file becomes a slash command. Write the prompt once, run it with `/name` any time.
|
||
|
|
|
||
|
|
Two directories are scanned, the project shadowing the user by name:
|
||
|
|
|
||
|
|
| Origin | Directory |
|
||
|
|
|---|---|
|
||
|
|
| user | `~/.shiro-neko/commands/*.md` |
|
||
|
|
| project | `.shiro/commands/*.md` |
|
||
|
|
|
||
|
|
The filename is the command: `.shiro/commands/review-diff.md` becomes `/review-diff`. Names are
|
||
|
|
letters, digits, dashes, and underscores; anything else is skipped. A custom command can never
|
||
|
|
shadow a built-in — `/cost` always runs the built-in `/cost`.
|
||
|
|
|
||
|
|
## Format
|
||
|
|
|
||
|
|
```markdown
|
||
|
|
---
|
||
|
|
description: Review the staged diff for defects
|
||
|
|
agent: review
|
||
|
|
---
|
||
|
|
|
||
|
|
Review the staged changes. For each finding give file, line, what breaks, and the fix.
|
||
|
|
```
|
||
|
|
|
||
|
|
Frontmatter is optional but useful:
|
||
|
|
|
||
|
|
- **`description`** — the one line shown in the `/` menu. Without it the first body line is used.
|
||
|
|
- **`agent`** — run this command under a specific agent variant (`default`, `quick`, `deep`,
|
||
|
|
`plan`, `review`). The variant is restored afterwards, so one command does not leak its agent
|
||
|
|
into the rest of the session.
|
||
|
|
|
||
|
|
Everything after the frontmatter fence is the prompt. A file with an empty body is skipped, as
|
||
|
|
is one that fails to parse.
|
||
|
|
|
||
|
|
## Arguments
|
||
|
|
|
||
|
|
The body is a template, expanded against whatever you type after the command:
|
||
|
|
|
||
|
|
- `$ARGUMENTS` — the whole argument string.
|
||
|
|
- `$1`, `$2`, … — positional arguments. A missing positional expands to nothing.
|
||
|
|
|
||
|
|
```markdown
|
||
|
|
Compare $1 against $2 and report the differences. Context: $ARGUMENTS
|
||
|
|
```
|
||
|
|
|
||
|
|
`/compare src/a.ts src/b.ts` sends `Compare src/a.ts against src/b.ts … Context: src/a.ts src/b.ts`.
|
||
|
|
|
||
|
|
## Shell substitution
|
||
|
|
|
||
|
|
A `` !`command` `` inline runs the shell command and inlines its output before the prompt is
|
||
|
|
sent:
|
||
|
|
|
||
|
|
```markdown
|
||
|
|
Review this diff:
|
||
|
|
|
||
|
|
!`git diff --staged`
|
||
|
|
```
|
||
|
|
|
||
|
|
Every substitution runs through the **guard** before executing, exactly as a direct `bash` call
|
||
|
|
is — so a custom command cannot smuggle a destructive command past you. A substitution that
|
||
|
|
exits non-zero, or one the guard refuses, fails the command with the reason named.
|
||
|
|
|
||
|
|
## When to write one
|
||
|
|
|
||
|
|
- A prompt you find yourself retyping: a review shape, a release checklist, a project-specific
|
||
|
|
"how we test".
|
||
|
|
- A prompt that should pin an agent: a read-only review command that always runs under `review`.
|
||
|
|
- Project conventions the whole team should share: commit `.shiro/commands/` so everyone gets
|
||
|
|
the same commands.
|
||
|
|
|
||
|
|
For behaviour that must survive across sessions rather than be invoked on demand, use
|
||
|
|
[memory](memory.md). For instructions the agent loads by task rather than by name, use a
|
||
|
|
[skill](skills.md). For extensions that add tools or refusal rules rather than prompts, see
|
||
|
|
[extensions](extensions.md).
|