Slash Commands

What it is#

Slash commands are short typed shortcuts that invoke a packaged workflow. The user types /something at the prompt, the harness recognises it, and either runs a built-in command (managed by the Claude Code CLI itself) or invokes a defined workflow (a markdown file with a prompt and configuration).

Built-in slash commands handle session-level operations: clearing context, switching models, viewing help, configuring settings. Workflow commands handle recurring tasks the user wants to invoke by name: “review this PR”, “set up a recurring task”, “do a security pass”.

The slash-command surface is one of three customisation layers Claude Code offers, alongside skills and sub-agents. Slash commands are the lightest weight: a markdown file is enough to define one. They are how recurring prompts and workflows become a typed shortcut instead of a paragraph the user has to retype.

When to use it#

• Use a built-in slash command when you need a session-level operation: /clear to wipe context, /model to switch model, /config for settings, /help to list available commands.
• Use a workflow slash command when a particular prompt or recipe is something you run more than two or three times. The cost of writing a slash command is small; the saved typing accumulates.
• Use a custom team-shared slash command when a project has a standard “do X” recipe that should look the same for every contributor. Code review, release prep, deployment checklist — these are good candidates.

Avoid slash commands when:

• The work is one-off. A slash command is overhead if you will never invoke it again.
• The work is so simple it would take longer to type the slash than the request. “Read this file” does not need a slash.
• The behaviour you want is automatic, not user-invoked. For “every time X happens, do Y”, use a hook, not a slash command.

How it works#

Built-in commands#

Built-in commands are handled by the CLI directly and do not invoke the model. They include (by convention; the exact set evolves):

These run synchronously inside the CLI; the model is not involved. They are fast and have no token cost.

Workflow commands#

A workflow command is a markdown file that defines a named prompt and (optionally) configuration. The file lives at one of these paths, in precedence order:

1. Project-scoped — <project>/.claude/commands/<name>.md. Available only in this project.
2. User-scoped — ~/.claude/commands/<name>.md. Available in every session.

When the user types /<name>, the harness loads the file, substitutes any arguments, and submits the prompt to the model on the user’s behalf. The model then runs as it would for any other prompt — using whatever tools are appropriate.

Frontmatter and arguments#

A command file has optional frontmatter for metadata and uses $ARGUMENTS as a placeholder for whatever the user typed after the slash:

---
description: Review a pull request and summarise the diff
model: opus
---

You are reviewing pull request #$ARGUMENTS.

Use `gh pr view $ARGUMENTS` and `gh pr diff $ARGUMENTS` to read the PR.
Produce:
- A one-line verdict (merge / changes requested / blocked).
- A summary of the diff (≤ 100 words).
- A bulleted list of concerns ordered by severity.

Invoked with /review 123, the harness substitutes $ARGUMENTS with 123 and the model runs the prompt.

Some commands of note#

Slash commands you will see referenced across the workbook:

• /loop — runs a prompt or another slash command on a recurring interval. Used for polling-style tasks like “check the deploy every 5 minutes”.
• /ultrareview — a thorough code-review pass. Runs the project’s review skill against the current diff.
• /schedule — manages recurring remote agents (routines) that run on a cron schedule.
• /security-review — a security-focused review of the pending changes on the current branch.

These show up as skills in the workbook context but are invokable as slash commands from the user prompt.

Configuration#

Where commands live#

Project-scoped commands committed to the repo travel with the team — every contributor gets the same /review, /release-prep, /triage-bug shortcuts. This is the right place for team-shared recipes.

Frontmatter fields#

The frontmatter is small and optional:

---
description: One-line summary shown by /help
model: opus | sonnet | haiku   # optional override
---

If model is omitted, the command runs against the session’s current model. Overriding is useful for commands that benefit from a stronger model (deep reviews, planning) or a faster one (quick lints).

Arguments#

$ARGUMENTS is the literal string after the slash and command name. Commands that expect multiple positional args parse $ARGUMENTS inside their prompt body — there is no built-in positional parsing.

Examples#

A PR review command#

<project>/.claude/commands/review.md:

---
description: Review a pull request and summarise the diff
model: opus
---

You are reviewing PR #$ARGUMENTS in this repo.

Steps:
1. Run `gh pr view $ARGUMENTS --json title,body,author,headRefName`.
2. Run `gh pr diff $ARGUMENTS`.
3. Run `gh pr checks $ARGUMENTS`.

Then produce:
- One-line verdict.
- Diff summary (≤ 100 words).
- Concerns, ordered by severity.
- Suggested next steps.

Do not push any commits. Do not run `gh pr merge`.

Invoked as /review 1234.

A release-prep command#

<project>/.claude/commands/release-prep.md:

---
description: Run the pre-release checklist
---

Run these checks in parallel and report results:
1. `pnpm test`
2. `pnpm lint`
3. `pnpm typecheck`
4. `pnpm build`

Then summarise:
- Test results
- Any lint warnings
- Any typecheck errors
- Whether the build succeeded

Do not commit or push. Stop at the summary.

Invoked as /release-prep. The standardised checklist takes the same form for every contributor.

A skill-invocation command#

~/.claude/commands/init.md:

---
description: Initialise CLAUDE.md for the current repo
---

Use the `init` skill to draft a CLAUDE.md for this repository.

This pattern — a slash command that just invokes a skill — is how you give a skill a memorable shortcut.

A scheduled poll#

# In the user prompt
/loop 5m /release-prep

The harness runs /release-prep every five minutes until the user stops the loop. Useful for “check the build every five minutes while I work on something else”.

Gotchas#

• Slash commands run as user prompts. The model executes the command’s body as if the user had typed it. Anything the prompt asks for, the model attempts. Audit the prompt body before committing a project-scoped command.
• $ARGUMENTS is literal substitution. No quoting, no escaping. A user who types /review 1234; rm -rf / would interpolate that string directly into the prompt. Treat command bodies like SQL — sanitise where needed.
• Project commands need agreement. Every contributor gets the same slash commands. A team that disagrees on what /review means will end up with churn around the file.
• Built-in vs custom collisions. A user-defined command with the same name as a built-in is shadowed — the built-in wins. Avoid naming a command /clear or /exit.
• Frontmatter model only applies to the model that runs the command. Sub-agents launched from inside the command use their own model defaults.
• Slash commands are not skills. Skills can be triggered by description matching (“the user asks for X, invoke this skill”); slash commands must be explicitly typed. They are complementary, not interchangeable.
• Don’t pack too much into one command. A /do-the-whole-release command that runs nineteen steps is hard to debug. Prefer smaller, composable commands the user invokes in sequence.
• No interactive prompts inside commands. The model cannot stop and ask the user mid-command. Either design the command to make a sensible call without input, or have it stop early and produce a plan the user can /continue.

Slash command vs hook at a glance#

Related features#

• Writing Custom Slash Commands
• Skills — User-Invocable Workflows
• Sub-Agents
• Settings and Configuration
• Hooks Overview