Claude Code Slash Commands Tutorial: Custom Commands Guide (2026)

What Are Claude Code Slash Commands?

A slash command is a typed shortcut that begins with a forward slash and executes a predefined prompt or session action. Where a normal prompt asks Claude to perform a coding task, a slash command often controls the Claude Code session itself -- things like compacting context, checking cost, running a stored workflow, or toggling a mode.

According to the Claude Code documentation, slash commands come in two flavors: built-in commands that ship with Claude Code, and custom commands that live in .claude/commands/ folders. Both feel identical to use. You type a slash, pick a command, and press enter.

Explicit trigger

Unlike skills, slash commands only run when you type them. Predictable. No surprise activations.

Shareable

Project commands live in git. Clone the repo, get the commands. Zero onboarding overhead.

Argument-aware

Pass text after the command name. Use $ARGUMENTS, $1, $2 to interpolate it into the prompt.

Tool-scoped

Frontmatter can restrict which tools the command is allowed to call. Safety on rails.

Built-In Slash Commands You Use Daily

Claude Code ships with dozens of built-in commands. You do not need to memorize them -- type /help to list every command available in the current session. These five are the ones you will reach for on day one.

Command	Purpose	When to use
`/init`	Generates CLAUDE.md from the codebase	First time you open a repo
`/help`	Lists every available command	When you forget a command name
`/compact`	Compresses conversation history	Long sessions near context limit
`/cost`	Shows token usage and spend	Check before running big tasks
`/review`	Runs the built-in code review skill	Before opening a PR

Bundled skills like /simplify, /debug, and /loop also appear as slash commands. They behave the same way.

Where Custom Slash Commands Live

Custom slash commands are just Markdown files. The folder they live in determines whether they are project-specific or global, and whether they are shared with teammates.

Location	Scope	Shared via git?
`.claude/commands/`	Current project	Yes (commit the folder)
`~/.claude/commands/`	All projects on this machine	No (personal only)
`.claude/commands/team/`	Current project (namespaced)	Yes, appears as /team:name

Subfolders become namespaces. A file at .claude/commands/db/migrate.md registers as /db:migrate. Use namespaces to group related commands and keep the root tidy.

Create Your First Custom Slash Command

The fastest way to feel how slash commands work is to create one. This example builds a /review command that runs a structured code review on uncommitted changes. Four commands and one Markdown file.

1. Create the folder

From the project root, make the commands directory. This works even if the repo has no prior Claude Code config.

mkdir -p .claude/commands

2. Create the Markdown file

The filename, minus the extension, becomes the command name. So review.md becomes /review.

touch .claude/commands/review.md

3. Write the prompt

Paste this into the file. The frontmatter up top is optional but recommended -- it teaches Claude which tools the command needs and gives teammates a one-line description.

---
description: Review uncommitted changes for bugs and style issues
allowed-tools: [Bash, Read, Grep]
---

Review the uncommitted changes on this branch.

1. Run `git diff` to see what changed.
2. For each file, flag bugs, security issues, and style violations.
3. Suggest concrete fixes with file:line references.
4. Summarize the review in three bullets at the end.

4. Run it

Open Claude Code in the project. Type / to see the autocomplete list. Your new /review should appear. Press enter and watch it run.

Frontmatter: Configure Tools, Model, Description

Frontmatter is the YAML block at the top of the Markdown file. It tells Claude Code how to run the command. Five fields cover 95% of real-world use.

Field	What it does
`description`	One-line summary shown in /help and autocomplete
`allowed-tools`	Array of tool names the command may call (Read, Edit, Bash, etc.)
`model`	Override the session model (e.g. claude-haiku-4-5 for cheap routing)
`argument-hint`	Example placeholder shown in autocomplete (like [file path])
`disable-model-invocation`	If true, only the user can trigger the command -- not the model

The most valuable field in practice is allowed-tools. A command scoped to just [Read, Grep] physically cannot edit files, which is perfect for read-only investigators like /explain.

Using $ARGUMENTS and Positional Arguments

Static prompts are useful. Dynamic prompts are transformative. Slash commands support two argument styles: all-text capture with $ARGUMENTS and positional capture with $1, $2, and so on.

$ARGUMENTS -- capture everything

Use when the argument is a free-form sentence or commit message. Typing /ship fixes the login redirect bug passes the whole string.

---
description: Commit, push, and open a PR
---

Commit the current changes with this message: $ARGUMENTS

Then push and open a pull request.

$1, $2 -- positional arguments

Use when the command expects a fixed number of inputs. Running /rename oldFn newFn maps to $1=oldFn, $2=newFn.

---
description: Rename a symbol across the whole repo
argument-hint: [old_name] [new_name]
---

Rename every reference to `$1` to `$2` across the codebase.

Update tests and type definitions too. Run the build afterward.

The complete playbook

Every slash command pattern, every frontmatter field, and the reasoning behind each decision in the full KaiShips Guide.

This post covers slash commands. The guide covers CLAUDE.md architecture, memory systems, subagents, cron automation, MCP servers, hooks, and 5 more chapters of production-tested configs.

Get the KaiShips Guide -- $29

Slash Commands vs Skills vs Subagents

Claude Code has three overlapping extension mechanisms, and most new users conflate them. The difference comes down to who triggers the behavior and how much autonomy it carries.

Mechanism	Trigger	Best for
Slash command	Explicit user input	Canned prompts and workflows
Skill	User OR model (auto)	Reusable expertise with metadata
Subagent	Model dispatches it	Isolated, long-running tasks

●Use slash commands for muscle-memory workflows. /ship, /review, /test -- anything you type twice a day.
●Use skills when you want Claude to reach for the workflow without you naming it. Bundle the same file as a skill if auto-invocation helps.
●Use subagents for heavy research or parallel branches where you want a clean context window.

7 Production-Ready Custom Slash Commands

These are the commands on my own machine. Each one replaces a prompt I used to type three times a day. Copy them into .claude/commands/ and adjust as needed.

SHIP

/ship -- commit, push, open PR

Runs git status + diff + log, drafts a conventional commit message, pushes to origin, and opens a PR with gh. The all-in-one end-of-feature command.

REVIEW

/review -- structured code review

Reads the diff on the current branch and flags bugs, perf issues, and missing tests with file:line references. Scoped to Read, Grep, Bash only.

TEST

/test -- run and fix failing tests

Runs the test suite, parses failures, and proposes minimal fixes. Uses positional $1 for optional test file or pattern.

EXPLAIN

/explain -- read-only code walkthrough

Takes a file or function name and produces a line-by-line explanation with references to related code. Scoped to Read and Grep so it cannot accidentally edit anything.

FIX

/fix -- bug fix with root-cause analysis

Takes a bug description as $ARGUMENTS, reproduces it, finds the root cause, ships the fix, and writes a regression test. Invokes the systematic-debugging skill internally.

DOCS

/docs -- keep the README honest

Scans the code for new CLI flags, env vars, or endpoints and updates README.md to match. Perfect for end of sprint cleanup.

DEBUG

/debug -- structured stack trace triage

Paste a stack trace as $ARGUMENTS. Returns the likely cause, the exact file and line, and the minimal patch. Runs on Haiku via model override for a faster turnaround.

Share Slash Commands With Your Team

The simplest way to standardize how a team uses Claude Code is to commit the .claude/commands/ folder. Everyone who clones the repo inherits every command instantly -- no setup, no docs, no training.

Namespace by team

Organize commands into subfolders like .claude/commands/frontend/ and .claude/commands/infra/. They show up as /frontend:name, /infra:name.

Require a description

Commands without a description field show up as blank rows in /help. Make it a PR review rule: no command merges without a one-line description.

Review tool access

Treat allowed-tools like a scope review. A command that touches production config should not have Bash enabled unless it needs it.

Troubleshooting Common Slash Command Issues

Four issues account for almost every "my command is not working" question. Check these in order before digging deeper.

●Command missing from /help. Restart Claude Code after creating the file. The command registry loads at session start.
●Wrong directory. Verify the file is in .claude/commands/ at the project root or ~/.claude/commands/, not inside a nested folder you forgot about.
●Broken frontmatter. YAML is whitespace-sensitive. Missing dashes or stray tabs can silently disable the command. Validate with a YAML linter.
●Tool blocked. If the command runs but fails halfway, check allowed-tools. A command missing Bash cannot run shell commands even if the prompt asks for it.

Frequently Asked Questions

What are Claude Code slash commands?

Claude Code slash commands are typed shortcuts that start with a forward slash and execute a predefined prompt or session action. Built-in commands like /init, /compact, /help, and /cost ship with Claude Code. Custom commands live as Markdown files in .claude/commands/ or ~/.claude/commands/ and become reusable prompts you can trigger by name.

Where do I save custom slash commands?

Save project-specific commands in .claude/commands/ inside your repository root, which lets you share them via git. Save personal commands that work in every project in ~/.claude/commands/. The filename without the .md extension becomes the command name, so .claude/commands/review.md becomes /review.

How do slash commands accept arguments?

Use $ARGUMENTS in the command body to capture everything after the command name, or use positional variables like $1 and $2 to pull specific arguments. For example, /ship fix login bug with $ARGUMENTS would substitute 'fix login bug' into the prompt before sending it to Claude.

What is the difference between slash commands and skills?

Slash commands are explicit triggers -- you type the command and it runs the prompt. Skills extend that idea with auto-discovery, allowing Claude to invoke the skill autonomously when the task matches. Skills live at .claude/skills/<name>/SKILL.md and support the same slash-command invocation plus model-initiated activation.

Can I limit which tools a slash command uses?

Yes. Add an allowed-tools field to the YAML frontmatter at the top of the Markdown file. For example, allowed-tools: [Read, Grep, Bash] restricts the command to those tools only. You can also set model: claude-haiku-4-5 to route the command to a faster model.

Can I share slash commands with my team?

Yes. Commit the .claude/commands/ folder to git. Every developer who clones the repository gets the same custom commands immediately. This is the standard way to ship team-wide workflows, review templates, and PR automation with Claude Code.

Keep Reading

Slash commands are one layer of the Claude Code toolkit. These guides cover the rest.