Custom Slash Commands

Extend the CLI with reusable Markdown prompts or executable scripts that run from the chat input.

Custom slash commands turn repeatable prompts or scripts into /shortcuts that you can run from chat. Droid scans .factory/commands folders and turns each registered file into a command.

Note

For new reusable workflows, prefer Skills; existing .factory/commands files keep working.

Discovery and naming

Scope	Location	Purpose
Workspace	`<repo>/.factory/commands`	Project-specific commands shared with teammates. Overrides a personal command with the same slug.
Personal	`~/.factory/commands`	Private or cross-project shortcuts available across sessions.

A file is registered only when it matches one of these rules:

It ends with .md.
Its first line starts with a #! shebang.

Filenames are slugged: lowercase, spaces and non-URL characters become -, and the extension is dropped. Code Review.md becomes /code-review.

Command files may be nested in subdirectories; Droid discovers them recursively. Invoke a command with /command-name optional arguments. Run /commands to open the Custom Commands manager for browsing, reloading, or importing.

Markdown commands

Markdown files render as a system notification that seeds Droid's next turn. Optional YAML frontmatter sets autocomplete metadata.

Frontmatter key	Purpose
`description`	Overrides the generated summary shown in slash suggestions.
`argument-hint`	Appends inline usage hints, such as `/code-review <branch-name>`.

Tool scoping is not available for custom commands. Use Skills or Custom Droids for tool policy.

$ARGUMENTS expands to everything typed after the command name. If you do not reference it, the body is sent unchanged.

Note

Positional placeholders like $1 or $2 are not supported in Markdown commands. Use $ARGUMENTS and parse the input inside the prompt.

Tip

Markdown output is wrapped in a system notification so the next agent turn immediately sees the prompt.

Executable commands

Executable files must start with a valid shebang so the CLI can call the interpreter.

Bash

#!/usr/bin/env bash
set -euo pipefail
 
echo "Preparing $1"
npm install
npm run lint
echo "Ready to deploy $1"

The executable receives positional arguments (/deploy feature/login sets $1=feature/login).
The script runs from the current working directory and inherits your environment.
Stdout and stderr (up to 64 KB) plus the script contents are posted back to the chat transcript for transparency. Failures still surface their logs.

Managing commands

Edit or add files directly in .factory/commands. In /commands, press R to reload, I to import, or Esc to close.
Import existing .agents or .claude commands: open /commands, press I, then use Space to select, A to toggle all, Enter to import, and B or Esc to return. Import scans .agents/commands and .claude/commands at the repo root and in ~. It copies only .md files and skips files that already exist in .factory/commands.
Remove a command by deleting its file. Workspace commands take precedence, so deleting the repo version reveals the personal fallback if one exists.

Examples

Review checklist

Markdown

---
description: Send a structured code review checklist
argument-hint: <branch-or-PR>
---
 
Review `$ARGUMENTS` and respond with:
 
1. Summary of what changed and why it matters.
2. Correctness checks: tests, edge cases, and regressions.
3. Risks: security, performance, or migration concerns.
4. Follow-up TODOs with file paths and owners.

Run /review feature/login-flow to seed Droid with a consistent checklist.

Deploy helper

Bash

#!/usr/bin/env bash
set -euo pipefail
 
target=${1:-"src"}
 
echo "Running lint and tests for $target"
npm run lint -- "$target"
npm test -- --runTestsByPath "$target"
 
git status --short
echo "Done"

Saved as deploy.sh, this shows up as /deploy. Pass a path (/deploy src/widgets) to constrain the checks and share the aggregated output in the thread.