Slash Command Builder

Create effective custom slash commands for Claude Code with proper structure, dynamic features, and best practices.

Quick Reference

Command File Location:

Project (shared): .claude/commands/name.md
Personal (individual): ~/.claude/commands/name.md

Dynamic Features:

Arguments: $ARGUMENTS (all) or $1, $2, $3 (positional)
Bash execution: [execute: command] (requires allowed-tools: Bash(...))
File references: @path/to/file

Frontmatter: Optional YAML with description, allowed-tools, argument-hint, model

The Slash Command Creation Workflow

Phase 1: Requirements Gathering

Use AskUserQuestion to understand what they need:

What should the command do?
- What task or prompt does it automate?
- What's the expected outcome?
Who will use it?
- Just you (personal command)
- Your team (project command)
Does it need dynamic inputs?
- Fixed prompt (no arguments)
- User-provided values (arguments needed)
- Context from system (bash execution)
- File contents (file references)
What tools should it access?
- Read-only analysis (Read, Grep, Glob)
- Git operations (Bash(git:*))
- Full access (default, no restrictions)

Phase 2: Choose Scope

Personal Command (~/.claude/commands/):

Your individual shortcuts
Experimental commands
Personal workflow automation
Not shared with team

Project Command (.claude/commands/):

Team-shared commands
Standardized workflows
Committed to git
Available to all team members

Phase 3: Design the Structure

Basic command structure:

---
description: Brief description for /help
allowed-tools: Optional tool restrictions
argument-hint: Optional argument guidance
---

[Your prompt here]

Decision tree:

Start with basic prompt
Add arguments if needed ($ARGUMENTS or $1/$2)
Add bash execution if context needed ([execute: command])
Add file references if analyzing files (@path)
Add frontmatter for description and restrictions

Phase 4: Implementation

Step 1: Create the file

# For project commands
touch .claude/commands/your-command.md

# For personal commands
touch ~/.claude/commands/your-command.md

The filename (without .md) becomes the command name.

Step 2: Write the command

Use templates from templates/ directory:

basic-command.md - Simple prompt
with-arguments.md - With dynamic inputs
with-bash.md - With bash execution
with-files.md - With file references
complex-command.md - All features combined

Step 3: Add frontmatter (recommended)

---
description: What this command does (appears in /help)
allowed-tools: Read, Grep, Glob  # Optional restrictions
argument-hint: [arg1] [arg2]     # Optional user guidance
---

Phase 5: Testing

Verify command appears:
```
/help
```
Look for your command in the list.
Test basic invocation:
```
/your-command
```
Test with arguments (if applicable):
```
/your-command arg1 arg2
```
Test bash execution (if applicable):
- Verify commands execute
- Check output appears in prompt
Test file references (if applicable):
- Verify files load correctly
- Check paths resolve
Team testing (for project commands):
- Have teammates try it
- Gather feedback
- Iterate based on usage

Phase 6: Iteration

Start simple, add complexity incrementally:

First: Basic prompt without dynamic features
Test: Verify it works
Add: One feature (arguments OR bash OR files)
Test: Verify new feature works
Repeat: Add next feature if needed

Don't try to add all features at once. Build incrementally.

Common Command Patterns

Pattern 1: Code Analysis

---
description: Analyze code for [specific criteria]
allowed-tools: Read, Grep, Glob
argument-hint: [file-or-directory]
---

Analyze @$1 for:
1. [Criterion 1]
2. [Criterion 2]
3. [Criterion 3]

Provide specific findings with examples.

Pattern 2: Git Workflow

---
description: [Git operation] with context
allowed-tools: Bash(git:*)
---

## Current State

Branch: [execute: git branch --show-current]
Status: [execute: git status --short]

## Task

[What to do with this context]

Pattern 3: Code Generation

---
description: Generate [artifact] following patterns
allowed-tools: Read, Grep, Glob, Write
argument-hint: [what-to-generate]
---

## Existing Patterns

@[relevant examples]

## Task

Generate $ARGUMENTS following the patterns above.

Pattern 4: Deep Analysis

---
description: Deep analysis of [topic]
---

Think deeply about $ARGUMENTS considering:
1. [Aspect 1]
2. [Aspect 2]
3. [Aspect 3]

[Extended thinking triggered by keywords]

Real-World Examples

See examples/ for complete working examples:

git-workflows.md - Commit, PR, branch commands
code-analysis.md - Review, security, performance
code-generation.md - Tests, docs, boilerplate

Advanced Features

Arguments: $ARGUMENTS vs $1/$2

Use $ARGUMENTS when:

You want all input as a single block
Free-form text (messages, descriptions)
Don't need to reference parts separately

Use $1, $2, $3 when:

You need structured parameters
Different parts used in different places
Want to provide defaults for missing args

Example:

# $ARGUMENTS approach
Explain $ARGUMENTS in detail.

# Positional approach
Review PR #$1 with priority $2 assigned to $3.

Bash Execution

Execute commands BEFORE the prompt runs:

---
allowed-tools: Bash(git:*)
---

Current branch: [execute: git branch --show-current]
Recent commits: [execute: git log --oneline -5]

Requirements:

Must include allowed-tools: Bash(...)
Use [execute: command] syntax (backticks required)
Output is captured and included in prompt

Security: Limit bash access with specific tool patterns:

allowed-tools: Bash(git:*)          # Git only
allowed-tools: Bash(npm:*), Bash(git:*)  # npm and git

File References

Include file contents with @ prefix:

Review @src/auth/login.js for security issues.

Features:

Automatic CLAUDE.md inclusion from file's directory hierarchy
Works with relative or absolute paths
Directories show listing (not contents)

Frontmatter Configuration

Complete frontmatter options:

---
description: Brief description (required for /help and SlashCommand tool)
allowed-tools: Read, Grep, Glob, Bash(git:*)  # Optional restrictions
argument-hint: [file] [priority]              # Optional guidance
model: claude-3-5-haiku-20241022              # Optional model override
disable-model-invocation: false               # Optional, prevent auto-calling
---

Best Practices

Always include description
- Helps team understand command purpose
- Required for SlashCommand tool
- Appears in /help
Use argument-hint for clarity
- Shows expected inputs
- Self-documenting commands
- Reduces user confusion
Limit allowed-tools when appropriate
- Read-only commands: Read, Grep, Glob
- Git-only: Bash(git:*)
- Enhances security and safety
Structure complex commands
- Use sections (Context, Task, Constraints)
- Makes prompts easier to understand
- Follows clear flow
Reference project conventions
- Include @CLAUDE.md for standards
- Reference example files
- Ensures consistency
Test incrementally
- Start simple, add features one at a time
- Test each addition before next
- Don't debug multiple features simultaneously
Organize with subdirectories
- Group related commands
- Cleaner file structure
- Easier to maintain
Commit project commands
- Share with team via git
- Version control for commands
- Team benefits from your work

Common Issues and Solutions

Issue: Command doesn't appear in /help

Causes:

File not in correct location
Missing .md extension
Filename has invalid characters

Solutions:

Check file is in .claude/commands/ or ~/.claude/commands/
Verify .md extension
Use lowercase-with-hyphens for filename

Issue: Arguments not replacing

Causes:

Typo in placeholder ($ARGUMENT instead of $ARGUMENTS)
Not passing arguments when invoking
Wrong syntax

Solutions:

Double-check spelling: $ARGUMENTS, $1, $2
Test with: /command arg1 arg2
Verify placeholder exists in template

Issue: Bash commands not executing

Causes:

Missing allowed-tools: Bash(...) in frontmatter
Wrong syntax (missing backticks)
Command fails when run

Solutions:

Add frontmatter: allowed-tools: Bash(command:*)
Use correct syntax: [execute: command]
Test command in terminal first

Issue: File references not working

Causes:

Missing @ prefix
File doesn't exist
Wrong path

Solutions:

Use @path/to/file syntax
Verify file exists: ls path/to/file
Try absolute path if relative fails

Slash Commands vs Skills

When to use each:

Use Slash Commands	Use Skills
Manual invocation (you decide when)	Automatic discovery (Claude decides when)
Simple prompt templates	Complex multi-file workflows
Quick, focused operations	Broad capabilities
Single .md file	Directory with multiple files

Example:

Slash command: /commit - You invoke when ready to commit
Skill: skill-builder - Claude discovers when you mention Skills

Both complement each other in your workflow.

Complete Syntax Reference

For detailed syntax documentation, see reference/syntax-guide.md.

For best practices and patterns, see reference/best-practices.md.

For troubleshooting help, see reference/troubleshooting.md.

Tips for Effective Commands

Start with the simplest version that works
Add complexity only when needed (YAGNI principle)
Test with real scenarios before sharing
Include clear descriptions in frontmatter
Use tool restrictions for safety
Reference project conventions with file refs
Gather context with bash execution
Structure prompts with clear sections
Provide examples in argument-hint
Iterate based on usage - improve over time

Next Steps

After creating a command:

Test thoroughly with various inputs
Share with team (if project command)
Document in CLAUDE.md if it's a pattern others should know
Create related commands for connected workflows
Refine based on feedback - commands improve with use

Remember: Slash commands are user-invoked prompt templates. Start simple, test frequently, and add features incrementally. The best commands are clear, focused, and solve real workflow problems.

slash-command-builder

Slash Command Builder

Quick Reference

The Slash Command Creation Workflow

Phase 1: Requirements Gathering

Phase 2: Choose Scope

Phase 3: Design the Structure

Phase 4: Implementation

Step 1: Create the file

Step 2: Write the command

Step 3: Add frontmatter (recommended)

Phase 5: Testing

Phase 6: Iteration

Common Command Patterns

Pattern 1: Code Analysis

Pattern 2: Git Workflow

Pattern 3: Code Generation

Pattern 4: Deep Analysis

Real-World Examples

Advanced Features

Arguments: $ARGUMENTS vs $1/$2

Bash Execution

File References

Frontmatter Configuration

Best Practices

Common Issues and Solutions

Issue: Command doesn't appear in /help

Issue: Arguments not replacing

Issue: Bash commands not executing

Issue: File references not working

Slash Commands vs Skills

Complete Syntax Reference

Tips for Effective Commands

Next Steps