Claude Code Custom Slash Commands: Best Practices for Bash Scripts, Prompt Templates & Team Workflows
Claude Code Custom Slash Commands: Automate Repetitive Development Tasks
Custom slash commands in Claude Code transform repetitive development workflows into single-command operations. Whether you’re generating boilerplate, running complex multi-step builds, or sharing standardized workflows across your team, slash commands let you encode institutional knowledge into reusable automation. This guide covers best practices for writing effective commands using bash scripts, prompt templates, and shared libraries.
Understanding Slash Command Types
Claude Code supports two primary types of custom slash commands, each suited for different automation needs:
| Type | File Extension | Location | Best For |
|---|---|---|---|
| Prompt Template | .md | .claude/commands/ | Context-rich prompts, code generation, reviews |
| Bash Script | .sh | .claude/commands/ | System operations, build pipelines, file manipulation |
mkdir -p .claude/commands- **Create the user-level command directory** for personal commands available across all projects:mkdir -p ~/.claude/commandsgit add .claude/commands/
git commit -m "feat: add Claude Code custom slash commands"Prompt templates (.md files) are the most powerful command type. They inject structured context into Claude's conversation, enabling consistent and repeatable results.
Example: Code Review Command
Create .claude/commands/review.md:
Review the current staged changes with these criteria:
- Security: Check for injection vulnerabilities, exposed secrets, and OWASP Top 10 issues
- Performance: Identify N+1 queries, unnecessary re-renders, or missing indexes
- Testing: Verify adequate test coverage for new logic paths
- Conventions: Ensure naming, file structure, and patterns match this project
Provide a summary table with severity (critical/warning/info) for each finding.
If no issues found, confirm the changes are ready to merge.
Focus on files from: git diff —cached —name-only
Usage: Type /project:review in Claude Code to invoke this command.
Example: Feature Scaffolding Command with Arguments
Create .claude/commands/scaffold-feature.md:
Generate a new feature module named “$ARGUMENTS” following our project conventions:
- Create the component file in src/features/$ARGUMENTS/
- Add a unit test file in src/features/$ARGUMENTS/tests/
- Create an index.ts barrel export
- Register the route in src/routes.ts
- Add a basic TypeScript interface for props
Use existing features in src/features/ as reference for patterns and naming.
Usage: /project:scaffold-feature user-profile
Step 3: Build Bash Script Commands
Bash commands handle operations that require system-level execution before or alongside Claude’s AI capabilities.
Example: Pre-PR Validation Script
Create .claude/commands/pre-pr.sh:
#!/bin/bash
set -euo pipefail
echo ”## Pre-PR Validation Report”
echo ""
Lint check
echo ”### Lint Results”
if npx eslint src/ —quiet 2>/dev/null; then
echo “All lint checks passed.”
else
echo “Lint errors detected. Fix before opening PR.”
fi
echo ""
Type check
echo ”### TypeScript Check”
if npx tsc —noEmit 2>/dev/null; then
echo “No type errors found.”
else
npx tsc —noEmit 2>&1 | tail -20
fi
echo ""
Test summary
echo ”### Test Summary”
npx jest —coverage —silent 2>&1 | grep -E “(Tests:|Suites:|Statements)” || echo “No test output captured.”
echo ""
echo ”### Changed Files”
git diff —stat HEAD~1
Make it executable: chmod +x .claude/commands/pre-pr.sh
Step 4: Create a Shared Team Command Library
Standardize workflows across your team by committing commands to version control with clear documentation.
- Establish a naming convention: Use prefixes like
dev-,qa-,ops-to categorize commands.- Add a README inside.claude/commands/README.md:# Team Slash Commands
Command Type Description /project:review Prompt Structured code review /project:scaffold-feature Prompt Generate feature module /project:pre-pr Bash Run pre-PR validation /project:dev-setup Bash Initialize dev environment /project:qa-checklist Prompt QA verification checklist
Step 5: Chain Commands into Workflows
Combine multiple commands into end-to-end workflows. Create a master prompt that references other operations.
Create .claude/commands/release-prep.md:
Prepare this project for release by completing these steps in order:
- Run all tests and confirm they pass
- Check for any TODO or FIXME comments in changed files since last tag
- Review the git log since the last tag and draft release notes in Keep a Changelog format
- Verify package.json version matches the planned release
- List any dependency updates that should be noted
Present a final release readiness summary with go/no-go recommendation.
Pro Tips
- Use
$ARGUMENTS liberally — prompt templates support the $ARGUMENTS placeholder, which captures everything typed after the command name. Design commands to accept flexible input.- Reference project files in prompts — include instructions like “Use the patterns in src/utils/ as reference” to ground Claude in your actual codebase conventions.- Layer personal and project commands — keep personal productivity commands in ~/.claude/commands/ and team standards in .claude/commands/. Project commands take precedence on name collision.- Keep bash scripts idempotent — commands may be run multiple times. Use checks like if [ ! -f … ] to avoid duplicate operations.- Version your commands with your code — as your project evolves, update the commands. Outdated slash commands that reference removed patterns cause confusion.
Troubleshooting
Issue Cause Solution Command not appearing in /project: list File not in correct directory Verify file is in .claude/commands/ at the repo root, not a subdirectory Bash command fails with permission denied Script not executable Run chmod +x .claude/commands/your-script.sh $ARGUMENTS not replacedUsed in .sh file instead of .md Argument substitution works in prompt templates (.md); for bash, use positional params $1, $@ Command runs but output is empty Script writes to file instead of stdout Bash commands should output to stdout so Claude can process the results Team members don't see commands Commands not committed to git Ensure .claude/commands/ is tracked and pushed to the remote branch
## Frequently Asked Questions
Can I use slash commands to interact with external APIs or services?
Yes. Bash script commands can call external APIs using curl or any CLI tool installed on your system. For example, you can create a command that fetches the latest deployment status from your CI/CD platform and presents it to Claude for analysis. Keep API keys in environment variables rather than hardcoding them in scripts—reference them as $YOUR_API_KEY in your bash commands.
What is the difference between project commands and user commands?
Project commands live in .claude/commands/ at your repository root and are shared with your team via version control. They appear under the /project: prefix. User commands live in ~/.claude/commands/ and are private to your machine, available across all projects under the /user: prefix. If both directories contain a command with the same name, the project-level command takes precedence.
How long can a slash command prompt template be?
Prompt templates can be as long as needed, but best practice is to keep them focused and under 500 words. Overly long templates dilute the instruction signal and may cause Claude to miss key requirements. If your workflow is complex, break it into multiple commands and chain them together rather than creating a single monolithic template. Reference existing project files for context instead of duplicating code patterns inline.