--- name: Slash Command Creator description: Create custom slash commands for Claude Code with argument handling, bash execution, and file references. Use when building reusable prompts, automating workflows, or creating project-specific commands. --- # Slash Command Development ## When to Use This Skill Use this skill when: - Creating custom slash commands for Claude Code - Building reusable prompt templates - Automating repetitive tasks with commands - Setting up project-specific workflows - Converting manual prompts to slash commands Do NOT use this skill for: - Creating full plugins (use claude-code-plugins skill) - Setting up hooks (use claude-code-hooks skill) - General Claude Code usage ## Quick Start: Creating a Command ### 1. Create Command File ```bash # Project-specific command (shared with team) mkdir -p .claude/commands cat > .claude/commands/review.md << 'EOF' --- description: Review code for common issues --- Review the following code for: - Bugs and logic errors - Code style issues - Performance problems - Security vulnerabilities $ARGUMENTS EOF ``` **Usage**: `/review @src/main.js` ### 2. Personal Command (Your Use Only) ```bash # Personal command (not shared) mkdir -p ~/.claude/commands cat > ~/.claude/commands/explain.md << 'EOF' --- description: Explain code in detail argument-hint: --- Provide a detailed explanation of: $ARGUMENTS Include: - What the code does - How it works - Key design decisions - Potential improvements EOF ``` **Usage**: `/explain @utils/parser.ts` ## Command Locations ### Project Commands (.claude/commands/) **Location**: `.claude/commands/` in your project **Scope**: Available to everyone working on the project **Version Control**: Commit to git for team sharing **Use For**: Project-specific workflows, team standards ### Personal Commands (~/.claude/commands/) **Location**: `~/.claude/commands/` **Scope**: Available in all your projects **Version Control**: Not in git (user-specific) **Use For**: Personal productivity, custom preferences ## Command Syntax ### Basic Structure ```markdown --- description: Brief description for /help --- Prompt content here ``` ### Command Name The filename (without `.md`) becomes the command: ```bash # File: .claude/commands/test.md # Command: /test # File: .claude/commands/commit-push.md # Command: /commit-push ``` ## Frontmatter Options ### description Shows in `/help` output: ```yaml --- description: Generate unit tests for a function --- ``` ### argument-hint Shows expected arguments in autocomplete: ```yaml --- description: Compare two files argument-hint: --- ``` ### allowed-tools Specifies which tools the command can use: ```yaml --- description: Review and commit changes allowed-tools: Bash(git status:*), Bash(git add:*), Bash(git commit:*) --- ``` **Patterns**: - `Bash(git status:*)` - Specific command with any args - `Read(*)` - Tool with any args - `*` - All tools allowed ### model Override default model for this command: ```yaml --- description: Simple task model: claude-haiku-4 --- ``` ### disable-model-invocation Prevent SlashCommand tool from calling this: ```yaml --- description: Internal helper command disable-model-invocation: true --- ``` ## Argument Handling ### $ARGUMENTS - All Arguments Captures everything passed to the command: ```markdown --- description: Explain multiple files --- Explain these files: $ARGUMENTS ``` **Usage**: `/explain @src/a.js @src/b.js @src/c.js` **Result**: All three file paths captured ### Positional Arguments ($1, $2, $3...) Individual arguments like shell scripts: ```markdown --- description: Compare two approaches argument-hint: --- Compare approach "$1" versus "$2" and recommend which is better. ``` **Usage**: `/compare REST GraphQL` **$1** = "REST" **$2** = "GraphQL" ### Combining Arguments ```markdown --- description: Test specific function argument-hint: --- In file $1, create comprehensive tests for the function: $2 $ARGUMENTS ``` ## File References with @ ### Single File ```markdown --- description: Review a file --- Review @$1 for code quality issues. ``` **Usage**: `/review src/auth.js` Claude will read `src/auth.js` automatically ### Multiple Files ```markdown --- description: Compare implementations --- Compare the implementation approaches in: $ARGUMENTS Which approach is better and why? ``` **Usage**: `/compare @old/version.js @new/version.js` ### Inline File References ```markdown Review @src/config.js and ensure it follows @docs/style-guide.md ``` The `@` prefix tells Claude to read those files before processing. ## Bash Execution with ! ### Prefix Commands with ! Run bash before the slash command executes: ```markdown --- description: Show git status and suggest next steps allowed-tools: Bash(git status:*), Bash(git diff:*) --- !git status !git diff --stat Based on the current git state, suggest what I should do next. ``` **Important**: Must include `allowed-tools` with Bash tool specification. ### Why Use ! Prefix? Without `!`, bash commands are just text in the prompt. With `!`, they execute and results are included in context. ```markdown # This doesn't work (just text): git status What should I commit? # This works (executes first): --- allowed-tools: Bash(git status:*) --- !git status What should I commit? ``` ## Namespacing with Directories ### Organize Related Commands ``` .claude/commands/ ├── git/ │ ├── commit.md │ ├── review.md │ └── sync.md └── test/ ├── unit.md └── integration.md ``` **Commands**: `/commit`, `/review`, `/sync`, `/unit`, `/integration` **Note**: Directory structure is for organization only - it doesn't affect command names. ## Complete Examples ### 1. Security Review Command ```markdown --- description: Comprehensive security review of code files allowed-tools: Read(*), Grep(*), Bash(grep:*) argument-hint: --- Perform a security audit on: $ARGUMENTS Check for: 1. SQL injection vulnerabilities 2. XSS vulnerabilities 3. Authentication/authorization issues 4. Hardcoded secrets or credentials 5. Unsafe deserialization 6. Path traversal vulnerabilities 7. Insecure cryptography 8. Information disclosure For each issue found: - Severity level (Critical/High/Medium/Low) - Location (file:line) - Explanation of the vulnerability - Recommended fix with code example ``` **Usage**: `/security-review @src/auth.js @src/api.js` ### 2. Commit + Push Command ```markdown --- description: Review changes, commit, and push to remote allowed-tools: Bash(git:*) --- !git status !git diff Review the changes above and: 1. Create an appropriate commit message 2. Commit the changes 3. Push to remote Ask for confirmation before pushing. ``` **Usage**: `/commit-push` ### 3. Test Generator ```markdown --- description: Generate comprehensive tests for a function argument-hint: model: claude-sonnet-4 --- For the function "$2" in @$1: 1. Analyze the function's behavior 2. Identify edge cases 3. Generate comprehensive unit tests including: - Happy path tests - Edge case tests - Error condition tests - Boundary value tests Use the project's existing test framework and patterns. ``` **Usage**: `/test-gen src/parser.js parseQuery` ### 4. API Documentation ```markdown --- description: Generate API documentation for endpoints allowed-tools: Read(*), Grep(*) --- Generate API documentation for: $ARGUMENTS Include: - Endpoint URL and method - Request parameters (query, body, headers) - Response format and status codes - Example requests and responses - Error conditions - Authentication requirements Format as OpenAPI/Swagger compatible YAML. ``` **Usage**: `/api-docs @routes/users.js @routes/posts.js` ### 5. Performance Analysis ```markdown --- description: Analyze code for performance issues argument-hint: --- Analyze @$1 for performance issues: 1. **Time Complexity**: Identify algorithms and their complexity 2. **Space Complexity**: Memory usage patterns 3. **Bottlenecks**: Potential performance problems 4. **Optimization Opportunities**: Specific improvements with examples For each issue: - Current implementation - Why it's problematic - Optimized version - Performance impact estimate ``` **Usage**: `/perf @src/data-processor.js` ## Command Patterns ### Review Pattern ```markdown --- description: Review X for Y --- Review $ARGUMENTS for [specific criteria] Include: - [Aspect 1] - [Aspect 2] - [Aspect 3] ``` ### Generate Pattern ```markdown --- description: Generate X from Y --- Generate [output type] for: $ARGUMENTS Requirements: - [Requirement 1] - [Requirement 2] ``` ### Compare Pattern ```markdown --- description: Compare X and Y argument-hint: --- Compare "$1" versus "$2" Analyze: - [Comparison aspect 1] - [Comparison aspect 2] Recommendation: [Which is better and why] ``` ### Workflow Pattern ```markdown --- description: Execute multi-step workflow allowed-tools: Bash(*), Read(*), Write(*) --- Execute the following workflow: 1. [Step 1] 2. [Step 2] 3. [Step 3] After each step, confirm before proceeding. ``` ## Testing Commands ### 1. Check Command List ```bash # See all available commands /help # Your command should appear in the list ``` ### 2. Test Argument Handling ```bash # Test with different argument patterns /mycommand arg1 /mycommand arg1 arg2 /mycommand @file.js /mycommand @file1.js @file2.js ``` ### 3. Verify Bash Execution If using `!` prefix, confirm commands execute: ```markdown --- description: Test bash execution allowed-tools: Bash(echo:*) --- !echo "This should show before prompt processing" Did the echo work? ``` ## Best Practices ### 1. Clear Descriptions ```yaml # Good description: Generate unit tests for a specific function # Bad description: Testing ``` ### 2. Explicit Arguments ```yaml # Good argument-hint: # Bad (no hint) argument-hint: ``` ### 3. Specific Tool Permissions ```yaml # Good - minimal permissions allowed-tools: Bash(git status:*), Bash(git diff:*) # Risky - too permissive allowed-tools: * ``` ### 4. Meaningful Names ```bash # Good /generate-tests /review-security /commit-and-push # Bad /gt /rs /cap ``` ### 5. Self-Documenting Content ```markdown Review code for: 1. Logic errors 2. Style issues 3. Performance problems $ARGUMENTS ``` Better than: ```markdown Review: $ARGUMENTS ``` ## Troubleshooting ### Command Not Found **Issue**: `/mycommand` says command not found **Solutions**: 1. Check file is in `.claude/commands/` or `~/.claude/commands/` 2. Verify filename ends with `.md` 3. Restart Claude Code to refresh command list ### Arguments Not Working **Issue**: `$ARGUMENTS` or `$1` showing literally **Solutions**: 1. Ensure proper syntax: `$ARGUMENTS`, `$1`, `$2` (not `${ARGUMENTS}`) 2. Check for typos in variable names 3. Test with simple command first ### Bash Commands Not Executing **Issue**: `!command` not running **Solutions**: 1. Add `allowed-tools` to frontmatter 2. Include specific tool pattern: `Bash(git:*)` 3. Test with simple command: `!echo test` ### File References Not Loading **Issue**: `@file.js` not including file content **Solutions**: 1. Verify file path is correct (relative to project root) 2. Check file exists: `ls @file.js` 3. Ensure no typos in file path ## Security Considerations ### Limit Tool Access Only grant necessary permissions: ```yaml # Specific commands only allowed-tools: Bash(git status:*), Bash(git log:*) # Never use unless absolutely required allowed-tools: * ``` ### No Hardcoded Secrets ```markdown # Bad - hardcoded API key !curl -H "API-Key: sk-abc123..." api.example.com # Good - use environment variables !curl -H "API-Key: $MY_API_KEY" api.example.com ``` ### Validate User Input If using arguments in bash: ```markdown # Risky - no validation !rm -rf $1 # Better - validate first Confirm you want to delete: $1 (Then use interactive confirmation before executing) ``` ## Command Template ```markdown --- description: [Clear, concise description of what this command does] argument-hint: [Expected arguments format] allowed-tools: [Specific tool patterns if needed] --- [Command prompt template] $ARGUMENTS ``` ## Resources - [Official Slash Commands Documentation](https://docs.claude.com/en/docs/claude-code/slash-commands) - [Plugin Development](../claude-code-plugins/SKILL.md) - For packaging commands in plugins - [Hooks](../claude-code-hooks/SKILL.md) - For event-based automation --- **Remember**: Slash commands are for reusable prompts. Start with manual prompts, identify patterns you repeat, then codify them as commands.