How Slash Commands Work in Claude Code

"A beginner-friendly walkthrough of built-in commands, custom commands, arguments, frontmatter, and skills. Stop repeating yourself and start building reusable workflows."

Version 1.0.0 • Updated 03/01/2026, 12:00 PM EST

Part 0: Intro

Using Claude Code but still typing the same long prompts every session? This is for you.

What this tutorial will show you is:

• ✅ Understand what slash commands are and how Claude Code finds them
• ✅ Use every built-in slash command effectively
• ✅ Create your own custom commands from scratch
• ✅ Pass dynamic arguments into commands
• ✅ Add frontmatter for advanced control (model selection, tool restrictions)
• ✅ Graduate from commands to skills when you're ready

The Big Idea: A slash command is a saved prompt stored in a Markdown file. Instead of typing a detailed instruction every time you need to do something common, you type /command-name and Claude Code executes it. That's it. No scripting language. No config files. Just Markdown.

What to expect: This is a practical tutorial. By the end, you'll have multiple working slash commands and a clear understanding of when to use project vs. global scope, how arguments work, and when to upgrade to skills.

The Fast Way: Let Claude Code Build It for You

Before we go deep, here's something most people don't realize: you can ask Claude Code to create slash commands for you. You don't have to manually create directories and files. Just tell Claude Code what you want the command to do, and it builds the whole thing.

The Prompt Template

Copy this into your Claude Code session and fill in the blanks:

Create a slash command called /[COMMAND-NAME] that does the following:

[DESCRIBE WHAT THE COMMAND SHOULD DO IN PLAIN ENGLISH]

Requirements:
- Scope: [global (available everywhere) | project (this repo only)]
- Arguments: [yes, describe what the user passes in | no]
- Tool restrictions: [read-only | full access | specific tools]
- Model: [default | claude-opus-4-6 for complex reasoning | claude-sonnet-4-5-20250929 for speed]
- Description for /help: "[SHORT DESCRIPTION]"
Click to copy

Example

Create a slash command called /review that does the following:

Review the current changes in this project. Focus on logic errors, security
issues, and performance concerns. Skip style nits. Prioritize things that
would break in production. Output findings in a table with severity, file,
and recommendation.

Requirements:
- Scope: global (available everywhere)
- Arguments: no
- Tool restrictions: read-only
- Model: claude-opus-4-6 for complex reasoning
- Description for /help: "Run a production-focused code review on current changes"
Click to copy

Claude Code will create the directory if it doesn't exist, write the Markdown file with proper frontmatter, and the command is immediately available. You can type /review right away.

This is the fastest path. If you already know what commands you want, use this template and move on.

The Manual Way: Understanding How It All Works

The rest of this tutorial walks through slash commands from the ground up. If you want to understand how they work under the hood, how the file system is structured, and how to make informed decisions about scope, arguments, frontmatter, and skills, keep reading.

Knowing the mechanics makes you better at designing commands, debugging when something doesn't work, and making architectural decisions for your team.

Tutorial Path

1. Part 1: What Are Slash Commands? (5 min)
2. Part 2: Built-In Commands (5 min)
3. Part 3: Creating Your First Custom Command (10 min)
4. Part 4: Using Arguments (5 min)
5. Part 5: Project vs. Global Commands (5 min)
6. Part 6: Adding Frontmatter (10 min)
7. Part 7: Real-World Command Examples (10 min)
8. Part 8: Skills, The Next Level (10 min)
9. Part 9: Quick Reference (5 min)
10. Part 10: What to Do Next (5 min)

Requirements

• Claude Code installed (requires Anthropic API key or Claude Max subscription): https://docs.anthropic.com/en/docs/claude-code
• Basic comfort with a terminal (you don't need to be a developer)
• A text editor (VS Code, Cursor, vim, whatever you prefer)

Part 1: What Are Slash Commands? (5 min)

The Problem

You use Claude Code regularly. You've noticed you type the same kinds of prompts over and over:

• "Review the current changes for bugs and security issues"
• "Write a commit message for these staged changes"
• "Explain what this codebase does at a high level"

Each one of these is 3-5 lines of instructions. You type them every day. Sometimes multiple times a day.

The Solution

A slash command is a Markdown file that contains a prompt. The filename becomes the command name. You type /filename in your Claude Code session, and the prompt executes.

~/.claude/commands/review.md  →  /review
.claude/commands/commit.md    →  /commit
~/.claude/commands/explain.md →  /explain
Click to copy

No install step. No compilation. You create a .md file in the right folder and it's immediately available.

Two Types

1. Built-in commands that ship with Claude Code (like /help, /clear, /compact)
2. Custom commands that you create yourself (like /review, /commit, /deploy)

Part 2: Built-In Commands (5 min)

What's Available Out of the Box

These commands are available in every Claude Code session without any setup. Type / during a session to see the full list.

When to Use Them

/compact is the one you'll use most. Long Claude Code sessions eat through context fast. When you notice responses getting less coherent or Claude Code "forgetting" things from earlier in the session, run /compact. It compresses the conversation history and frees up context window space.

/init is worth running in every new project. It creates a CLAUDE.md file at the root of your project that gives Claude Code awareness of your project structure, build commands, and conventions. This means Claude Code doesn't have to figure these out from scratch every session.

/install-github-app is underrated. Once installed, Claude automatically reviews your PRs. It catches logic errors and security issues that human reviewers tend to miss. The default review prompt is too verbose. Customize it after install.

Tip: Run /help first in any new project. It shows both built-in and custom commands available in your current directory context.

Part 3: Creating Your First Custom Command (10 min)

Step 1: Create the Directory

Custom commands live in a .claude/commands/ folder. You need to create it first.

For a global command (available everywhere, personal to you):

mkdir -p ~/.claude/commands
Click to copy

For a project command (only works inside this project):

mkdir -p .claude/commands
Click to copy

If you're just getting started, go with global. You can always move commands to project scope later.

Step 2: Create the Markdown File

The filename becomes the command name. Create a file called review.md:

touch ~/.claude/commands/review.md
Click to copy

Open it in your editor and write your prompt:

Review the current changes in this project. Focus on:

1. Logic errors and bugs
2. Security issues (injection, auth bypass, data exposure)
3. Performance concerns
4. Error handling gaps

Skip style nits and formatting opinions. Prioritize things that would break in production.
Click to copy

Save the file.

Step 3: Use It

In your Claude Code session, type:

/review
Click to copy

Claude Code reads the Markdown file and executes the prompt. It reviews whatever changes are present in the current project context.

That's it. You now have a reusable command.

How Claude Code Finds Your Commands

When you type /, Claude Code checks two locations:

1. ~/.claude/commands/ (global commands)
2. .claude/commands/ in your current working directory (project commands)

Every .md file found in those directories becomes an available slash command. No registration, no config file, no restart required.

Part 4: Using Arguments (5 min)

Making Commands Dynamic

Static commands are useful, but many workflows need input. The $ARGUMENTS placeholder lets you pass dynamic values into your commands.

Whatever you type after the command name gets injected where $ARGUMENTS appears.

Example

Create ~/.claude/commands/test.md:

Generate unit tests for the following file: $ARGUMENTS

Requirements:
- Cover happy path and edge cases
- Include error handling scenarios
- Use the testing framework already in the project
- Name test functions descriptively
Click to copy

Usage

/test src/api/auth.py
Click to copy

Claude Code receives the full prompt with src/api/auth.py substituted in place of $ARGUMENTS.

You can pass anything: file paths, topic names, feature descriptions, branch names.

/test src/models/user.py
/test lib/utils/parser.ts
Click to copy

Same command, different targets every time.

Part 5: Project vs. Global Commands (5 min)

Two Scopes

When to Use Each

Global commands are for your personal workflow. Things like:

• /review - your personal code review checklist
• /explain - how you like codebases explained
• /commit - your preferred commit message format

These reflect how you work. They travel with you across every project.

Project commands are for team workflows. Things like:

• /deploy - the deployment procedure for this specific project
• /pr - the PR format and process the team agreed on
• /onboard - instructions for getting a new developer set up

These reflect how the team works. They live in the repo so everyone has access.

Rule of thumb: If it's about how you personally work, make it global. If it's about how the project or team works, make it a project command and commit it.

Priority

If a global and project command have the same name, the project command wins. This lets teams override personal preferences with standardized workflows.

Part 6: Adding Frontmatter (10 min)

What Is Frontmatter?

Frontmatter is optional YAML metadata at the top of your Markdown file, enclosed between --- markers. It gives you fine-grained control over how the command runs.

Available Fields

Example: Security Scan

.claude/commands/security-scan.md:

---
allowed-tools: Read, Grep, Glob
description: Run a read-only security vulnerability scan on the codebase
model: claude-opus-4-6
---

Analyze the codebase for security vulnerabilities including:

1. SQL injection risks
2. XSS vulnerabilities
3. Exposed credentials or API keys
4. Insecure configurations
5. Dependency vulnerabilities

Do not modify any files. Report findings in a table with severity, location, and recommended fix.
Click to copy

Why This Matters

allowed-tools: Read, Grep, Glob means Claude Code can only read files during this command. It cannot write, execute shell commands, or make changes. This is critical for audit-style commands where you want analysis without any side effects.

model: claude-opus-4-6 forces the most capable model. Useful for commands where reasoning quality matters more than speed (security analysis, architecture reviews). For simpler commands, you might use Sonnet to save tokens.

description is a small thing that pays off when your team has 20+ commands. Running /help lists every command with its description so people can find what they need.

When to Use Frontmatter

For simple personal commands, skip it. Frontmatter is most valuable when:

• You're sharing commands with a team (the description helps)
• The command should be read-only (restrict tools)
• The command needs the strongest model for quality (specify model)

Part 7: Real-World Command Examples (10 min)

Here are practical commands you can copy and start using today.

Commit Message Generator

~/.claude/commands/commit.md:

Look at the staged changes (git diff --cached) and write a commit message.

Format:
- First line: type(scope): short description (under 72 chars)
- Blank line
- Body: what changed and why, not how

Types: feat, fix, refactor, docs, test, chore

Do not include anything other than the commit message itself.
Click to copy

Usage: Stage your changes with git add, then type /commit.

Pull Request Creator

.claude/commands/pr.md:

---
description: Generate and open a pull request for the current branch
---

1. Check if a PR already exists for this branch. If so, report it and stop.
2. Compare all commits on the current branch vs. main.
3. Generate a PR with:
   - A clear, descriptive title
   - A summary of what changed and why
   - Testing notes (what was tested, how to verify)
   - Breaking changes (if any)
4. Open the PR using `gh pr create`.
Click to copy

Usage: /pr

Codebase Explainer

~/.claude/commands/explain.md:

Give me a high-level overview of this project:

1. What does it do?
2. What's the tech stack?
3. Directory structure: what lives where?
4. Entry points: where does execution start?
5. Key dependencies and why they're used

Keep it concise. I want orientation, not a deep dive.
Click to copy

Usage: /explain when you open a new or unfamiliar codebase.

Pipeline Fixer

.claude/commands/fix-pipeline.md:

---
description: Fetch failed CI logs and fix the issue
model: claude-opus-4-6
---

1. Run `gh run list --limit 5` to find the most recent failed run.
2. Fetch the logs for the failed run using `gh run view <id> --log-failed`.
3. Read the actual error before proposing any fix.
4. Identify the root cause.
5. Implement the fix.
6. Explain what went wrong and what you changed.
Click to copy

Usage: /fix-pipeline when CI breaks.

Daily Standup Notes

~/.claude/commands/standup.md:

Look at my git log for the last 24 hours across all branches.

Generate a standup update in this format:

**Yesterday:**
- [list of completed work based on commits]

**Today:**
- [infer likely next steps based on branch state and open PRs]

**Blockers:**
- [flag anything that looks stuck: failed CI, merge conflicts, stale PRs]
Click to copy

Usage: /standup at the start of your day.

Part 8: Skills, The Next Level (10 min)

What Changed

Anthropic recently merged slash commands into a broader system called skills. Your existing .claude/commands/ files continue to work exactly the same. Skills just add more capability on top.

What Skills Add

A skill is a directory instead of a single file. The directory contains a SKILL.md entry point plus optional supporting files:

.claude/skills/deploy/
├── SKILL.md          # Main instructions (required)
├── checklist.md      # A pre-deploy checklist template
├── examples/
│   └── sample.md     # Example output showing expected format
└── scripts/
    └── validate.sh   # Script Claude can execute
Click to copy

Key Differences from Plain Commands

Example Skill

.claude/skills/deploy/SKILL.md:

---
name: deploy
description: Handles deployment to staging and production environments.
  Use when the user mentions deploying, releasing, or pushing to production.
---

When deploying, always follow these steps:

1. Run the test suite and confirm all tests pass
2. Check the deploy checklist in checklist.md
3. Run the validation script in scripts/validate.sh
4. Deploy to staging first, verify, then promote to production
5. Update the changelog
Click to copy

The description field does double duty here. It shows in /help, and it also tells Claude Code when to auto-load this skill. If you mention "deploy to production" in conversation, Claude Code can pull in this skill's instructions without you typing /deploy.

Priority Order

If a command and a skill share the same name, the skill wins. The full priority chain:

1. Enterprise skills (if applicable)
2. Personal skills (~/.claude/skills/)
3. Project skills (.claude/skills/)
4. Personal commands (~/.claude/commands/)
5. Project commands (.claude/commands/)

Context Budget

Skill descriptions are loaded into context so Claude Code knows what's available. If you have many skills, they can exceed the character budget. The budget scales at 2% of the context window with a fallback of 16,000 characters. Run /context to check for warnings about excluded skills.

When to Upgrade

Stay with plain .md commands until you need:

• Supporting files (templates, scripts, examples)
• Auto-invocation based on conversation context
• Monorepo-aware command discovery

For most people, plain commands handle 90% of use cases.

Part 9: Quick Reference (5 min)

Command Cheat Sheet

File Naming

• Filename = command name: commit.md becomes /commit
• Use hyphens for multi-word names: fix-pipeline.md becomes /fix-pipeline
• Keep names short and descriptive

Directory Summary

~/.claude/
├── commands/           # Global commands (personal, all projects)
│   ├── review.md
│   ├── commit.md
│   └── explain.md
└── skills/             # Global skills (personal, all projects)
    └── deploy/
        └── SKILL.md

your-project/
├── .claude/
│   ├── commands/       # Project commands (team, this repo only)
│   │   ├── pr.md
│   │   └── fix-pipeline.md
│   └── skills/         # Project skills (team, this repo only)
│       └── test/
│           └── SKILL.md
└── CLAUDE.md           # Project context (generated by /init)
Click to copy

Part 10: What to Do Next (5 min)

Start Small

You don't need 20 commands on day one. Start with one command that saves you the most repetition.

Day 1:

• Create ~/.claude/commands/
• Write one command for something you do every day (review, commit, explain)
• Use it in your next session

Week 1:

• Add 2-3 more commands based on what you find yourself repeating
• Try using $ARGUMENTS in at least one command
• Share a useful project command with your team via .claude/commands/

Week 2:

• Add frontmatter to commands that need tool restrictions or model overrides
• Run /help to see your full command library
• Refine command prompts based on output quality

Week 3+:

• Evaluate if any commands need supporting files (upgrade to skills)
• Build domain-specific commands for different project types
• Review your team's project commands and standardize where it makes sense

The Compounding Effect

Every command you create is a workflow you never have to think about again. A developer with 10 well-crafted slash commands has effectively automated the most tedious parts of their day. The prompts get better over time as you refine them, and new team members get access to battle-tested workflows from day one.

Resources

• Claude Code Docs: https://docs.anthropic.com/en/docs/claude-code
• Slash Commands Reference: https://code.claude.com/docs/en/slash-commands
• Skills Documentation: https://code.claude.com/docs/en/slash-commands
• Community Commands Repo: https://github.com/wshobson/commands