slash-command-builder

name	slash-command-builder
description	Create custom slash commands for Claude Code including syntax, arguments, bash execution, file references, and frontmatter configuration. Use when creating slash commands, custom commands, .md command files, or when asked about command creation, /command syntax, or command best practices.

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:

1. What should the command do?

   • What task or prompt does it automate?
   • What's the expected outcome?

2. Who will use it?

   • Just you (personal command)
   • Your team (project command)

3. Does it need dynamic inputs?

   • Fixed prompt (no arguments)
   • User-provided values (arguments needed)
   • Context from system (bash execution)
   • File contents (file references)

4. 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:

1. Start with basic prompt
2. Add arguments if needed ($ARGUMENTS or $1/$2)
3. Add bash execution if context needed ([execute: command])
4. Add file references if analyzing files (@path)
5. 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

1. Verify command appears:

   /help
   

   Look for your command in the list.

2. Test basic invocation:

   /your-command
   

3. Test with arguments (if applicable):

   /your-command arg1 arg2
   

4. Test bash execution (if applicable):

   • Verify commands execute
   • Check output appears in prompt

5. Test file references (if applicable):

   • Verify files load correctly
   • Check paths resolve

6. Team testing (for project commands):

   • Have teammates try it
   • Gather feedback
   • Iterate based on usage

Phase 6: Iteration

Start simple, add complexity incrementally:

1. First: Basic prompt without dynamic features
2. Test: Verify it works
3. Add: One feature (arguments OR bash OR files)
4. Test: Verify new feature works
5. 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:

1. Must include allowed-tools: Bash(...)
2. Use [execute: command] syntax (backticks required)
3. 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

1. Always include description

   • Helps team understand command purpose
   • Required for SlashCommand tool
   • Appears in /help

2. Use argument-hint for clarity

   • Shows expected inputs
   • Self-documenting commands
   • Reduces user confusion

3. Limit allowed-tools when appropriate

   • Read-only commands: Read, Grep, Glob
   • Git-only: Bash(git:*)
   • Enhances security and safety

4. Structure complex commands

   • Use sections (Context, Task, Constraints)
   • Makes prompts easier to understand
   • Follows clear flow

5. Reference project conventions

   • Include @CLAUDE.md for standards
   • Reference example files
   • Ensures consistency

6. Test incrementally

   • Start simple, add features one at a time
   • Test each addition before next
   • Don't debug multiple features simultaneously

7. Organize with subdirectories

   • Group related commands
   • Cleaner file structure
   • Easier to maintain

8. 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

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

Next Steps

After creating a command:

1. Test thoroughly with various inputs
2. Share with team (if project command)
3. Document in CLAUDE.md if it's a pattern others should know
4. Create related commands for connected workflows
5. 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.