claude-plugins/claude-code/skills/claude-code-slash-commands/SKILL.md

---
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: <file-path>
---

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: <file1> <file2>
---
```

### 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: <approach1> <approach2>
---

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: <file> <function-name>
---

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

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: <file> <function-name>
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: <file>
---

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: <option1> <option2>
---

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: <file-path> <function-name>

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