Custom Slash Commands

Claude Code includes a set of built-in slash commands that give you quick access to common actions. Beyond those, you can create your own custom slash commands to automate workflows specific to your project or personal preferences. In this lesson, you will learn every built-in command and how to build powerful custom ones.

What You Will Learn

• All built-in slash commands and when to use them
• How to create custom slash commands for your project
• The command file format and argument placeholders
• Project-level vs user-level custom commands
• Practical examples you can use immediately

---

Built-In Slash Commands

Claude Code comes with several slash commands out of the box. You can use them by typing a forward slash followed by the command name during a session.

/help

Displays a list of available commands and general usage information. This is your go-to when you forget a command name.

> /help

This shows all built-in commands, their descriptions, and any custom commands you have configured.

/clear

Clears the current conversation context and starts fresh. Use this when you want to switch to a completely different task without leftover context from the previous conversation.

> /clear

This does not close your Claude Code session -- it just resets the conversation history. Your CLAUDE.md context is reloaded automatically.

/compact

Compresses the current conversation to save context window space. When you have been working on a long task and Claude Code's responses start feeling less focused, compacting the conversation helps it retain the most important information while freeing up space.

> /compact

You can also provide an optional instruction to guide what should be preserved:

> /compact Focus on the database migration we are working on

This tells Claude Code to prioritize keeping context about the database migration while summarizing or dropping less relevant conversation history.

/cost

Shows how many tokens you have used in the current session and the estimated cost. This is useful for monitoring your API usage, especially on longer sessions.

> /cost

The output shows input tokens, output tokens, and the total cost for the current session.

/doctor

Runs a diagnostic check on your Claude Code installation. Use this when something is not working correctly -- it verifies your configuration, authentication, and environment.

> /doctor

This checks things like:

• Whether your API key or authentication is valid
• Whether your Node.js version is compatible
• Whether required dependencies are installed
• Whether your configuration files are well-formed

/init

Analyzes your project and auto-generates a CLAUDE.md file. This is the fastest way to bootstrap project context for Claude Code.

> /init

Claude Code will examine your repository structure, package files, build scripts, and existing documentation to create a comprehensive CLAUDE.md. You should always review and customize the generated file, but it provides an excellent starting point.

If a CLAUDE.md already exists, /init will offer to update it rather than overwrite it.

/review

Triggers a code review workflow. Claude Code examines your recent changes (typically the current git diff) and provides feedback on code quality, potential bugs, and improvement suggestions.

> /review

This is particularly powerful after you have made a series of changes and want a second opinion before committing. Claude Code looks at your staged and unstaged changes and provides structured feedback covering:

• Potential bugs or logic errors
• Code style issues
• Performance concerns
• Security considerations
• Suggestions for improvement

You can also direct the review to focus on specific aspects:

> /review Focus on security and input validation

/bug

Launches a bug-finding workflow. Claude Code systematically searches for bugs in your codebase or recent changes.

> /bug

This is different from /review in that it is specifically focused on finding defects rather than providing general code quality feedback. Claude Code will look for:

• Null reference errors
• Off-by-one errors
• Unhandled edge cases
• Race conditions
• Resource leaks
• Logic errors

You can narrow the scope:

> /bug Check the authentication middleware for security issues

---

Custom Slash Commands

Built-in commands cover general workflows, but every project has its own repetitive tasks. Custom slash commands let you define reusable prompts that you or your team can invoke with a simple slash command.

How Custom Commands Work

A custom slash command is simply a markdown file placed in a special directory. The filename becomes the command name, and the file contents become the prompt that is sent to Claude Code when you invoke the command.

Creating Your First Custom Command

Let us create a command that runs your test suite and fixes any failures. Create a file at .claude/commands/fix-tests.md in your project:

mkdir -p .claude/commands

Then create the file .claude/commands/fix-tests.md with this content:

Run the test suite using `npm test`. If any tests fail, analyze the failures
and fix the underlying code (not the tests) to make them pass. After making
fixes, run the tests again to confirm they pass. Repeat until all tests pass.

Now you can use this command in any Claude Code session within your project:

> /project:fix-tests

Claude Code reads the markdown file and executes the instructions as if you had typed them manually.

The $ARGUMENTS Placeholder

Custom commands can accept arguments using the $ARGUMENTS placeholder. This makes commands flexible and reusable.

Create .claude/commands/explain.md:

Explain the following file or code in detail, including:
- What it does at a high level
- Key functions and their purposes
- Any notable patterns or design decisions
- Potential issues or improvements

File or topic to explain: $ARGUMENTS

Now you can use it with different arguments each time:

> /project:explain src/auth/middleware.ts
> /project:explain the database connection pooling logic
> /project:explain src/utils/cache.ts

The $ARGUMENTS placeholder is replaced with whatever text follows the command name.

---

Project-Level vs User-Level Commands

Custom commands can live in two locations, similar to CLAUDE.md files.

Project-Level Commands

Stored in your project's .claude/commands/ directory:

my-project/
  .claude/
    commands/
      fix-tests.md
      deploy.md
      review-pr.md

These commands are available to anyone who works on the project (if the .claude/ directory is committed to the repository). They are invoked with the /project: prefix:

> /project:fix-tests
> /project:deploy
> /project:review-pr

User-Level Commands

Stored in your home directory at ~/.claude/commands/:

~/.claude/
  commands/
    my-style.md
    explain.md
    refactor.md

These are personal commands available across all your projects. They are invoked with the /user: prefix:

> /user:my-style
> /user:explain src/index.ts
> /user:refactor

User-level commands are ideal for personal preferences and workflows that you use regardless of the project.

---

Practical Examples of Custom Commands

Here are several custom commands that demonstrate common use cases. You can adapt these to your own projects.

Deploy Command

.claude/commands/deploy.md:

Prepare the project for deployment by doing the following:

1. Run the linter: `npm run lint` -- fix any issues found
2. Run the type checker: `npm run typecheck` -- fix any type errors
3. Run the test suite: `npm test` -- fix any failures
4. Create a production build: `npm run build` -- fix any build errors
5. If everything passes, summarize what was checked and confirm
   the project is ready for deployment

Do NOT actually deploy. Just verify everything is ready.

Usage:

> /project:deploy

Test All Command

.claude/commands/test-all.md:

Run a comprehensive testing pass:

1. Run unit tests: `npm test`
2. Run type checking: `npm run typecheck`
3. Run linting: `npm run lint`

For each step, report the results. If anything fails, provide a summary
of all failures at the end but do NOT attempt to fix them automatically.

$ARGUMENTS

Usage:

> /project:test-all
> /project:test-all Also check for console.log statements that should be removed

Release Notes Command

.claude/commands/release-notes.md:

Generate release notes based on the git log. Compare the current branch
against the main branch:

1. Run `git log main..HEAD --oneline` to get the list of commits
2. Group the commits into categories:
   - Features (new functionality)
   - Bug Fixes (error corrections)
   - Improvements (refactoring, performance, DX)
   - Documentation (docs changes)
3. Write concise, user-friendly release notes in markdown format
4. Include the date range covered

Additional instructions: $ARGUMENTS

Usage:

> /project:release-notes Format for a GitHub release
> /project:release-notes Include migration steps for breaking changes

Create Component Command

.claude/commands/create-component.md:

Create a new React component based on the following requirements.

Follow our project conventions:
- Use TypeScript with a Props interface
- Use named exports (no default export)
- Place the component in src/components/
- Create a corresponding test file in __tests__/
- Use Tailwind CSS for styling
- Include JSDoc comments on the component and its props

Component requirements: $ARGUMENTS

Usage:

> /project:create-component A responsive pricing card that shows plan name, price, features list, and a CTA button

Database Migration Command

.claude/commands/migrate.md:

Create a database migration for the following change:

1. Modify the Prisma schema in `prisma/schema.prisma` as needed
2. Run `npx prisma migrate dev --name $ARGUMENTS` to generate the migration
3. Review the generated SQL in `prisma/migrations/`
4. Run `npx prisma generate` to update the Prisma client
5. If there are any existing queries or types that need updating
   based on the schema change, identify and update them

Migration description: $ARGUMENTS

Usage:

> /project:migrate add-user-avatar-field
> /project:migrate create-comments-table

---

Tips for Effective Custom Commands

Keep Commands Focused

Each command should do one thing well. Instead of a single mega-command that tests, lints, deploys, and notifies, create separate commands for each step.

Use Clear Step-by-Step Instructions

Claude Code follows instructions best when they are numbered and explicit. Instead of "make sure everything works," specify exactly which commands to run and in what order.

Include Error Handling Instructions

Tell Claude Code what to do when something fails:

Run `npm test`. If tests fail:
- If the failure is in test code, fix the test
- If the failure is in application code, fix the application code
- If the failure is environmental (missing env var, port in use), report
  the issue and stop

Commit Commands to Your Repository

Project-level commands in .claude/commands/ should be committed to git. This way, every team member has access to the same commands and they stay in sync with the project.

git add .claude/commands/
git commit -m "Add custom Claude Code commands for team workflows"

Document Your Commands

Add a note in your CLAUDE.md about available custom commands:

## Custom Commands

- `/project:fix-tests` - Run tests and fix any failures
- `/project:deploy` - Pre-deployment checklist
- `/project:release-notes` - Generate release notes from git log
- `/project:create-component` - Scaffold a new React component

This helps team members discover what commands are available.

---

Command Discovery

When you are in a Claude Code session, you can discover available commands in several ways:

# See all available commands
> /help

# Start typing to see matching commands
> /project:     # Shows all project-level commands
> /user:        # Shows all user-level commands

Claude Code also supports tab completion for command names, making it fast to find and invoke commands.

---

Summary

Slash commands are a powerful way to interact with Claude Code efficiently. The built-in commands (/help, /clear, /compact, /cost, /doctor, /init, /review, /bug) cover essential workflows, while custom commands let you automate project-specific tasks with simple markdown files. By placing command files in .claude/commands/ at the project level or ~/.claude/commands/ at the user level, you create reusable, shareable workflows that save time and ensure consistency across your team.

In the next lesson, we will explore MCP servers -- a way to connect Claude Code to external tools and data sources like databases, GitHub, and more.