What Are Claude Code Slash Commands?

What Are Claude Code Slash Commands?

Type a forward slash into Claude Code and a menu appears. Some of what is in there you probably use daily, like clearing context or switching models. Most of it you have almost certainly never opened.

The more interesting half of the feature is the part you write yourself. A slash command is a reusable instruction you save to a file, so the prompt you keep retyping becomes something you invoke in four keystrokes.

There is a wrinkle, though, and it is the reason a lot of older tutorials now give slightly wrong advice. Custom commands and skills used to be two separate systems. They are now one, and the documentation has moved with them.

What Are Claude Code Slash Commands?

They are short instructions typed at the start of a message, beginning with a forward slash. Claude Code ships with dozens of built-in ones covering session control, review, configuration and diagnostics. You can also define your own by saving a markdown file in your project or home directory, which Claude Code turns into a command named after the file.

The Short Answer

There are two kinds and the distinction is worth holding onto.

Built-in commands act on the session or the tool itself. Things like /clear, /compact, /model, /permissions, /usage and /diff. You do not configure these; they come with the install.

Custom commands are prompts you author. You write a markdown file, Claude Code derives the command name from the filename, and invoking it injects that file's content as your instruction.

One rule governs both. A command is only recognised at the start of your message, so a slash halfway through a sentence is just a character.

A workflow worth automating is usually a workflow worth measuring. A free SEO audit from SEO Stuff shows you where your site is losing search traffic. Get your free audit.

The Commands You Get Out of the Box

The built-in set is large and genuinely worth skimming once. It clusters into a handful of jobs.

Context management is the group most people need first. /clear starts a new conversation with empty context, /compact summarises the conversation so far to free space while continuing it, and /context visualises current usage as a coloured grid with optimisation suggestions.

Session control covers /resume for reopening a conversation by ID or name, /rewind for stepping the conversation or the code back to an earlier point, and /export for writing the transcript out as plain text.

Configuration runs through /config, /model, /permissions for allow, ask and deny rules, and /memory for editing your CLAUDE.md files.

Code work is where the bundled skills live. /code-review reviews the current diff, or a PR number, branch or path you pass; /diff shows the working-tree changes including Claude's own edits; and /simplify runs cleanup-focused review agents in parallel without hunting for correctness bugs.

Diagnostics include /doctor, a setup checkup that diagnoses installation, settings and CLAUDE.md problems and proposes fixes you confirm, and /debug, which turns on session logging mid-session.

Two caveats are worth knowing. Anthropic notes that not every command appears for every user, because availability depends on your platform, plan and environment. And commands are not permanent fixtures: /pr-comments was removed in v2.1.91, and /ultraplan was removed in favour of plan mode.

The Change Most Guides Have Not Caught Up With

Custom commands have been merged into skills. That is Anthropic's own framing, and it has two practical consequences.

The first is that a file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both produce the same /deploy command and behave the same way. The second is that your existing .claude/commands/ files keep working. Nothing broke. The older format is simply no longer the one to reach for when you write something new.

This is why older tutorials stop at creating a commands directory, and why the current reference documentation sends you to the skills page when you look for custom command syntax.

Where the Files Live Now

Three scopes, each with a different reach.

Project scope goes in .claude/skills/ at the root of your repository. These are shared with anyone who checks out the project.

Personal scope goes in ~/.claude/skills/, which is per-user and follows you across every project on that machine.

Nested scope sits in a monorepo subdirectory, such as a skills folder inside apps/web.

How a File Becomes a Command Name

The naming rules are mechanical, and getting them wrong is the most common reason a command does not appear.

A skill takes its name from the name field in its frontmatter, or from its directory name if that field is absent. So .claude/skills/deploy-staging/SKILL.md becomes /deploy-staging.

An older command file takes its name from the filename without the extension, so .claude/commands/deploy.md becomes /deploy.

Subdirectories namespace the command, with each path separator replaced by a colon. A file at .claude/commands/frontend/component.md becomes /frontend:component, and a nested skill at apps/web/.claude/skills/deploy/SKILL.md becomes /apps/web:deploy.

Plugin skills follow the same colon convention, appearing as the plugin name, a colon and the skill name.

How to Build Your Own Slash Command, Step by Step

Step 1: create the directory. Make a skills folder inside your project's .claude directory, then a folder inside it named after the command you want.

Step 2: write the file. Create SKILL.md in that folder. The frontmatter must start on line 1 — Claude Code reads it only when the opening delimiter is the file's very first line.

---
description: Review the staged diff for missing tests
---

Look at the staged changes and list any new behaviour
that is not covered by a test. Do not write the tests.

Step 3: keep the description useful. Every frontmatter field is optional, and description is the one Anthropic recommends. Omit it and Claude Code falls back to the first non-empty line of your content. The description also drives whether Claude picks the skill up unprompted, so lead it with the use case.

Step 4: reload. Run /reload-skills to re-scan your skill and command directories so a file added during the session becomes available without restarting. Then check it appears with /skills.

The frontmatter fields worth knowing beyond description are when_to_use for extra context on when Claude should invoke it, argument-hint for autocomplete, allowed-tools for tools Claude may use without asking during that turn, model and effort for overriding either, disable-model-invocation to stop Claude loading it automatically, and user-invocable for a skill only Claude should trigger.

The same precision pays off in search. Request a free SEO audit and see what is working on your site.

Passing Arguments Into a Command

A command that takes input is far more useful than one that does not, and there are four placeholder forms.

$ARGUMENTS expands to everything you typed after the command name. If no placeholder in your file receives an argument, Claude Code appends what you typed as a labelled arguments line instead, so nothing is silently lost.

$ARGUMENTS[N] picks a single argument by zero-based index, so the first is index zero.

$N is shorthand for the same thing, which means $0 is the first argument and $1 the second. That off-by-one trap catches people coming from shell scripting, where $1 is first.

$name resolves a named argument you declared in an arguments frontmatter field, which accepts either a space-separated string or a YAML list.

Two behaviours are worth internalising. Multi-word values need quoting, so passing a quoted phrase keeps it as one argument. And an indexed placeholder that receives nothing is left in the content unchanged rather than blanked, which is why a command invoked with no arguments can produce an instruction containing a literal dollar sign. If you need a literal dollar amount in the text, escape it with a backslash.

Claude Code also exposes session variables you can interpolate, including the session ID, the current effort level and paths to the skill, project and plugin directories.

Running Shell Commands Inside a Command

This is the feature that turns a static prompt into a live one. You can run a shell command as the file is loaded and inject its output into the instruction.

The syntax is an exclamation mark immediately followed by the command wrapped in backticks. Claude Code recognises it only when that mark sits at the start of a line or directly after whitespace, which stops ordinary punctuation from triggering it. A fenced block opened with an exclamation mark handles multiple lines.

---
description: Summarise the current diff
allowed-tools: Bash(git *)
---

Here is the current diff. Summarise it in three bullets.

Two things govern whether it runs. The allowed-tools field needs to cover the command you are invoking, and that grant is deliberately short-lived: it clears as soon as you send your next message. Separately, an administrator can disable the whole mechanism through a settings flag, in which case the injected output is replaced with a notice that shell execution is disabled by policy.

Live context beats guesswork, in tooling and in search. Book a free SEO audit and find the fixes that actually move rankings.

When a Slash Command Is Worth Writing

Not every repeated prompt earns a file. The ones that do share a shape.

The prompt is long and you keep retyping it. Anything over a few sentences that you have typed three times is a command.

The prompt needs live context. A review command that injects the current diff is strictly better than one that asks Claude to go and find it.

The prompt encodes a team convention. A command checked into the repository is documentation that executes, which is a far better fate than a paragraph in a wiki nobody opens.

Limitations and Things That Trip People Up

Most failures here are quiet rather than loud, which is what makes them annoying.

A misspelled frontmatter field is ignored silently. Anthropic is explicit that a field name must match exactly, hyphens included, and that an unrecognised field is skipped without reporting an error. A typo therefore looks like the feature not working.

Frontmatter not on line 1 is not read. A blank line or a comment above the opening delimiter and the whole block is treated as content.

Boolean values are more forgiving than they used to be. Current versions accept yes, no, on, off, 1 and 0 in any case, but builds before v2.1.218 recognised only true and false.

Descriptions get truncated. The combined description and when-to-use text is cut at 1,536 characters in the skill listing, so front-load the important part.

Skills checked into a repository are executable trust. A skill can grant itself broad tool access through allowed-tools, so Anthropic advises reviewing that field in any repository skill before you run Claude Code there. This is the single most important line in the whole feature.

Portability is narrower than it looks. Outside Claude Code only a small subset of frontmatter fields is accepted, and an unexpected key is a hard error rather than an ignored line. Anthropic also suggests keeping a skill file under 500 lines.

Slash Commands vs the Alternatives

Three other mechanisms overlap, and picking the wrong one is a common mistake.

A CLAUDE.md file is for instructions that should apply always, without being invoked. A slash command is for instructions you want on demand. If you find yourself invoking a command at the start of every session, it belongs in memory instead.

A plugin bundles skills, and therefore commands, for distribution. If you want a colleague on another team to have your command, a plugin is the delivery mechanism. Our guide to how Claude Code plugins work covers what a plugin contains and how marketplaces distribute them.

An MCP server can expose prompts that surface as commands too, which is the right route when the instruction has to come from an external system rather than a file in your repo.

Final Thoughts

The built-in set is worth one deliberate pass through /help; the context-management commands in particular change how a long session feels.

The custom side is where the leverage is, and the main thing to get right is conceptual rather than technical: commands and skills are the same system now, so write new work as a skill and let your old command files keep working. Beyond that, the failures are nearly all in the frontmatter. Put the delimiter on line 1, spell the field names exactly, and give every command a description that says when to use it.

And read the allowed-tools field of any skill you did not write yourself. A command is an instruction with permissions attached, which is exactly as powerful and exactly as risky as it sounds.

Want the same clarity about your search performance? Get a free SEO audit from SEO Stuff and start with what is costing you the most.