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

name, description

name	description
Slash Command Creator	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

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

# 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

---
description: Brief description for /help
---

Prompt content here

Command Name

The filename (without .md) becomes the command:

# File: .claude/commands/test.md
# Command: /test

# File: .claude/commands/commit-push.md
# Command: /commit-push

Frontmatter Options

description

Shows in /help output:

---
description: Generate unit tests for a function
---

argument-hint

Shows expected arguments in autocomplete:

---
description: Compare two files
argument-hint: <file1> <file2>
---

allowed-tools

Specifies which tools the command can use:

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

---
description: Simple task
model: claude-haiku-4
---

disable-model-invocation

Prevent SlashCommand tool from calling this:

---
description: Internal helper command
disable-model-invocation: true
---

Argument Handling

$ARGUMENTS - All Arguments

Captures everything passed to the command:

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

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

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

---
description: Review a file
---

Review @$1 for code quality issues.

Usage: /review src/auth.js Claude will read src/auth.js automatically

Multiple Files

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

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:

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

# 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

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

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

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

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

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

---
description: Review X for Y
---

Review $ARGUMENTS for [specific criteria]

Include:
- [Aspect 1]
- [Aspect 2]
- [Aspect 3]

Generate Pattern

---
description: Generate X from Y
---

Generate [output type] for: $ARGUMENTS

Requirements:
- [Requirement 1]
- [Requirement 2]

Compare Pattern

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

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

# See all available commands
/help

# Your command should appear in the list

2. Test Argument Handling

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

---
description: Test bash execution
allowed-tools: Bash(echo:*)
---

!echo "This should show before prompt processing"

Did the echo work?

Best Practices

1. Clear Descriptions

# Good
description: Generate unit tests for a specific function

# Bad
description: Testing

2. Explicit Arguments

# Good
argument-hint: <file-path> <function-name>

# Bad (no hint)
argument-hint:

3. Specific Tool Permissions

# Good - minimal permissions
allowed-tools: Bash(git status:*), Bash(git diff:*)

# Risky - too permissive
allowed-tools: *

4. Meaningful Names

# Good
/generate-tests
/review-security
/commit-and-push

# Bad
/gt
/rs
/cap

5. Self-Documenting Content

Review code for:
1. Logic errors
2. Style issues
3. Performance problems

$ARGUMENTS

Better than:

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:

# Specific commands only
allowed-tools: Bash(git status:*), Bash(git log:*)

# Never use unless absolutely required
allowed-tools: *

No Hardcoded Secrets

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

# Risky - no validation
!rm -rf $1

# Better - validate first
Confirm you want to delete: $1
(Then use interactive confirmation before executing)

Command Template

---
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
• Plugin Development - For packaging commands in plugins
• Hooks - For event-based automation

---

Remember: Slash commands are for reusable prompts. Start with manual prompts, identify patterns you repeat, then codify them as commands.