claude-code/slash-commands

Overview

Claude Code slash commands are reusable prompts plus a small amount of declarative configuration that Claude Code injects when the user types /<name>. They sit on disk (in ~/.claude/commands/ or <repo>/.claude/commands/) as Markdown files with YAML frontmatter. A well-designed slash command turns a recurring agent workflow into a one-keystroke operation without hiding the intent from the user.

This skill covers: when to build a slash command vs. a sub-agent or hook, how to structure the command, how to pass arguments, how to reference files and tools safely, review criteria, and the shipping checklist.

When to use

Build a slash command when all of the following hold:

• The task is naturally driven by the user, not the assistant (reach for hooks/sub-agents if the trigger is implicit or automated).
• The prompt is reusable across repos or sessions.
• The ideal invocation is short — a phrase the user types, optionally with a few arguments.
• You need determinism in the starting context: you want Claude to start from the same framing every time.

Do not use a slash command if:

• The behavior should be automatic (use a hook).
• The task requires an isolated reasoning context with tool access different from the main conversation (use a sub-agent).
• The "prompt" is actually shared configuration (settings, memory, or CLAUDE.md).

How it works

File shape

A slash command is a Markdown file whose name (minus .md) becomes the invocation. Optional YAML frontmatter controls metadata:

---
description: One-line summary shown in `/help`.
argument-hint: '<issue-number>'
allowed-tools: [Bash, Read, Grep]
---

# Short title

Instructions for Claude. Use $1, $2, $ARGUMENTS to reference positional args.
Reference files with @path/to/file.ts; they are read and included automatically.
Run non-interactive shell snippets with !command substitution when the value
must be fresh at invocation time.

Arguments

• $ARGUMENTS — raw arg string as typed by the user.
• $1, $2, … — positional tokens split on whitespace.
• argument-hint (frontmatter) — shown inline when the user starts typing the command; keep it short and literal.

Validate args inside the prompt itself — ask Claude to short-circuit and explain if they are missing or shaped wrong. The user sees a useful error instead of a confused action.

File and command interpolation

• @path injects the literal contents of a file at prompt-build time. Use for stable references (style guides, schemas).
• !command runs a shell command before the prompt is sent and inlines stdout. Use sparingly — every invocation pays the cost.
• Prefer letting Claude use its tools at runtime over pre-running commands. ! is for values that must be captured at invocation time (current git branch, clock, hostname).

Tool allowances

Declare the minimum tool set in allowed-tools. A slash command should not grant broader permissions than the surrounding session already has — treat the list as a tightening, not a widening. Omit the field to inherit the session default.

Prompt structure that holds up

1. Role clause. One line restating the task posture ("You are reviewing a PR for style regressions, not correctness.").
2. Input contract. What the assistant should read first — files, tickets, arguments. Be explicit so the assistant doesn't improvise.
3. Procedure. Numbered, short. Each step should be verifiable.
4. Stop conditions. When to halt, when to ask the user, when to fail loudly.
5. Output contract. The shape of the final artifact (diff, checklist, Markdown summary).

Avoid: verbose preamble, filler encouragement, duplicate guidance already in the top-level system prompt, tool lists embedded in prose.

Examples

Minimal PR-review command

---
description: Review the current branch against style rules.
argument-hint: '[optional base-branch]'
allowed-tools: [Bash, Read, Grep]
---

# PR review

Review the changes in the current branch vs. $1 (default: main) for:

1. Lint-clean diffs only — flag any `// eslint-disable-next-line` added.
2. Test coverage on new code paths.
3. Commit messages follow Conventional Commits.

Run `git diff $1..HEAD --stat` first to scope the work. If the branch hasn't
diverged, say so and stop. Produce a short Markdown report with file-grouped
findings. Don't modify code.

Issue-driven scaffold

---
description: Turn a Linear issue into a branch + initial commit.
argument-hint: '<linear-issue-url>'
---

# Start from issue

Read the Linear issue at $1 via the Linear MCP tool if available, else ask the
user to paste the issue body.

Create a branch named `<owner-handle>/<issue-id>-<slug>`.
Write a draft plan as `./plan.md` with checkboxes derived from the issue.
Commit the plan with message `chore: plan for <issue-id>`.
Do not push.

Non-obvious: fan-out delegation

---
description: Fan out independent investigations to sub-agents.
argument-hint: '<topic>'
---

# Investigate $1

Identify 2–4 independent facets of "$1" that can be researched separately
(e.g., history, current state, tradeoffs, recommendations). Delegate each to
a fresh sub-agent in parallel with a tight scope. Wait for all to return.
Synthesize into a single brief with one recommendation. Cite each fact.

Limitations

• Slash commands share context with the current conversation. They are not isolated — use sub-agents when isolation matters.
• !command executions happen in the user's shell with the user's permissions. Never inline commands that touch secrets or production.
• Nested slash commands are not supported; compose by calling tools, not by invoking /foo from within another command.
• File inlining via @path happens at build time — the content is the file as-of the invocation moment, not as-read-later. For moving targets, prefer having Claude Read the file at runtime.
• The frontmatter is not a security boundary; it narrows but cannot expand permissions. Don't treat allowed-tools as a sandbox against a malicious prompt.

References

• Claude Code — Slash commands
• Claude Code — Memory & CLAUDE.md
• Claude Code — Sub-agents
• Claude Code — Hooks