Writing a Claude Code slash command

What a slash command is for

A slash command is a saved, reusable prompt you can invoke by name instead of retyping it — the difference between typing out a detailed multi-paragraph review checklist every time you want Claude to review a pull request, and typing one short command that expands into that same checklist automatically. The value isn't the typing you save on any single use; it's that the instruction is written once, carefully, and then runs identically every time rather than being reconstructed from memory and drifting slightly each time.

Where a command earns its place over a one-off prompt

Not every repeated instruction needs to become a command. The ones worth saving share a specific property: the phrasing genuinely matters and is easy to get subtly wrong when typed from memory. A code-review checklist with a specific order of checks, a release-note format with an exact structure, a debugging routine with steps that need to happen in sequence — these degrade if retyped loosely each time, and a command keeps them exact. A simple one-off request that's different enough each time anyway doesn't benefit from being saved; there's nothing stable to capture.

Arguments make a command a template, not a fixed string

A command that always does exactly the same thing is useful, but a command that accepts an argument — a file path, an issue number, a target branch — is a template, and that's usually the more valuable shape. The difference matters because a fixed-string command tends to get copy-pasted and manually edited at the point of use, which reintroduces exactly the drift a command was supposed to eliminate; an argument-taking command keeps the instruction itself untouched and only the specific target changes.

Personal commands versus project commands

A command that's useful to you alone — a personal shorthand, a debugging habit specific to how you work — belongs scoped to you rather than committed to the project, where it would show up for every teammate whether or not it means anything to them. A command that encodes a team convention — the project's actual PR checklist, its actual release process — belongs committed alongside the code, so it's versioned with the project and updates for everyone at once rather than living as one person's private habit that nobody else benefits from or even knows exists.

The mistake that makes a command worse than no command

A command that's too vague just relocates the ambiguity rather than removing it — "review this PR" as a saved command produces exactly the inconsistent results that "review this PR" typed fresh each time would, just under a shorter name. The value of a command comes entirely from what's specific and considered in its body: naming the actual checks, the actual order, the actual output format you want. A command worth saving is one you'd be willing to defend line by line if someone asked why it's phrased the way it is — if you can't, it isn't specific enough yet to be worth the indirection of a saved name.

Iterating on a command over time

Treat a command's phrasing the same way you'd treat a piece of code you rely on regularly — revise it when it produces a result you didn't want, rather than working around the bad output by hand each time and leaving the command itself untouched. A command that's quietly been producing mediocre results for months because nobody went back to fix the wording is a worse outcome than never having saved it, since it's actively training a lower bar for what "good" looks like on that task.

Commands that call other commands

Once you have a handful of well-scoped commands, a natural next step is a command that references another — a release command that starts by running the project's checklist command, then adds its own release-specific steps on top. This is worth doing deliberately rather than by accident: a web of commands that call each other several layers deep gets hard to reason about, and debugging why a top-level command produced an odd result means tracing through every command it touched along the way. Keep the chain shallow, and keep each command's own job description narrow enough that you could explain what it does in a sentence.

A command is not a substitute for a good system prompt

It's tempting to offload everything into slash commands and leave the project's baseline instructions sparse, on the theory that commands cover the specifics. That inverts the right division of labour: the system-level project instructions should carry what's true on every task — coding conventions, testing expectations, how the project is structured — and commands should carry what's specific to one repeated kind of request. A command that has to re-explain project conventions every time because they aren't established anywhere else is compensating for a gap that belongs one layer up, not inside the command itself.