Custom Slash Commands

You write the same prompts over and over. "Review this for security issues." "Write a PR description for these changes." "Run the tests and tell me what failed." Each one takes 10–30 seconds to type well. Multiply by 20 sessions a week and you are spending hours writing prompts you have already written.

Custom slash commands fix this. A well-built command library is a prompt OS — your best instructions, encoded once, fired instantly.

How They Work

Create a markdown file in ~/.claude/commands/. The filename becomes the command name. Type /filename in any Claude Code session and Claude executes the file's contents as a prompt.

mkdir -p ~/.claude/commands
echo "Review the code I've shown you for security issues, performance bottlenecks, and missing error handling." > ~/.claude/commands/review.md

Type /review in any session. Claude reads the file and executes it. That's the entire mechanism.

Project-scoped commands live in .claude/commands/ at the project root. Both scopes coexist, but the docs treat same-name conflicts between user and project commands as unsupported — do not rely on one "winning" over the other. Avoid collisions by naming project commands distinctly. Use project scope for commands that are project-specific — a /seed-db that knows your specific database setup, a /deploy that knows your exact deployment target.

The $ARGUMENTS Placeholder

Commands become dynamic when they accept parameters:

# ~/.claude/commands/debug.md
I need to debug the following issue: $ARGUMENTS

Steps:
1. Search the codebase for the most likely source of this error
2. Identify the specific line(s) causing it
3. Propose a fix with explanation
4. Show me the test that would catch this regression

Type /debug TypeError: Cannot read property 'id' of undefined and Claude receives the full prompt with your error text substituted in. The command encodes the systematic approach; the invocation provides the context.

Building Your Core Command Library

/review — the audit

# ~/.claude/commands/review.md
Review the current state of the code I'm working on.

Check for:
- Security vulnerabilities (injection, auth bypass, exposed secrets)
- Missing or incomplete error handling
- Performance issues (N+1 queries, unnecessary re-renders, large payload sizes)
- Violations of the project conventions in CLAUDE.md
- Functions without tests that should have them

For each issue: severity (critical/major/minor), file and line, what's wrong, and the fix.

/pr-description — PR automation

# ~/.claude/commands/pr-description.md
Generate a pull request description for the changes in this session.

Format:
## Summary
[2-3 bullet points on what changed and why]

## Test Plan
[Bulleted checklist of what to test before merging]

## Notes
[Anything reviewers should know — breaking changes, dependencies, migration steps]

Keep the title under 70 characters. Lead with the verb (feat/fix/refactor/chore).

/test — test runner with reporting

# ~/.claude/commands/test.md
Run the test suite for this project.

1. Execute: npm test (or pytest, or whatever this project uses — check CLAUDE.md)
2. Report: total tests, passing, failing, coverage percentage
3. For any failing tests: paste the error message and identify the root cause
4. If coverage is below 90%, identify the top 3 uncovered modules

/deploy — environment-aware deploy

# ~/.claude/commands/deploy.md
Deploy to $ARGUMENTS (default: staging if no argument given).

Pre-flight:
- Confirm no uncommitted changes (git status)
- Run tests, abort if any fail
- Check CLAUDE.md for deploy commands and constraints

Execute the deploy. Report the URL or service endpoint when complete.

Dynamic Context with ! and @

There is no special "include" directive — the mechanism is bash command execution. A !-prefixed, backtick-wrapped command executes that shell command and inlines its output into the prompt at invocation time. For Claude Code to run it, the command file's frontmatter must grant Bash access via allowed-tools:

---
allowed-tools: Bash(cat:*)
description: Review code against the live project standards
---
# ~/.claude/commands/full-review.md
Review the code against our project standards.

!`cat CLAUDE.md`

Above are our project conventions. Apply them in your review.

Specifically check for: $ARGUMENTS

The backtick syntax executes a shell command and inlines the output. !cat CLAUDE.md`` includes your entire CLAUDE.md in the prompt at invocation time. Use this when a command needs live data — the current git diff, a config file, a recent log — rather than static text. Without the allowed-tools grant, the ! line will not execute.

Frontmatter and @-file references. Command files support YAML frontmatter: description (shown in the command menu), argument-hint (autocomplete hint for $ARGUMENTS), model (pin a specific model for this command), and allowed-tools (the tool grants required for ! execution). You can also reference files directly with @ — writing @src/utils/helpers.js in a command includes that file's contents in the prompt with no shell command needed.

Commands are the planning. The / is the execution. Do the planning once, execute it infinitely.

Command Naming Conventions

Verbs, not nouns. /review not /reviewer. /deploy not /deployment. Commands are actions.

Keep names short — you type them. /pr-description is fine. /generate-pull-request-description-with-full-context is not.

Use project commands for project-specific things. Your global /review should work anywhere. Your /migrate-db only makes sense in one project — put it in .claude/commands/, not ~/.claude/commands/.

Discovering What to Automate

Three signals that a command is worth creating:

1. You typed the same prompt more than three times. If you are writing the same instructions repeatedly, it is a command.
2. The prompt encodes standards. If the prompt reflects your quality standards or conventions, a command ensures those standards are consistently applied.
3. You have to think about how to phrase it. If you have to think about how to ask Claude to do something you do regularly, that thinking should happen once and be encoded.

Lesson Drill

Create three commands today:

1. /review — your actual review standards, not generic advice
2. /pr-description — your preferred PR format
3. One project-specific command in .claude/commands/ for your current project

Use each one in a session. Iterate on the prompt based on what Claude does. Within a week, your command library will feel indispensable.

Bottom Line

Custom slash commands are reusable prompts — ~/.claude/commands/ for global, .claude/commands/ for project-scoped. Filename becomes the command. $ARGUMENTS accepts runtime parameters. ! executes shell commands inline. Build a library of your best prompts — /review, /pr-description, /test, /deploy. Encode your standards, not generic advice. Version-control the library, share it across machines. Every command you build is permanent leverage: written once, used in every session for the rest of your career.