Claude Code Slash Commands: Repeatable Workflows

Why a retyped prompt drifts and a command does not

A Claude Code slash command is a reusable prompt stored as a file and invoked by name. You type /deploy or /review and Claude reads the command file, follows the procedure it contains, and runs it the same way every time. The appeal is repeatability. A workflow you would otherwise retype, with all its steps, caveats, and ordering, becomes a single name you invoke, and the procedure behind it is identical on the hundredth run as on the first. The risk of not using one is the opposite: a procedure that lives only in your head, retyped from memory each time, drifts a little with every invocation until the workflow you think you are running and the one you actually run diverge.

A team without slash commands runs its important workflows by retyping prompts. Today's deploy prompt mentions the pre-flight check; tomorrow's, typed in a hurry, forgets it. One person's review prompt asks for security analysis; another's does not. The procedure exists, but only as a fuzzy shared memory that each person reconstructs slightly differently. Steps get dropped, ordering shifts, and the workflow that was supposed to be standard becomes whatever the person at the keyboard remembered to type. The cost shows up as inconsistency: a deploy that skipped a check, a review that missed a class of bug, a setup that left out a step nobody noticed until it broke.

This guide covers the slash command setup that makes a workflow repeatable: the command file structure and where it lives, passing arguments so one command handles many inputs, project versus user scope for who inherits the command, the procedure-as-source-of-truth discipline, and the way commands compose into larger workflows. For commands that need to call out to external systems, Claude Code MCP servers covers the tool integrations. For the permissions a command's actions run under, Claude Code permissions covers the policy layer.

The slash command file structure

A slash command is a Markdown file in a commands directory. The filename becomes the command name, and the file contents are the prompt Claude runs when you invoke it. A file at .claude/commands/review.md becomes the /review command.

---
description: Review the current diff for bugs and security issues
---

Review the changes in the current git diff.

## Procedure
1. Run `git diff` to see what changed
2. Read the project CLAUDE.md for the rules these files must follow
3. For each change, check correctness, edge cases, and security
4. Flag anything that violates a CLAUDE.md rule as a hard issue

## Output
List findings as file:line plus a one-line description. End with a verdict:
PASS if no hard issues, FAIL otherwise.

The frontmatter description is what shows in the command list so you and your team can see what each command does. The body is the procedure, written as the instruction Claude follows. The value of putting it in a file is that the procedure is now explicit and fixed. Every /review runs these four steps in this order and produces output in this shape, because the file does not change between invocations the way a retyped prompt does. The procedure is the source of truth, and the command is how you run it.

The same structure scales to the workflows that matter most. A /deploy command encodes the pre-flight checks, the build, the push, and the post-deploy verification, so a deploy is never missing a step because someone forgot it. A /setup command encodes the onboarding procedure for a new feature area. Anything you do more than a couple of times, and care about doing consistently, is a candidate.

Passing arguments to a command

Most useful commands need input. A review command might take a target path; a deploy command might take an environment. Claude Code passes arguments to a command through placeholders the command file references.

---
description: Review a specific path for bugs and security issues
---

Review the changes in $ARGUMENTS.

If $ARGUMENTS is empty, review the full current diff. Otherwise, scope the
review to the files or directory named in $ARGUMENTS.

## Procedure
1. Read the project CLAUDE.md for the rules these files must follow
2. Review only the code in scope, checking correctness and security
3. Flag CLAUDE.md violations as hard issues

The $ARGUMENTS placeholder is replaced with whatever you type after the command name. Invoke /review src/auth and the command reviews the auth directory; invoke /review with nothing and it reviews the full diff. The single command file handles every input because the procedure is written to adapt to the argument rather than hardcoding a target.

For commands that take several distinct inputs, named positional arguments keep them clear.

---
description: Deploy a service to an environment
---

Deploy the service to environment $1, using strategy $2 (default: rolling).

## Procedure
1. Confirm $1 is a known environment (dev, staging, prod)
2. Run the pre-flight check for $1
3. Deploy using the $2 strategy
4. Verify the deploy reports healthy before reporting success

The $1 and $2 placeholders take the first and second arguments, so /deploy staging rolling maps cleanly onto environment and strategy. Naming the positions in the procedure tells Claude what each argument means, which keeps a multi-argument command unambiguous. The discipline mirrors how a well-defined function reads, and it is the same clarity that Claude Code subagents bring to a delegated job: state the inputs, state what each does.

Project scope vs user scope

Commands live in one of two scopes, and the scope decides who can run them. Getting this right is what makes a command a team standard rather than a personal shortcut.

Project scope is the .claude/commands/ directory inside a repository. Commands here are committed and shared with everyone who clones the repo. This is where team workflows belong: the /deploy that everyone should run the same way, the /review that encodes the team's review standard, the /setup that onboards a new feature consistently. Because the command is committed, the procedure is versioned, so a change to how the team deploys is a change to a file in a pull request, reviewable like any other code.

User scope is a commands directory in your Claude Code user settings, outside any repository. Commands here apply across every project you open and are personal to you. This is where your own shortcuts belong: a /scratch that sets up a throwaway experiment the way you like it, a personal /explain that formats explanations to your taste. They follow you between projects and are not imposed on anyone else.

The choice is about audience. A procedure the whole team should run identically belongs in project scope, committed and versioned. A procedure that is just yours belongs in user scope, available everywhere you work. Putting a team workflow in user scope means only you have it; putting a personal shortcut in project scope clutters everyone's command list with something only you use. This is the same scoping logic that Claude Code MCP servers apply to server config: team things shared, personal things personal.

The command CLAUDE.md template

The project CLAUDE.md governs how commands are written and used: what deserves a command, how arguments are handled, and the rules that keep commands consistent.

# Slash command rules

## What deserves a command
- A multi-step workflow run more than a couple of times
- A procedure where consistency matters (deploy, review, release)
- A setup or onboarding sequence that should not vary

## Writing a command (MANDATORY)
- The command file is the source of truth for the procedure
- Write the steps explicitly and in order
- State the output shape the command should produce
- Use $ARGUMENTS or $1/$2 for input, never hardcode a target

## Scope (MANDATORY)
- Team workflows live in project scope (.claude/commands/), committed
- Personal shortcuts live in user scope, not committed
- NEVER put a personal command in project scope

## Hard rules
- NEVER retype a standard workflow you could encode as a command
- NEVER change a command's behaviour without changing its file
- NEVER hardcode an input a command should take as an argument
- NEVER put a team-critical workflow only in one person's memory
- ALWAYS write the procedure as explicit, ordered steps
- ALWAYS commit team commands so the procedure is versioned

Three rules carry most of the value.

The source-of-truth rule is the whole point of a command. When the file is authoritative, the procedure cannot drift, because there is one place it lives and changing it is a deliberate edit. The rule forbids the pattern where a workflow exists both as a command and as a habit people sometimes follow instead, which is how the two diverge.

The arguments rule keeps a command general. A command that hardcodes its target works for exactly one case and gets copied-and-tweaked for every other, recreating the drift the command was meant to prevent. The rule pushes input into arguments so one command file handles the whole family of cases.

The scope rule decides reach. A team workflow only standardises behaviour if the whole team has it, which means project scope and a commit. The rule keeps team-critical procedures out of personal memory and personal shortcuts out of the shared list. This is the same discipline that CLAUDE.md examples bring to project rules: put the shared thing where everyone inherits it.

Commands that compose into workflows

The strongest use of slash commands is composition, where a larger command invokes smaller ones, or a command's output feeds the next step. A /release command might run /review, then /build, then /deploy, each a command in its own right, so the release procedure is assembled from pieces that are independently useful and individually versioned.

The benefit of composing rather than writing one monolithic command is the same as composing functions. Each small command does one job and can be run alone, tested alone, and reasoned about alone. The release command coordinates them but does not duplicate their logic, so a change to how reviews work lives in /review and propagates to every workflow that uses it, including /release. A monolithic command that inlines the review, build, and deploy steps has to be edited in three places when any one of them changes, and the inlined copies drift.

This composition is also where commands meet other parts of the system. A command can invoke a subagent for an isolated subtask, hand work to a parallel fan-out, or call an MCP tool to reach an external system. The command file is the orchestration layer, naming the steps in order, and the subagents, parallel runs, and tools are the workers it coordinates. For the delegation piece, Claude Code subagents covers how a command hands an isolated job to a dedicated agent.

Common Claude Code mistakes with slash commands

Six patterns Claude or a team gets wrong without CLAUDE.md constraints.

1. A workflow retyped instead of encoded

The pattern: an important procedure run from memory, drifting a little each time.

Correct pattern: encode it as a command file so it runs identically every invocation.

2. A hardcoded target instead of an argument

The pattern: a command that only works for one path or environment.

Correct pattern: $ARGUMENTS or $1/$2 so one command handles the whole family of cases.

3. A team workflow in user scope

The pattern: a critical /deploy that only the author has.

Correct pattern: project scope, committed, so the whole team runs it the same way.

4. Behaviour changed without changing the file

The pattern: running a command but mentally adding steps it does not contain.

Correct pattern: change the command file so the procedure stays the source of truth.

5. A monolithic command that inlines everything

The pattern: one giant command duplicating review, build, and deploy logic.

Correct pattern: compose smaller commands so each step is reusable and versioned once.

6. No output shape defined

The pattern: a command that produces unpredictable, unparseable output.

Correct pattern: state the output shape in the command so the result is consistent.

Add each pattern to CLAUDE.md with the corrected form. Combined with the command file structure above, the result is workflows that run the same way every time.

Keeping commands maintained

A command library is code, and it rots like code. A /deploy written six months ago may reference a build step that no longer exists, or skip a check that has since become mandatory. Because a command runs silently and confidently, a stale one is worse than no command, since it executes an outdated procedure with the same authority as a current one.

The maintenance habit is to treat commands like the rest of the codebase: review them when the workflow they encode changes, update the file in a pull request, and delete commands for workflows you no longer run. When a deploy process changes, the change is not done until /deploy reflects it. Keeping the command current is what preserves the property that made it valuable, that invoking the name runs the right procedure. This is the same upkeep that Claude Code MCP servers need, where a config that drifts from reality becomes a liability rather than a help.

Building slash commands that run the same way every time

The slash command setup in this guide produces commands where the file is the source of truth for a procedure, arguments handle the inputs cleanly, team workflows live in project scope where everyone inherits them, and larger workflows compose from smaller commands rather than duplicating logic. The result is a set of workflows that run identically on every invocation, by anyone, instead of a collection of half-remembered prompts that drift with each retype.

The principle is the same as any Claude Code configuration. A workflow that lives only in memory drifts, drops steps, and varies by who runs it. A command file fixes the procedure, takes its inputs as arguments, and lives in a scope the right people inherit, which is what turns a fuzzy habit into a reliable, versioned standard.

For the external systems a command reaches through, Claude Code MCP servers covers tool integration. For the isolated jobs a command delegates, Claude Code subagents covers the delegation pattern. For the policy a command's actions run under, Claude Code permissions covers what Claude is allowed to do.

Get Claudify. Encode your workflows once and run them the same way every time.