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.