If there’s a prompt you type into Claude Code over and over — “review this for security issues,” “write a conventional commit message for the staged changes,” “explain this module to a new hire” — a custom slash command turns it into a single /name you trigger instantly. It’s the simplest customization in Claude Code: a markdown file whose contents become a prompt.
This walks through creating commands, passing arguments, organizing them into groups, and the one distinction that trips people up — when to use a command versus a skill. By the end you’ll have a couple of working commands and know where each kind of shortcut fits.
For the broader set of features this sits among, see the power-user guide.
The basics: a file is a command
A slash command is a markdown file. The location decides its scope, and the filename becomes the command name:
Command locations
| .claude/commands/ | Project commands — committed, shared with the team |
|---|---|
| ~/.claude/commands/ | Personal commands — follow you across projects |
Create one:
mkdir -p .claude/commands
echo "Review the staged changes for bugs, missing error handling, and security issues. Rank findings by severity." > .claude/commands/review.mdOn Windows in PowerShell, the user path is C:\Users\YourName\.claude\commands\. Now in a Claude Code session, type /review and the file’s contents run as your prompt. That’s the whole mechanism — the file is the prompt.
Passing arguments
A static prompt only goes so far. To handle variable input, use the arguments placeholder so whatever you type after the command name gets inserted:
Look at GitHub issue #$ARGUMENTS in this repo. Find the relevant code,
explain the likely cause, and propose a fix on a new branch.Now /fix-issue 482 runs the prompt with 482 substituted in. One command, any issue number. This is what turns a command from a fixed snippet into a small reusable tool.
Organizing with namespaces
As your command set grows, group related ones in subdirectories. The subfolder namespaces the command:
.claude/commands/
git/
review.md -> /git:review (grouped under git)
pr-desc.md -> /git:pr-desc
docs/
update.md -> /docs:updateNamespacing keeps the slash menu readable when you’ve got fifteen commands instead of three. Group by area — git, docs, testing, deploy — so you and your team can find them.
Command vs skill: the distinction that matters
This is the question people get stuck on, because commands and skills overlap. Both run instructions. The difference is who decides when they run.
Slash command vs skill
| Slash command | Runs only when you type it. Same prompt every time. You're in control. |
|---|---|
| Skill | Claude applies it automatically when a task matches the description. |
| Use a command when | You want a prompt on demand, triggered deliberately |
| Use a skill when | You want Claude to follow a convention without being asked |
Concrete version: a /deploy-checklist command that walks through your release steps is something you fire on purpose, so it’s a command. “Always format commit messages our way” is something you want applied whenever Claude writes a commit, so it’s a skill. If you want explicit control, use a command. If you want automatic behavior, use a skill. The full comparison is in skills vs MCP vs subagents.
Useful commands to build
A few that earn their place in most projects:
/review— your code-review prompt, applied to the current changes./commit— generate a commit message in your team’s format./explain— explain a file or module for someone new, taking the path as an argument./test— write tests for the given file following your conventions./pr-desc— draft a pull request description from the branch’s changes.
Write a git commit message for the staged changes.
Use Conventional Commits: type(scope): subject.
Imperative mood, subject under 72 characters, no trailing period.
Add a short body only if the change needs context.Creating your first commands
- Create .claude/commands/ in your project
- Add a markdown file named for the command (review.md → /review)
- Use the arguments placeholder for commands that take input
- Group related commands in subdirectories
- Commit project commands; keep personal ones in ~/.claude/commands/
- Reach for a skill instead when you want automatic behavior
Wrapping up
Custom slash commands are the fastest way to stop retyping the same prompts. Drop a markdown file in .claude/commands/, name it for the command, add an arguments placeholder if it needs input, and you’ve got a reusable shortcut. Reserve them for prompts you trigger deliberately, and use skills when you want Claude to apply something on its own.
For commands worth copying and the patterns that work best, see the best Claude Code slash commands.
