{"id":517,"date":"2026-07-29T02:13:15","date_gmt":"2026-07-29T02:13:15","guid":{"rendered":"https:\/\/abrarqasim.com\/blog\/claude-code-slash-commands\/"},"modified":"2026-07-29T02:13:15","modified_gmt":"2026-07-29T02:13:15","slug":"claude-code-slash-commands","status":"publish","type":"post","link":"https:\/\/abrarqasim.com\/blog\/claude-code-slash-commands\/","title":{"rendered":"Claude Code Slash Commands: The Ones That Earn Their Place"},"content":{"rendered":"\n

Last updated: July 2026. Reflects Claude Code 2.1.x, the .claude\/skills\/<\/code> format that replaced .claude\/commands\/<\/code>, and the namespacing bug that is still open.<\/em><\/p>\n\n\n\n

\n

TL;DR<\/h3>\n\n\n\n

Claude Code slash commands are two different things wearing one name: built-in session controls like \/clear<\/code>, \/compact<\/code>, \/context<\/code>, and \/model<\/code>, and custom commands you write yourself as Markdown files. The custom ones used to live in .claude\/commands\/name.md<\/code>; Anthropic now calls that the legacy format and points you at .claude\/skills\/name\/SKILL.md<\/code> instead. Both still produce \/name<\/code>, both take the same frontmatter (description<\/code>, argument-hint<\/code>, allowed-tools<\/code>, model<\/code>, disable-model-invocation<\/code>), and both support $ARGUMENTS<\/code>, !<\/code> for injecting shell output, and @<\/code> for injecting files. The single highest-value trick is bash injection: a command that runs !`git diff --cached`<\/code> before Claude thinks is worth more than a command with a beautifully worded prompt. The thing that will waste your afternoon is subdirectory namespacing, which the docs describe and the CLI does not implement the way they describe it.<\/p>\n<\/div><\/div>\n\n\n\n

The word “slash command” covers two unrelated things<\/h2>\n\n\n\n

This is the source of most of the confusion I see, so it goes first.<\/p>\n\n\n\n

When you type \/<\/code> in a Claude Code session, the autocomplete list mixes two categories that have nothing in common except the prefix. Built-in commands are session controls compiled into the CLI. They manipulate the conversation, the model, or your config. You cannot write one, override one, or change what one does. Custom commands are Markdown files on your disk that expand into a prompt. They are text. Claude reads them the same way it reads anything else you type.<\/p>\n\n\n\n

The practical consequence: \/compact<\/code> is not a prompt, it is a mechanism, and you cannot ask Claude to run it for you. Your \/deploy<\/code> command is<\/em> a prompt, so Claude can invoke it on its own if you let it. Those two facts drive most of the design decisions later in this post.<\/p>\n\n\n\n

The built-in commands worth memorizing<\/h2>\n\n\n\n

There are a lot of built-ins. I use maybe eight of them with any regularity, and three of those are context management, which is where the actual leverage is.<\/p>\n\n\n\n

Command<\/th>What it does<\/th>When I reach for it<\/th><\/tr><\/thead>
\/clear<\/code><\/td>Wipes conversation history, starts from empty context<\/td>New task in the same repo. Stops the last task’s decisions bleeding into this one.<\/td><\/tr>
\/compact<\/code><\/td>Summarizes older messages and replaces them with the summary<\/td>Mid-task, when context is filling but I still need the history.<\/td><\/tr>
\/context<\/code><\/td>Shows what is currently eating your context window<\/td>Before I decide between \/clear<\/code> and \/compact<\/code>.<\/td><\/tr>
\/model<\/code><\/td>Switches the model for the session<\/td>Dropping to a cheaper model for mechanical work.<\/td><\/tr>
\/cost<\/code><\/td>Token usage and spend for the session<\/td>After a long agentic run, to see what it cost.<\/td><\/tr>
\/rewind<\/code><\/td>Restores earlier conversation state<\/td>When a run went sideways and I want the state from four turns ago.<\/td><\/tr>
\/agents<\/code><\/td>Manages subagent definitions<\/td>Setting up a repo, rarely after.<\/td><\/tr>
\/init<\/code><\/td>Generates a CLAUDE.md from the codebase<\/td>First run in an unfamiliar repo. The output always needs editing.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

The ordering advice everyone gives is “run \/compact<\/code> when you get the warning.” That is backwards. By the time the warning fires, the compaction has to summarize a context that is already 90% full, and the summary it produces is correspondingly lossy. Check \/context<\/code> around the halfway mark and compact then, while there is still room for a summary that keeps detail. I wrote more about how context windows actually degrade in the post about the anti-hallucination prompt that backfired on me<\/a>.<\/p>\n\n\n\n

One more built-in note: \/clear<\/code> does not destroy anything. The old conversation stays on disk and you can resume it by session ID. It is not a delete, it is a fresh window.<\/p>\n\n\n\n

Where custom commands live, and why there are now two answers<\/h2>\n\n\n\n

Every guide written before 2026 tells you the same thing: drop a Markdown file in .claude\/commands\/<\/code>, the filename becomes the command name, done. review.md<\/code> gives you \/review<\/code>.<\/p>\n\n\n\n

That still works. Anthropic’s current docs also label it the legacy format and point you at .claude\/skills\/<name>\/SKILL.md<\/code> instead. The two formats produce the same slash command and accept the same frontmatter. The difference is that a skill can also be invoked autonomously by Claude when it decides the skill is relevant, whereas the mental model for a command file is that you type it.<\/p>\n\n\n\n

Location<\/th>Scope<\/th>Committed to git?<\/th><\/tr><\/thead>
.claude\/commands\/x.md<\/code><\/td>This project, everyone on the repo<\/td>Yes<\/td><\/tr>
.claude\/skills\/x\/SKILL.md<\/code><\/td>This project, everyone on the repo (current format)<\/td>Yes<\/td><\/tr>
~\/.claude\/commands\/x.md<\/code><\/td>You, every project<\/td>No, it is your home dir<\/td><\/tr>
~\/.claude\/skills\/x\/SKILL.md<\/code><\/td>You, every project (current format)<\/td>No<\/td><\/tr>
Plugin<\/td>Distributed to other people, namespaced \/plugin__command<\/code><\/td>Separate repo<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

My rule after a year of this: anything that encodes how this repo<\/em> works goes in the project directory and gets committed. Anything that encodes how I<\/em> work goes in ~\/.claude\/<\/code>. The mistake I made early was putting a \/test<\/code> command in my home directory that assumed Vitest. It fired in a Go repo and Claude confidently went looking for a package.json<\/code>. Personal commands need to be framework-agnostic or they are landmines.<\/p>\n\n\n\n

Anatomy of a custom command<\/h2>\n\n\n\n

A command file is YAML frontmatter plus a prompt body. Here is a complete one:<\/p>\n\n\n\n

---\ndescription: Create a git commit with a conventional message\nallowed-tools: Bash(git add:*), Bash(git commit:*), Bash(git diff:*)\nargument-hint: [optional message]\nmodel: haiku\n---\n\n## Staged changes\n!`git diff --cached`\n\n## Recent commit style\n!`git log --oneline -10`\n\nWrite a Conventional Commits message for the staged changes above.\nMatch the style of the recent commits. If $ARGUMENTS is non-empty,\nuse it as the subject line instead of generating one.\nCommit. Do not push.<\/pre>\n\n\n\n
The frontmatter fields, in order of how much they matter:<\/p>\n\n\n\n
Field<\/th>Purpose<\/th>Default if omitted<\/th><\/tr><\/thead>
description<\/code><\/td>Shown in autocomplete and \/help<\/code>. Also required for Claude to invoke the command itself.<\/td>First line of the prompt body<\/td><\/tr>
allowed-tools<\/code><\/td>Restricts which tools the command can use<\/td>Inherits from the conversation<\/td><\/tr>
argument-hint<\/code><\/td>Shows expected args in autocomplete<\/td>None<\/td><\/tr>
model<\/code><\/td>sonnet<\/code>, haiku<\/code>, a full model ID, or inherit<\/code><\/td>Inherits from the conversation<\/td><\/tr>
disable-model-invocation<\/code><\/td>true<\/code> means only a human typing the command can trigger it<\/td>false<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
description<\/code> looks like documentation and is actually load-bearing. Claude can invoke your custom commands on its own through the SlashCommand tool, but only ones that have a description<\/code> populated. Leave it out and your command becomes type-only. That is sometimes what you want, and there is a cleaner way to say so.<\/p>\n\n\n\n
disable-model-invocation: true<\/code> is the cleaner way. Put it on anything with side effects you would not want an agent triggering mid-run: \/deploy<\/code>, \/commit<\/code>, anything that talks to production. The failure mode without it is not dramatic, it is quiet. Claude decides your \/deploy<\/code> command is a reasonable next step in a long agentic loop, and you find out from the notification. Related reading on why I do not let agents run unsupervised: AI coding agents will run a poisoned issue for you<\/a>.<\/p>\n\n\n\n
model: haiku<\/code> on mechanical commands is the cheapest win in this whole post. Linting, formatting, generating a commit message from a diff \u2014 none of that needs a frontier model. The model reverts when the command finishes; it does not stick to your session or your settings.<\/p>\n\n\n\n
Bash injection is the feature that actually matters<\/h2>\n\n\n\n
Everything above is plumbing. This is the part that changes what your commands can do.<\/p>\n\n\n\n
Prefix a backtick-wrapped shell command with !<\/code> inside a command file and Claude Code runs it before<\/em> the model sees the prompt, then substitutes the output inline. The model does not decide to run git diff<\/code>; the diff is already sitting in its context when it starts.<\/p>\n\n\n\n
## Context\n- Branch: !`git rev-parse --abbrev-ref HEAD`\n- Status: !`git status --short`\n- Failing tests: !`npm test 2>&1 | tail -40`\n\nFix the failing tests above. Change the implementation, not the assertions,\nunless the assertion is provably wrong.<\/pre>\n\n\n\n
The difference in reliability is not subtle. A prompt that says “check the test output and fix the failures” gives the model a choice about how to gather context, and it will sometimes run the wrong command, sometimes run a narrower subset, sometimes decide it already knows. A prompt with the output pre-injected removes the choice. This is the same principle I keep landing on across every agentic setup: constrain the input, do not rely on a better model. I made that argument at length in why the feedback loop beats a smarter model<\/a>.<\/p>\n\n\n\n
Two things that bit me. First, whatever you inject counts against your context window, so !`git diff`<\/code> on a 4,000-line refactor will eat the session before Claude writes a line. Pipe through head<\/code> or --stat<\/code>. Second, the shell command has to be in allowed-tools<\/code> or the whole thing fails at expansion time, and the error is easy to misread as the command not existing.<\/p>\n\n\n\n
File references work the same way with @<\/code>. Review @src\/auth\/session.ts against @docs\/auth.md<\/code> pulls both files into the prompt. Useful when the file set is fixed; useless when it is not, because you cannot glob.<\/p>\n\n\n\n
Arguments, and a docs inconsistency to watch<\/h2>\n\n\n\n
$ARGUMENTS<\/code> captures everything the user typed after the command name. That is the safe one and it behaves the way you expect.<\/p>\n\n\n\n
Positional arguments are where I would slow down. Community guides and most examples use $1<\/code> for the first argument and $2<\/code> for the second. Anthropic’s own SDK page shows an example where \/fix-issue 123 high<\/code> resolves to $0=\"123\"<\/code> and $1=\"high\"<\/code> \u2014 zero-indexed. I have not found a version note explaining the difference, so I stopped guessing: write a throwaway command whose entire body is first=$1 second=$2 zero=$0<\/code>, run it with two known arguments, and read what comes back on your version. Thirty seconds, and it beats debugging a command that silently interpolates the wrong string into a gh<\/code> call.<\/p>\n\n\n\n
Worth knowing regardless: if you reference more placeholders than the user supplied, the unmatched ones stay in the prompt as literal text. So a missing argument does not error, it hands Claude a prompt containing the characters $2<\/code>. If your command has optional arguments, say so in the body \u2014 “if $2<\/code> is empty or still reads as $2<\/code>, default to X.”<\/p>\n\n\n\n
Namespacing: the documented behavior and the real behavior<\/h2>\n\n\n\n
You can organize commands into subdirectories:<\/p>\n\n\n\n
.claude\/commands\/\n\u251c\u2500\u2500 frontend\/\n\u2502   \u251c\u2500\u2500 component.md\n\u2502   \u2514\u2500\u2500 style-check.md\n\u251c\u2500\u2500 backend\/\n\u2502   \u2514\u2500\u2500 db-migrate.md\n\u2514\u2500\u2500 review.md<\/pre>\n\n\n\n
What the current docs say happens: the subdirectory shows up in the command’s description, but the command name is unchanged. frontend\/component.md<\/code> gives you \/component<\/code>, not \/frontend:component<\/code>.<\/p>\n\n\n\n
Older documentation described a colon-namespaced form, \/project:frontend:component<\/code>, and there is an open issue on the Claude Code repo (#2422) from people who tried it, got “command not found,” and reasonably assumed they had misconfigured something. If you read a guide that promises colon namespacing, that guide is describing documentation rather than behavior.<\/p>\n\n\n\n
Which leaves you with a flat namespace, so two commands with the same filename in different subdirectories collide. Prefix the filenames instead \u2014 fe-component.md<\/code>, be-migrate.md<\/code>. Ugly, works today.<\/p>\n\n\n\n
Plugin commands are the exception and are properly namespaced as \/pluginname__commandname<\/code>, which is why installing two plugins that both ship a \/review<\/code> does not break anything.<\/p>\n\n\n\n
One more collision to know about: Claude Code ships bundled skills including code-review<\/code> and verify<\/code>. Create .claude\/commands\/code-review.md<\/code> and yours shadows the bundled one silently. The command list shows the name once and you have no indication which one you are running. If you want your own review workflow, give it a different name. I go through what I actually run before merging agent-written code in this post on AI code review tools<\/a>.<\/p>\n\n\n\n
Restricting tools, and the allowed-tools syntax question<\/h2>\n\n\n\n
allowed-tools<\/code> is the guardrail that makes a read-only command actually read-only. allowed-tools: Read, Grep, Glob<\/code> on an audit command means it physically cannot edit a file, which matters more than a prompt that politely asks it not to.<\/p>\n\n\n\n
Anthropic’s documentation examples use comma-separated lists, including for scoped bash permissions like Bash(git add *), Bash(git status *)<\/code>. Some community guides insist the field is space-separated and that commas silently whitelist nothing. I have not been able to reproduce the silent-failure claim, and the official examples use commas, so commas are what I write. But if you ever hit a command that asks for permission on a tool you explicitly allowed, that is the first line to test \u2014 swap the separator before you go looking for anything more exotic.<\/p>\n\n\n\n
Scoped bash patterns are the part worth getting right. Bash(git:*)<\/code> allows every git subcommand, including git push --force<\/code>. Bash(git add:*)<\/code> and Bash(git commit:*)<\/code> as separate entries is more typing and considerably narrower. If you want enforcement that survives a command file someone edits later, that belongs in hooks rather than frontmatter \u2014 I covered that setup in Claude Code hooks: the guardrails I actually ship<\/a>.<\/p>\n\n\n\n
Running commands without the interactive session<\/h2>\n\n\n\n
You do not have to open a session to fire a command. claude -p '\/lint'<\/code> runs it headless and exits, which makes commands usable from aliases, git hooks, and CI.<\/p>\n\n\n\n
alias clint=\"claude -p '\/lint'\"\nalias ccommit=\"claude -p '\/commit'\"<\/pre>\n\n\n\n
This is where model: haiku<\/code> compounds. A pre-commit alias that runs a Haiku-backed lint-and-fix costs close to nothing and finishes in the time it takes to switch windows. The same alias on a frontier model is a habit you will drop within a week because of the latency.<\/p>\n\n\n\n
Two cautions. Headless runs still hit whatever permissions your settings enforce, so a command that needs approval will hang waiting for an answer nobody is there to give \u2014 allowed-tools<\/code> is not optional in this mode. And if you are wiring this into CI, remember the output is a full model response, not a exit code you can branch on, unless your command explicitly instructs the model to end with a machine-readable line.<\/p>\n\n\n\n
What I would actually build first<\/h2>\n\n\n\n
If you are starting from zero, resist writing fifteen commands in an afternoon. Most of them will never fire. The ones that stuck for me share a shape: repetitive, mechanical, and dependent on context I would otherwise have to paste in by hand.<\/p>\n\n\n\n