Guide for creating custom Claude Code slash commands with proper structure, argument handling, frontmatter configuration, and best practices. Use when the user wants to create slash commands, custom commands, reusable prompts, or mentions creating/designing/building commands.
This skill helps you create custom Claude Code slash commands - reusable prompts stored as Markdown files that can be invoked with `/command-name` syntax. Slash commands are ideal for frequently-used prompts that you want to trigger explicitly.
When creating a new slash command, follow this workflow:
1. **Identify the purpose** - What reusable prompt do you need?
2. **Choose scope** - Project-level (.claude/commands/) or personal (~/.claude/commands/)?
3. **Select name** - Clear, descriptive filename without .md extension
4. **Design arguments** - Will it use $ARGUMENTS, $1/$2/$3, or none?
5. **Add frontmatter** - Optional metadata (description, tools, model)
6. **Write prompt** - The markdown content that becomes the prompt
7. **Test invocation** - Verify command works with various arguments
Commands are invoked with:
```
/command-name [arguments]
```
The command name comes from the filename without `.md` extension.
```bash
echo "Review this code for security vulnerabilities" > .claude/commands/security-review.md
```
**Example structure:**
```
.claude/commands/
├── review.md # /review
├── optimize.md # /optimize
├── test.md # /test
└── frontend/
└── component.md # /component (project:frontend)
```
```bash
echo "Explain this code in simple terms" > ~/.claude/commands/explain.md
```
**Example structure:**
```
~/.claude/commands/
├── explain.md # /explain (user)
├── refactor.md # /refactor (user)
└── snippets/
└── doc.md # /doc (user:snippets)
```
Simple commands that don't need input:
```markdown
Review the current codebase for potential improvements and suggest optimizations.
```
Usage: `/review`
Captures everything passed to the command:
```markdown
Fix issue #$ARGUMENTS following our coding standards and best practices.
```
Usage:
Access specific arguments by position:
```markdown
Review PR #$1 with priority $2 and assign to $3 for review.
```
Usage: `/review-pr 456 high alice`
**Benefits:**
Use both positional and all arguments:
```markdown
Create a $1 feature called "$2" with the following requirements:
$ARGUMENTS
```
Usage: `/create-feature backend "user authentication" JWT tokens, role-based access, password hashing`
Add optional metadata at the top of your command file:
```markdown
---
allowed-tools: Read, Write, Edit, Bash
argument-hint: <issue-number> [priority]
description: Fix GitHub issue following coding standards
model: claude-3-5-sonnet-20241022
---
Your command prompt content goes here...
```
**allowed-tools:** Restrict which tools Claude can use
```yaml
allowed-tools: Read, Write, Edit, Bash
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
```
**argument-hint:** Show expected arguments in autocomplete
```yaml
argument-hint: <file-path>
argument-hint: <pr-number> [priority] [assignee]
argument-hint: [message]
```
**description:** Brief command description (overrides first line)
```yaml
description: Create a git commit with proper formatting
```
**model:** Specific model to use for this command
```yaml
model: claude-3-5-haiku-20241022 # Fast, cheap
model: claude-3-5-sonnet-20241022 # Balanced
model: claude-opus-4-20250514 # Advanced
```
**disable-model-invocation:** Prevent auto-invocation via SlashCommand tool
```yaml
disable-model-invocation: true
```
Include file contents in your command:
```markdown
---
description: Review code implementation
---
Review the implementation in @src/utils/helpers.js and compare it with @src/utils/legacy.js.
Identify:
```
Usage: `/review-implementation`
Execute bash commands and include output (requires allowed-tools):
```markdown
---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
description: Create a git commit
---
Create a git commit with the following context:
**Current Status:**
!`git status`
**Recent Changes:**
!`git diff HEAD`
**Commit Message:** $ARGUMENTS
```
Usage: `/commit "Add user authentication feature"`
Trigger extended reasoning by including keywords in the command content:
```markdown
---
description: Analyze complex architectural decisions
---
Please use extended thinking to analyze the following architectural decision:
$ARGUMENTS
Consider:
```
Organize commands in subdirectories (affects description, not command name):
```
.claude/commands/
├── git/
│ ├── commit.md # /commit (project:git)
│ └── review.md # /review (project:git)
└── frontend/
└── component.md # /component (project:frontend)
```
The subdirectory appears in the description but doesn't change the command invocation.
**File:** `.claude/commands/review.md`
```markdown
---
description: Comprehensive code review for quality and security
---
Review this code for:
Provide specific, actionable feedback with code examples.
```
Usage: `/review`
**File:** `.claude/commands/fix-issue.md`
```markdown
---
argument-hint: <issue-number> [priority]
description: Fix GitHub issue following coding standards
---
Fix issue #$1 following our coding standards.
Priority: $2
Steps:
1. Read the issue details from GitHub
2. Analyze the problem and root cause
3. Implement the fix with tests
4. Update documentation if needed
5. Create a commit with proper message format
```
Usage:
**File:** `.claude/commands/create-pr.md`
```markdown
---
allowed-tools: Bash(git *), Read, Write
argument-hint: <title> [description]
description: Create GitHub pull request with template
model: claude-3-5-sonnet-20241022
---
Create a GitHub pull request with the following details:
**Title:** $1
**Description:** $2
**Context:**
**Current Branch:**
!`git branch --show-current`
**Changes:**
!`git diff main...HEAD --stat`
**Commits:**
!`git log main..HEAD --oneline`
Generate a comprehensive PR description following our template at @.github/pull_request_template.md
```
Usage: `/create-pr "Add user authentication" "Implements JWT-based authentication system"`
**File:** `.claude/commands/test.md`
```markdown
---
allowed-tools: Bash, Read, Grep
argument-hint: [file-pattern]
description: Run tests and analyze failures
model: claude-3-5-haiku-20241022
---
Run tests matching pattern: $ARGUMENTS
Steps:
1. Execute test suite
2. Analyze any failures
3. Suggest fixes for failing tests
4. Validate fixes and re-run
Provide clear, actionable feedback on test failures.
```
Usage:
**File:** `.claude/commands/document.md`
```markdown
---
allowed-tools: Read, Write, Grep, Glob
description: Generate comprehensive documentation
---
Generate comprehensive documentation for: $ARGUMENTS
Include:
Format output in clear, professional markdown.
```
Usage: `/document src/utils/api-client.ts`
**File:** `.claude/commands/optimize.md`
```markdown
---
description: Analyze and optimize code performance
---
Analyze this code for performance optimizations:
$ARGUMENTS
Focus on:
Provide specific refactoring suggestions with before/after examples.
```
Usage: `/optimize`
**File:** `.claude/commands/review-pr.md`
```markdown
---
allowed-tools: Bash(gh *), Read
argument-hint: <pr-number> <priority> [assignee]
description: Review pull request with priority and assignment
---
Review PR #$1 with priority: $2
**PR Details:**
!`gh pr view $1`
**Changes:**
!`gh pr diff $1`
Review focus areas based on priority $2:
Assign to: $3 (if provided)
Provide comprehensive feedback organized by:
1. Critical issues (blocking)
2. Important suggestions
3. Minor improvements
4. Positive observations
```
Usage: `/review-pr 123 high alice`
**File:** `.claude/commands/git-flow.md`
```markdown
---
allowed-tools: Bash(git *)
argument-hint: <action> <branch-name>
description: Execute git workflow actions
---
Execute git workflow action: $1
Branch: $2
**Current Status:**
!`git status`
**Available Branches:**
!`git branch -a`
Actions:
Additional context: $ARGUMENTS
```
Usage:
**File:** `~/.claude/commands/optimize-query.md`
```markdown
---
description: Optimize database queries for performance
---
Analyze and optimize this database query:
$ARGUMENTS
Optimization checklist:
Provide:
1. Performance analysis
2. Optimized query
3. Index recommendations
4. Before/after execution plan comparison
```
Usage: `/optimize-query`
**File:** `.claude/commands/create-issue.md`
```markdown
---
allowed-tools: Bash(gh *), Read
argument-hint: <title> <type>
description: Create detailed GitHub issue with template
model: claude-3-5-sonnet-20241022
---
Create a GitHub issue with:
**Title:** $1
**Type:** $2 (feature/bug/enhancement/docs)
**Repository Analysis:**
!`gh repo view --json name,description,url`
**Template:**
@.github/ISSUE_TEMPLATE/$2.md
Generate a comprehensive issue following our template structure with:
Additional context: $ARGUMENTS
```
Usage: `/create-issue "Add dark mode support" feature "Users want theme customization"`
**Characteristics:**
**Best for:**
**Characteristics:**
**Best for:**
**Yes!** Use both approaches:
When creating a slash command:
List all available commands:
```bash
/help
```
Look for your command in the output.
```bash
/your-command
```
Verify the prompt expands correctly.
```bash
/your-command arg1
/your-command arg1 arg2 arg3
```
Verify argument substitution works.
If using `@file.txt`, verify the file exists and is readable.
If using `!command`, verify:
**Command not appearing:**
**Arguments not substituting:**
**File references not working:**
**Bash commands failing:**
**Description not showing:**
```
.claude/commands/
├── git/
│ ├── commit.md
│ ├── review.md
│ └── workflow.md
├── testing/
│ ├── run.md
│ ├── coverage.md
│ └── debug.md
└── docs/
├── generate.md
└── update.md
```
```
~/.claude/commands/
├── quick/ # Simple, haiku-model commands
│ ├── explain.md
│ └── format.md
├── standard/ # Regular sonnet commands
│ ├── review.md
│ └── optimize.md
└── complex/ # Advanced opus commands
└── architect.md
```
```
.claude/commands/
├── frontend/
│ ├── component.md
│ └── style.md
├── backend/
│ ├── api.md
│ └── database.md
└── devops/
├── deploy.md
└── monitor.md
```
Converting a skill to a slash command:
**Skill (automatic invocation):**
```markdown
---
name: code-explainer
description: Explain code in simple terms when user asks
---
Instructions for explaining code...
```
**Slash Command (explicit invocation):**
```markdown
---
description: Explain code in simple terms
---
Explain this code in simple, beginner-friendly terms:
$ARGUMENTS
Include:
```
Usage: `/explain`
**Avoid:**
**Safe practices:**
```markdown
---
description: Create component from template
---
Create a new $1 component named $2:
**Template:**
@templates/$1-template.tsx
**Destination:**
src/components/$2/
Generate files:
1. Component implementation
2. Test file
3. Styles
4. Documentation
5. Storybook story
```
Usage: `/create-component button UserProfileButton`
```markdown
---
allowed-tools: Bash, Read, Write, Edit
description: Complete feature implementation workflow
---
Implement feature: $ARGUMENTS
Workflow:
1. Create feature branch
2. Generate boilerplate code
3. Implement core logic
4. Add tests
5. Update documentation
6. Run quality checks
7. Create PR
Execute each step with confirmation.
```
Usage: `/feature-workflow "user authentication"`
```markdown
---
allowed-tools: Bash(git *), Read
description: Comprehensive code review with full context
---
Review code with full context:
**Project Structure:**
!`find . -type f -name "*.ts" -o -name "*.tsx" | head -20`
**Recent Changes:**
!`git log --oneline -10`
**Modified Files:**
!`git diff --name-only HEAD~5..HEAD`
**Code to Review:**
$ARGUMENTS
Provide comprehensive feedback considering project context.
```
1. **Descriptive names** - Clear, action-oriented command names
2. **Explicit invocation** - Users trigger commands intentionally
3. **Argument clarity** - Use argument-hint for discoverability
4. **Scope appropriately** - Project commands for team, personal for you
5. **Tool restrictions** - Only grant necessary tool access
6. **Model selection** - Match model to task complexity
7. **Organization** - Use subdirectories for related commands
8. **Documentation** - Clear descriptions and argument hints
9. **Testing** - Verify with various inputs before sharing
10. **Security** - Never hardcode sensitive data
When user asks to create a slash command:
1. **Clarify purpose** - What prompt should be reusable?
2. **Choose scope** - Project or personal command?
3. **Design arguments** - $ARGUMENTS, $1/$2/$3, or none?
4. **Select name** - Descriptive, kebab-case filename
5. **Add frontmatter** - Description, tools, model, argument-hint
6. **Write prompt** - Clear, actionable command content
7. **Add features** - File references (@), bash commands (!)
8. **Test thoroughly** - Various arguments, edge cases
9. **Document usage** - Examples in comments or description
10. **Share if needed** - Commit project commands to git
Remember: Slash commands are for explicit, manual invocation of frequently-used prompts. Use skills for automatic, context-driven capabilities.
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/create-command/raw