Slash commands in Claude Code are reusable prompts saved as markdown files — instead of re-typing "review this PR for security issues and check for N+1 queries" every time, you type /security-check and it runs the same instructions every time, consistently, across every project that has the file.
Why Custom Commands Matter (and When to Skip Them)
Any prompt you catch yourself typing more than twice deserves to become a command. The value isn't just saved keystrokes — it's consistency. A hand-typed review prompt varies slightly every time; a saved command runs the identical checklist whether you're tired at 11pm or sharp at 9am, and your whole team gets the same checklist if you commit it to the repo.
Skip commands for genuinely one-off asks — if you'll never type the same request again, a slash command is unnecessary ceremony.
Getting Started
Commands live as markdown files in .claude/commands/ (project-level, shared via git) or ~/.claude/commands/ (personal, global to every project):
<!-- .claude/commands/security-check.md -->
Review the current diff for:
- SQL injection or unescaped query interpolation
- Missing auth checks on new API routes
- Secrets or tokens committed in plaintext
- Unvalidated user input reaching a database call
Report findings as a list with file:line references. Do not fix anything — report only.
Run it with /security-check from any Claude Code session in that repo. Commands can accept arguments too — reference $ARGUMENTS in the file to receive whatever text follows the command name.
Core Concepts Every Developer Should Know
1. Project vs. personal scope. Project commands in .claude/commands/ get committed and shared — everyone on the team gets the same /deploy-check or /pr-prep. Personal commands in ~/.claude/commands/ are yours alone, good for habits specific to how you work rather than team-wide conventions.
2. Arguments make commands flexible. /fix-issue $ARGUMENTS lets you run /fix-issue 142 and have the command template interpolate the issue number into a broader instruction set that fetches context and starts work.
3. Commands can chain tool use. A command isn't just a static prompt — it can instruct Claude Code to run tests, check git status, or read specific files as part of executing the command, turning a checklist into an actual automated procedure.
4. Namespacing with subdirectories. Organize commands into folders (.claude/commands/git/commit.md) and invoke with /git:commit — useful once you've accumulated more than a handful.
Common Mistakes and How to Fix Them
Mistake 1: Writing commands too vague to be useful. "Review my code" as a command is barely better than typing it fresh — the value is in the specificity of the checklist, not the shortcut itself.
Mistake 2: Keeping useful commands personal instead of committing them. If a command genuinely improves your workflow, it probably helps your whole team — commit it to .claude/commands/ instead of leaving it in your personal config.
Mistake 3: Command sprawl with no organization. A flat folder of forty commands with similar names becomes as hard to navigate as no commands at all. Namespace by category once you pass a dozen.
When Should You Build Custom Commands?
Build one the second time you catch yourself typing a near-identical prompt. Good early candidates: PR review checklists, commit message conventions, deployment pre-flight checks, and security or accessibility audits.
In Practice
On suhailroushan.com's tooling I keep committed commands for /pr-prep, /security-check, and /deploy-check — each one encodes a checklist I'd otherwise half-remember under time pressure. The commands don't do anything I couldn't type manually; they just make sure I actually do it, every time, the same way.
Write down the last review checklist you did from memory, turn it into a command, and never rely on memory for it again.