Define reusable slash commands as Markdown files, share them across the team via git, and cover high-frequency tasks like code review, test generation, and PR descriptions.
Claude Code ships with a handful of built-in slash commands — /help, /clear, /compact. But the ones that actually speed up your workflow are the ones you write yourself.
This article is about designing a reusable slash command system — so everyone on your team can share the same prompt library instead of reinventing task descriptions from scratch every time.
In Claude Code, a custom slash command is just a Markdown file. Drop it in the right directory, Claude Code picks it up on startup, and typing /filename triggers it.
The file's content is the prompt sent to Claude. That's it.
No special syntax, no config format — one .md file is one command.
Two locations, two purposes:
| Location | Path | Scope |
|---|---|---|
| Project-level | .claude/commands/ |
Current project only, can be committed to git |
| User-level | ~/.claude/commands/ |
All projects, personal |
Project-level is the core of team sharing. Commit .claude/commands/ to git and everyone who clones the repo gets the full command set automatically.
User-level is for personal habits — your preferred code style checks, or tool integrations only you use.
From the project root:
mkdir -p .claude/commands
Create .claude/commands/review.md:
Review the quality of the current changes. Focus on:
1. Logic errors and edge cases
2. Whether naming is clear
3. Any duplicate code worth extracting
4. Security issues (SQL injection, XSS, exposed secrets)
Give specific, actionable suggestions — not generic advice.
Restart Claude Code and type /review to trigger it.
Fixed-content commands have limited use. $ARGUMENTS makes commands flexible — whatever the user types after /command gets substituted into the prompt.
Example .claude/commands/test.md:
Write tests for the following: $ARGUMENTS
Requirements:
- Cover the happy path and edge cases
- Test names should be self-explanatory
- Use real data instead of mocks where possible
Usage:
/test the login method on the UserAuthentication class
Claude receives:
Write tests for the following: the login method on the UserAuthentication class
Requirements:
...
$ARGUMENTS can appear anywhere in the prompt and can be used multiple times.
One command, one responsibility
Don't write a catch-all command that handles everything. /review is for code review, /test is for writing tests, /pr is for PR descriptions. Narrow commands are easier to remember and easier to reuse.
Write concrete prompts, not abstract ones
Bad:
Help me optimize this code
Good:
```
Optimize this code for performance. Prioritize:
1. Reducing unnecessary database queries (N+1 problems)
2. Avoiding repeated computation inside loops
3. Replacing linear searches with more efficient data structures
Keep the interface unchanged — only change the implementation.
```
Concrete constraints lead to targeted results.
Add frontmatter to your commands
The description field shows up in Claude Code's command list, so team members can quickly understand what each command does:
---
description: Review current changes for code quality feedback
---
Review the quality of the current changes...
For a Rails project, these commands cover the most common daily development tasks:
.claude/commands/review.md — Code review
Review the changes in git diff. Check for:
- Logic errors and edge case handling
- Security issues: SQL injection, authorization checks
- Naming clarity
- Duplicate logic worth extracting
For each issue, give the specific location and a concrete suggestion.
```
.claude/commands/test.md — Generate tests
Write tests for this code: $ARGUMENTS
Use RSpec. Cover: happy path, edge cases, error conditions.
Test naming format: describe ... context ... it ...
Use real objects by default; only mock external dependencies when necessary.
```
.claude/commands/pr.md — PR description
Based on git diff and commit log, generate a PR description.
Format:
(2-3 sentences summarizing what was done)
(Background and motivation)
(How to verify this change)
Keep it concise, written for a code reviewer.
```
.claude/commands/explain.md — Explain code
Explain what $ARGUMENTS does:
- What is its overall responsibility?
- How does the key logic work?
- What edge cases are worth noting?
Write for a developer who is new to this part of the codebase. Focus on why, not just what.
```
Some habits are personal and shouldn't be forced on the whole team. Put these in ~/.claude/commands/:
~/.claude/commands/standup.md — Daily standup prep
```markdown
Based on today's git log and open TODOs, prepare a standup summary:
- What I completed yesterday
- What I'm planning today
- Any blockers
Keep it to 5 sentences max.
```
~/.claude/commands/refactor.md — Refactoring suggestions
```markdown
Analyze $ARGUMENTS and suggest refactoring improvements.
Only raise genuinely worthwhile changes — don't refactor for its own sake.
For each suggestion, explain: what problem it solves, how much work it involves, and what the risk is.
```
The real value of custom commands isn't personal productivity — it's giving your team a shared vocabulary.
Commit .claude/commands/ to your repo and document the available commands in your README or CLAUDE.md. New teammates get the team's accumulated prompt library the moment they clone the repo, without needing to figure things out themselves.
As the project evolves, so do the commands. If a prompt isn't working well, fix one line and push — the whole team gets the update. This is the lowest-overhead way to land prompt engineering at the team level.
.claude/
├── commands/
│ ├── review.md # Code review
│ ├── test.md # Generate tests
│ ├── pr.md # PR description
│ └── explain.md # Explain code
└── settings.json