Custom Slash Commands in Claude Code

You keep typing the same multi-line prompt. "Review this file for missing error handling, N+1 queries, and untested branches." "Draft a changelog entry from my staged changes." "Explain what this module does and why." Retyping a good prompt every session is exactly the kind of friction Claude Code's custom slash commands remove.

A custom slash command is a saved prompt you invoke by name. Write it once as a Markdown file, and from then on /your-command fires it — optionally with arguments — instead of you re-typing it. This article covers what they are, when they pay off, how arguments work, and the thing people most often get tangled up in: how slash commands differ from skills.

What a custom slash command is

A custom slash command is a Markdown file whose contents become a prompt. The filename is the command name: a file named review.md gives you /review. When you type that command, Claude Code takes the file's body, substitutes any arguments you passed, and sends the result as your message — as if you'd typed the whole thing yourself.

That's the entire idea. It's prompt expansion — a macro for instructions you'd otherwise repeat. In everyday use you're the one who fires it: nothing happens until the command is invoked, and when it is, it expands exactly what's in the file into your message. There's no configuration to wire up and nothing to register.

Claude Code ships with built-in slash commands too — things like clearing the context or switching models. Your custom commands live alongside those and work the same way from your side: type /, pick the command, run it.

When slash commands earn their place

The value shows up with repetition. If a prompt is a genuine one-off, just type it. But the moment you notice you're re-typing the same structured request — especially a multi-step one — that's the signal to save it as a command.

Good candidates share a shape: a task you do often, phrased the same way each time, where consistency matters. A few that tend to recur:

• Reviewing a file against a fixed checklist you always forget one item of.
• Generating tests that follow your house conventions, every time.
• Drafting a commit message or changelog entry from the current diff.
• Turning a rough ticket into a file-level implementation plan.

The payoff isn't only saved keystrokes. It's that the prompt stops drifting. The version you refined — the one that names the edge cases and the output format — runs identically every time, instead of degrading into a lazy one-liner when you're in a hurry.

Passing arguments

A static prompt is useful; a parameterized one is more so. Custom slash commands support argument substitution: text you type after the command name gets injected into the prompt at a placeholder. So /review src/pricing.ts can drop that path into the body where the command expects it.

The common placeholder is $ARGUMENTS, which captures everything you passed. Claude Code also supports positional arguments and a few richer conveniences — pulling in the output of a shell command, or the contents of a file — so a command's prompt can be assembled from live repo state rather than being frozen text. The exact syntax for these is worth reading from the official Claude Code docs rather than trusting a half-remembered version; the concept to hold onto is that a command can take input and build its prompt from real context at the moment you run it.

Here's the shape of a simple command with an argument:

---
description: Generate tests for a file, following our conventions
argument-hint: <path to the file under test>
---
Write tests for $ARGUMENTS.

Follow our conventions:
- Use the existing test framework and file layout.
- Cover the happy path and every error branch.
- Assert on concrete values; no snapshot tests for logic.

Invoked as /write-tests src/pricing.ts, this expands into a full, consistent prompt with the path filled in. The optional frontmatter — here description and argument-hint — is metadata that helps the command surface nicely in the picker. Other fields exist (for example, to scope which tools the command may use, or which model it runs on); the docs list the current set, so check there before relying on a specific field name.

Where the commands live

Custom slash commands are discovered from a .claude/commands/ directory, in two scopes:

• Project commands, in your repository's .claude/commands/, are shared with everyone who clones it. This is how a team standardizes on the same reviews and generators — the command is versioned like any other file, reviewed and improved in pull requests.
• Personal commands, in your home directory's ~/.claude/commands/, follow you across every project.

Organizing commands into subdirectories namespaces them, which keeps a growing collection tidy. For the exact namespacing convention, check the docs — but the model is the same as the rest of Claude Code: drop a file in the right place and it's available, with nothing to register.

How slash commands relate to skills

This is where people get confused, because both live under .claude/ and both can be invoked by typing /name. The difference is who decides when they run and what they package.

A custom slash command is a saved prompt you fire yourself. You choose the moment; it expands its text into the conversation, unchanged except for any arguments you passed. That's the whole contract — you control when it runs, and it's exactly as smart as the prompt you wrote.

A skill is a capability the model can invoke on its own. A skill has a description, and Claude Code reads it to decide, automatically, whether the skill is relevant to what you're doing — loading its instructions only when they apply. You can also trigger a skill by name, but its defining trait is that it fires without you remembering to, based on the task at hand.

So the rule of thumb:

• Reach for a custom slash command when you want to run a specific prompt on demand — a repeatable request you'll deliberately kick off yourself.
• Reach for a skill when you want a procedure applied automatically whenever it's relevant, without invoking anything — "before you commit, run these checks," applied every time you commit.

Slash commands are the older, simpler mechanism: a prompt template. Skills are the richer abstraction — a packaged capability with a description that drives auto-loading and can carry supporting files. They're complementary, not competitors. If you want to see the skill side in a real, readable repo, the free claude-code-starter ships a working ship skill, a subagent, and a CLAUDE.md template you can adapt.

Conceptual examples

To make the split concrete, here are prompts worth saving as commands — cases where you want manual, on-demand control:

• /explain <path> — "Explain what this file does, its inputs and outputs, and any non-obvious control flow." Fired when you hit unfamiliar code.
• /pr-summary — "Summarize the staged diff into a PR description: what changed, why, and how to test it." Fired when you're opening a pull request.
• /harden <path> — "Review this handler for input validation, authorization, and error handling; list concrete gaps." Fired on the files where it matters.

Each is a prompt you'd otherwise retype, invoked exactly when you want it. If instead you wanted "always check authorization on every handler I touch, without me asking," that's a skill's job, not a command's — there, the trigger is the task, not your keystroke.

Wrapping up

A custom slash command is one of the simplest durable upgrades in Claude Code: take a prompt you keep re-typing, save it as a Markdown file, and invoke it by name — with arguments when you need them. Reserve them for the repeated, multi-step requests you want to fire deliberately, and let skills handle the procedures you want applied automatically. Because the exact argument and frontmatter syntax can evolve, lean on the official docs for the specifics — but the concept is stable and worth adopting today: stop retyping your best prompts, and start invoking them.

Related guides

• Claude Code Subagents: A Practical Guide
• Getting Claude Code to Write Tests That Catch Bugs
• 12 Claude Code Tips for Shipping Faster