Slash Commands: Built-in and Custom

A slash command is text entered at the beginning of a message after the / character. It's a minimal interface for invoking anything: built-in CLI logic, a prompt template, or an entire analysis script. Everything written after the command name is automatically passed to it as arguments.

By nature, commands fall into two types: built-in — hardcoded into the CLI and executing fixed logic — and custom (also called skills) — simply a Markdown file with instructions that Claude reads and executes. The distinction is fundamental: the built-in /clear command immediately clears the context without involving the model; a custom /deploy command makes Claude read your Markdown and carry out its instructions as a regular prompt.

Built-in Commands: A Complete Overview

Claude Code has dozens of built-in commands. Type / on an empty line to open an interactive, searchable list. Commands are easiest to understand when grouped by purpose.

Session and Context Management

Model and Modes

Code Quality

Parallel Work and Background Tasks

Infrastructure and Settings

A separate category is built-in skills, marked in the docs as Skill: /debug, /loop, /run, /verify, /code-review, /batch, /claude-api. Technically these are not hardcoded — they are prompt files that Anthropic ships out of the box. They work exactly like custom skills, except they are not visible in your .claude/.

Custom Commands: Two Syntaxes, One Logic

Any Markdown file placed in the right location automatically becomes a slash command. There are two approaches:

Classic — a file inside .claude/commands/:

.claude/commands/deploy.md  →  /deploy

New — a directory inside .claude/skills/:

.claude/skills/deploy/SKILL.md  →  /deploy

Both work the same way. The difference: a skill directory can contain auxiliary files, templates, and scripts. A file in commands/ is always a single file. The official recommendation: use .claude/skills/ for new commands and leave existing .claude/commands/ entries as-is — they still work.

The storage location determines the scope:

File Structure: Frontmatter and Body

The file consists of a YAML block between --- delimiters and a Markdown instruction body:

---
name: Deploy to staging
description: Deploy the application to the staging environment. Use when the user asks to deploy, push to staging, or release a build.
disable-model-invocation: true
argument-hint: [branch]
arguments: branch
allowed-tools: Bash
---

Deploy the branch `$branch` to staging:

1. Run `npm test` — stop if tests fail
2. Build: `npm run build`
3. Deploy: `./scripts/deploy.sh staging $branch`
4. Report the deployment URL

Key frontmatter fields:

description — the most important field. Claude reads it to decide whether to load the skill automatically (without an explicit /). Be specific: "when the user asks to deploy, push to staging, or release a build." Without description, Claude uses the first paragraph of the body.

disable-model-invocation: true — prevents Claude from invoking the skill automatically. Only an explicit /deploy will trigger it. Required for destructive operations — deployment, publishing, git push.

argument-hint — a hint string shown in autocomplete: [branch], [issue-number], [filename] [format].

arguments — names for positional arguments. With arguments: [issue, branch] you can write $issue and $branch instead of $0 and $1.

allowed-tools — tools that are permitted without a permission prompt while this skill is active: Read Grep Bash.

context: fork — runs the skill in an isolated subagent (a separate context window).

model / effort — override the model and thinking level for this skill. After the skill completes, the session defaults are restored.

paths — glob patterns. The skill is loaded automatically only when working with files that match the pattern: "src/api/**".

Argument Substitution

When you type /review-pr 123, everything after the command name goes into the $ARGUMENTS variable. This string is substituted into the skill body before Claude reads it:

---
description: Review a GitHub pull request by number
argument-hint: <pr-number>
---

Review PR #$ARGUMENTS:
1. Fetch it with `gh pr view $ARGUMENTS --json title,body,files`
2. Analyze the diff for bugs and style issues
3. Summarize: what changed, risks, suggested improvements

For multiple arguments — use named variables or positional indices:

---
arguments: [filename, format]
---

Convert `$filename` to `$format`.
# Or: $ARGUMENTS[0] and $ARGUMENTS[1]
# Or: $0 and $1

A multi-word argument should be quoted: /convert "src/api.ts" markdown.

There are also system substitutions:

• ${CLAUDE_SESSION_ID} — current session ID (for logs, temporary files)
• ${CLAUDE_EFFORT} — current thinking level
• ${CLAUDE_SKILL_DIR} — path to the skill directory (for references to auxiliary files)

Dynamic Context: !command

The most powerful feature of skills is inline shell command execution directly inside the skill body. Claude Code runs the command before the model reads the prompt and inserts the output in place of that line:

---
description: Summarize uncommitted changes and flag risks
---


::widget{id="rc-3"}


::widget{id="rc-2"}


::widget{id="rc-1"}

## Current diff

!`git diff HEAD`

## Instructions

Summarize the changes above in 2-3 bullets. Flag any risks: missing error
handling, hardcoded values, tests that need updating. If diff is empty, say so.

Now $ARGUMENTS is not needed — Claude receives the live git diff in context rather than having to ask you to paste it manually.

Practical examples:

# Insert the current branch
!`git branch --show-current`

# List open issues
!`gh issue list --limit 10 --json number,title`

# Test status
!`npm test -- --passWithNoTests 2>&1 | tail -20`

Dynamic context is especially valuable for skills that Claude should invoke automatically — when the description matches your request, the model receives up-to-date data without any extra steps on your part.

Real-World Examples of Custom Commands

/fix-issue — fetch a task from the tracker and put it in context

---
description: Fetch a GitHub issue and start working on it
argument-hint: <issue-number>
arguments: issue
---

## Issue #$issue

!`gh issue view $issue --json title,body,comments`

Analyze the issue above. Understand what needs to be done, find the relevant
code, and make a plan. Ask for confirmation before making changes.

/commit — commit following the convention

---
description: Create a conventional commit for staged changes. Use when user asks to commit.
disable-model-invocation: true
allowed-tools: Bash
---

## Staged changes

!`git diff --cached`

Write a conventional commit message (feat/fix/docs/refactor/test/chore) for
these changes. Run `git commit -m "<message>"`. No confirmation needed.

/daily-standup — generate a standup from git history

---
description: Generate a standup update from recent git activity
---

## My activity (last 24h)

!`git log --since='24 hours ago' --author='$(git config user.email)' --oneline`

## Open PRs

!`gh pr list --author @me --json title,state,reviewDecision`

Based on the above, write a concise standup (3-5 bullets): what I did,
what I'll do today, any blockers.

Custom Command vs Skill vs Subagent vs Hook

A slash command is the lightest-weight customization mechanism. The choice is straightforward:

• A recurring request you're tired of typing manually → custom command / skill
• Need context isolation or parallel execution → Subagents and Context Isolation
• Need a deterministic response to an event (file saved, Claude finished responding) → Hooks — Lifecycle Events
• Need portable expertise with auxiliary files → Skills — Portable Capabilities

Slash commands don't execute logic — they pass a prompt to the model. If you need branching, loops, or working with multiple tools in parallel, that calls for a skill with context: fork or a subagent. The decision matrix is covered in detail in What to Choose: Command, Skill, Subagent, MCP, or Hook.

See also

• Skills — Portable Capabilities — advanced features: auxiliary files, auto-invocation, progressive loading
• Subagents and Context Isolation — when you need context isolation rather than just a prompt template
• Hooks — Lifecycle Events — deterministic shell commands on events, as opposed to prompt-based commands
• What to Choose: Command, Skill, Subagent, MCP, or Hook — the decision matrix for all extensibility mechanisms
• CLAUDE.md and the Memory System — the difference between instructions in CLAUDE.md and moving procedures into commands
• Headless Mode and CLI Scripting — how -p interacts with custom commands in CI
• Plugins and Marketplace — how to bundle commands together with hooks and MCP servers into a single versioned package