Slash Commands

A slash command is a Markdown file in .claude/commands/ whose filename becomes a trigger. Save instructions in ux-review.md and Claude Code reads those instructions whenever you type /ux-review. The file is the command — there’s no compilation step, no registration, no manifest.

This puts slash commands at the simplest end of Claude Code’s customisation surface. CLAUDE.md is always-on context. Skills load on inferred relevance. Hooks fire on lifecycle events. Slash commands are the one mechanism you trigger explicitly, by name, when you want exactly that workflow to run.

When a command earns its place

A repeated, deliberate workflow is the trigger. Three patterns in particular:

• An end-of-task review you run on every PR (/ux-review, /copy-check, /migration-review)
• A start-of-session ritual that loads context Claude wouldn’t pull in by default (/resume-context, /brief)
• A multi-step instruction you find yourself pasting into the chat more than twice a week

If you’ve written the same prompt three times in a fortnight, it’s a command. Move it into .claude/commands/ and you’ll never write it again.

Scope

Slash commands follow the same scoping pattern as everything else in Claude Code:

Location	Scope
~/.claude/commands/	User-level — available in every project
.claude/commands/	Project-level — committed with the repo, shared across collaborators

Project commands travel with the codebase. Anyone who clones the repo gets the same shortcuts you do. This is the right default for any command that reflects how this project is built; user-level is for personal habits that follow you between projects.

Anatomy of a command file

The minimum viable command is a single sentence:

Review the staged diff for clarity, flag any jargon that needs explaining,
and verify all factual claims have a source.

Save that as .claude/commands/copy-check.md and /copy-check works.

For anything more involved, three optional frontmatter fields make the command self-documenting:

---
name: client-brief
description: Prepare a briefing document for a client meeting
argument-hint: [client-name]
---

Prepare a briefing document for $ARGUMENTS:

1. Search the project for relevant client docs
2. Summarise the current state of the engagement
3. List outstanding action items
4. Note key contacts and their roles
5. Flag any risks or sensitive topics

Format as a one-page summary.

The argument-hint field is the bit non-obvious enough to call out: when you start typing /client-brief in Claude Code, the hint appears as inline placeholder text, telling you what argument the command expects. Worth setting on any command that takes an argument.

Dynamic elements

Two pieces of syntax make commands flexible enough to be worth saving.

$ARGUMENTS is replaced with whatever you type after the command name. /client-brief Acme Corp substitutes “Acme Corp” wherever $ARGUMENTS appears in the file. Use this for any command where the workflow is fixed but the subject changes.

@filename references a file by path. /fact-check @docs/q3-report.md sends both your fact-checking instructions and the contents of the named file into Claude’s context. Use this when the command needs to operate on a specific file the user names at trigger time.

These two cover the majority of cases. If you find yourself wanting more dynamic behaviour than this, the command has probably outgrown the format — see the graduation note below.

Authoring

Two ways to write a command, same as every other foundational element:

1. Open a text editor, write the Markdown file, save it in the right folder.
2. Tell Claude Code to do it: “Create a slash command at the project level called /migration-review that reads the latest migration file and flags destructive operations.” Claude writes the file. You read and approve before committing.

The second approach is the right default once you’ve written a few by hand and know the shape. Claude Code is faster than you at writing the file, and reviewing a draft is faster than authoring one.

When a command should graduate to a skill

Commands and skills overlap in what they can do. The rules of thumb for when to graduate one:

• The command needs supporting files — templates, references, examples — that won’t fit cleanly in a single Markdown file.
• You want Claude to invoke the workflow on its own when the situation matches, rather than waiting for you to type the trigger.
• The instructions have grown to several screens of Markdown and are getting hard to maintain.

When any of these apply, the workflow has outgrown the slash-command format. Move it to a skill (see Skills). A command that calls out to a skill is also a valid pattern — the command is the trigger, the skill is the implementation.

Built-in commands worth knowing

Claude Code ships with a set of built-in slash commands. You don’t need to memorise them, but four come up often enough in Playbook workflows to call out:

• /init — generates a starter CLAUDE.md based on the project Claude is opened in. Run this on day one of a new project; revise the output by hand.
• /compact — summarises the current conversation to free context window space. Use when a session has run long but you’re not ready to end it.
• /context — shows how much of the context window is in use. Pair with /compact when the indicator suggests you’re nearing the limit.
• /diff — opens an interactive viewer of uncommitted changes. The cheapest way to verify what Claude has actually done before committing.

These four cover most of the lifecycle moments where a built-in command beats writing a prompt.