creating-commands
Expert knowledge on creating slash commands for Claude Code. Use when designing or creating slash command .md files, understanding command arguments, or implementing bash execution.
- Category: discovered
- Tags: github, community
- Version: 1.0.0
- Author: walid
- Downloads: 0
- Updated: 2025-11-22
Download the latest version (v1.0.0) from this page.
SKILL.md
---
name: creating-commands
description: Expert knowledge on creating slash commands for Claude Code. Use when designing or creating slash command .md files, understanding command arguments, or implementing bash execution.
allowed-tools: Read, Grep, Glob
---
# Creating Slash Commands
This Skill provides comprehensive knowledge about creating effective slash commands in Claude Code.
## What Are Slash Commands?
Slash commands are user-invoked operations that start with `/`. When executed, they expand to a full prompt that Claude processes. They're different from subagents (which are automatically invoked) - slash commands require explicit user action.
**Critical Insight - Thin Wrappers**: The best practice for slash commands is to treat them as **thin wrappers** or **triggers** that activate Skills. The command file itself should NOT contain complex workflow logic - that belongs in a SKILL.md file. Commands are simply user-friendly aliases that point to specific skills or workflows.
**Command → Skill → (Subagent)**: This is the ideal flow:
1. User invokes `/command`
2. Command activates a specific Skill
3. Skill (the "playbook") guides the agent through the process
4. Agent may delegate to subagents as needed
## Plugin System Integration (October 2025)
As of October 2025, **plugins are the standard way to bundle and share slash commands**.
### What Are Plugins?
Plugins bundle multiple components together:
- Slash commands
- Subagents
- MCP servers
- Hooks
- Skills
### Installing Command Plugins
```bash
/plugin marketplace add <url> # Add plugin source
/plugin install <name> # Install plugin
/plugin list # Show installed plugins
/plugin uninstall <name> # Remove plugin
```
### Creating Commands in Plugins
Commands in plugins work identically to standalone commands:
- Same YAML frontmatter
- Same argument patterns
- Same bash execution
**Benefit**: Version control, selective activation, easier distribution across teams.
**See**: Official plugin documentation for creating distributable command collections.
## File Structure
**Project commands**: `.claude/commands/{command-name}.md`
**Personal commands**: `~/.claude/commands/{command-name}.md`
**Format**:
```yaml
---
description: Brief description of what this command does
argument-hint: [arg1] [arg2] # Optional
allowed-tools: Bash(git:*), Read, Write # Optional
model: haiku # Optional
disable-model-invocation: false # Optional
---
Command prompt that Claude will execute.
Can use $ARGUMENTS or $1, $2, $3, etc.
```
## YAML Frontmatter Fields
### Optional Fields (All Are Optional)
**description** (string)
- Brief description shown in `/help`
- If omitted, uses first line of prompt
- Keep concise (one sentence)
**argument-hint** (string)
- Shows expected arguments in autocomplete
- Examples: `[filename]`, `[message]`, `add [tag] | remove [tag]`
- Helps users know what to provide
**allowed-tools** (comma-separated string)
- Tools this command can use
- If omitted, inherits from conversation
- Use for command-specific restrictions
**model** (string)
- Specific model: `sonnet`, `opus`, `haiku`
- If omitted, inherits from conversation
- Use `haiku` for simple/fast commands
**disable-model-invocation** (boolean)
- If `true`, prevents SlashCommand tool from calling this command
- Default: `false`
- Use to keep commands user-only
## Command Arguments
### Using $ARGUMENTS (All Arguments)
Captures everything after the command name:
```yaml
---
description: Fix issue following coding standards
---
Fix issue #$ARGUMENTS following our coding standards
```
Usage:
```
/fix-issue 123 high-priority
# $ARGUMENTS becomes "123 high-priority"
```
### Using $1, $2, $3 (Positional Arguments)
Access specific arguments individually:
```yaml
---
description: Review PR with priority and assignee
argument-hint: [pr-number] [priority] [assignee]
---
Review PR #$1 with priority $2 and assign to $3.
Focus on security, performance, and code style.
```
Usage:
```
/review-pr 456 high alice
# $1="456", $2="high", $3="alice"
```
### @-Mention Support (August 2025)
Commands support **@-mentions** in arguments with typeahead support:
**File References:**
```bash
/review-pr @src/components/Header.tsx
/analyze @tests/test_auth.py
```
**Agent References:**
```bash
/delegate @agent:security-expert
/consult @agent:code-reviewer
```
**Benefits:**
- Typeahead completion for file paths
- Clear intent (@ signals reference)
- Works with glob patterns: `@src/utils/*.js`
**In Command Prompt:**
```yaml
---
description: Review specific files
argument-hint: [@file-path]
---
Review the implementation in $1
Focus on code quality, security, and maintainability.
```
**Usage**: `/review-files @src/auth.ts @tests/test_auth.ts`
### When to Use Which
**Use $ARGUMENTS**:
- Flexible, variable-length input
- Natural language descriptions
- Unknown number of args
**Use $1, $2, $3**:
- Fixed structure
- Specific fields needed
- Build complex prompts with arg positioning
## Bash Command Execution
Execute bash commands before the prompt runs using `!` prefix.
### Basic Execution
```yaml
---
allowed-tools: Bash(git:*)
---
## Current Status
Git status: !`git status`
## Your Task
Based on the above status, create a commit.
```
The `!` commands run first, output is included in prompt context.
### Multiple Commands
```yaml
---
allowed-tools: Bash(git:*), Bash(docker:*)
---
## Context
- Git status: !`git status`
- Docker status: !`docker ps`
- Current branch: !`git branch --show-current`
## Task
Deploy the current branch.
```
### Required: allowed-tools
**Must** include Bash tool permissions:
```yaml
---
allowed-tools: Bash(git status:*), Bash(git diff:*)
---
Current changes: !`git diff HEAD`
```
Specify exact commands or use wildcards:
- `Bash(git:*)` - All git commands
- `Bash(git status:*), Bash(git diff:*)` - Specific commands only
## File References
Include file contents using `@` prefix:
```yaml
---
description: Review implementation
---
Review the implementation in @src/utils/helpers.js
Compare @src/old-version.js with @src/new-version.js
```
When command runs, files are automatically included in context.
## Extended Thinking
Trigger extended thinking by including keywords:
```yaml
---
description: Solve complex algorithm problem
---
Think carefully about this algorithm optimization problem: $ARGUMENTS
Consider multiple approaches before implementing.
```
Keywords that trigger thinking: "think carefully", "consider", "analyze deeply"
## Commands and Skills Integration
**Best Practice**: Commands should activate Skills, not replace them.
### The Thin Wrapper Pattern
**Good - Command activates a Skill**:
```yaml
---
description: Run comprehensive code review
---
Activate the code-review-process Skill and review the current changes.
```
The actual review process (checklist, steps, output format) lives in `.claude/skills/code-review-process/SKILL.md`, not in the command file.
**Bad - Command contains the entire process**:
```yaml
---
description: Run comprehensive code review
---
Review the code changes following these steps:
1. Check code style
2. Verify error handling
3. Look for security issues
[... 50 more lines of detailed process ...]
```
This defeats modularity and makes the process hard to maintain.
### Why This Matters
- **Reusability**: Skills can be invoked by multiple commands or automatically by Claude
- **Maintainability**: Update the process once in SKILL.md, not in every command
- **Clarity**: Commands = user interface, Skills = implementation
- **Modularity**: Skills can reference other skills, creating composable workflows
## Programmatic Command Invocation (SlashCommand Tool)
Claude can **automatically invoke your commands** during conversations using the SlashCommand tool.
### How It Works
When you create a command with a populated `description` field, Claude can:
1. See the command in its tool list
2. Invoke it programmatically when relevant
3. Get the expanded prompt as input
**Example:**
```yaml
---
description: Run all tests and report failures
---
Run the complete test suite and analyze failures.
```
Claude might invoke this automatically when user says: "Make sure everything still works"
### Requirements
**Must Have:**
- `description` field populated (commands without descriptions are invisible)
- Under 15,000 character budget (see below)
**Optional:**
- `disable-model-invocation: true` - Prevents automatic invocation (user-only command)
### Character Budget Limit
Claude can only see commands that fit within `SLASH_COMMAND_TOOL_CHAR_BUDGET` (default: 15,000 characters).
**Managing Budget:**
- Keep command prompts concise
- Use `disable-model-invocation: true` for internal/debug commands
- Increase limit in settings.json if needed:
```json
{
"SLASH_COMMAND_TOOL_CHAR_BUDGET": 30000
}
```
### Best Practices
**Enable Automatic Invocation:**
- Clear, specific descriptions
- Common user phrases as triggers
- Thin wrappers to skills
**Disable Automatic Invocation:**
- Internal/debug commands
- Dangerous operations (deploy, delete)
- Commands needing explicit human approval
**Encouraging Usage:**
Reference commands in CLAUDE.md:
```markdown
To commit changes: Execute /commit command
For code review: Use /review command
```
This helps Claude map natural language → commands.
## Command Patterns
Seven main patterns have emerged for effective slash commands:
1. **Simple Action** - Single operation (run tests, build project)
2. **Context Gathering** - Collect and present information (status, review prep)
3. **Workflow** - Multi-step sequences (branch creation, PR automation)
4. **Validation** - Pre-flight checks (pre-commit, pre-deploy)
5. **Generation** - Create code/files (scaffolding, boilerplate)
6. **Skill Activation** - Thin wrapper to skill (complex workflows)
7. **Context Pollution Prevention** - Delegate massive outputs to subagents
**See [patterns.md](patterns.md) for detailed explanations, examples, and when to use each pattern.**
## Tool Restrictions and Model Selection
**Tool Restriction Patterns**:
```yaml
# Read-only
allowed-tools: Read, Grep, Glob
# Git only
allowed-tools: Bash(git:*)
# Multiple specific tools
allowed-tools: Bash(git:*), Bash(npm:*), Bash(pytest:*)
```
**Model Selection**:
- `model: haiku` - Fast, cheap (simple commands)
- Omit model field - Uses conversation model (default)
- `model: opus` - Complex reasoning
**See [reference.md](reference.md) for detailed bash execution patterns, security considerations, and troubleshooting.**
## Examples
**Quick Example - Thin Wrapper to Skill**:
```yaml
---
description: Run comprehensive code review
---
Activate the code-review-process Skill and review the current changes.
```
This demonstrates the thin wrapper pattern - the command is minimal, and the actual review process lives in a skill.
**See [examples.md](examples.md) for 7 detailed, real-world command examples covering all major patterns.**
## Command Organization
**Flat** (< 10 commands): All in `.claude/commands/`
**Subdirectories** (organized): Use `git/`, `testing/` folders for grouping
Note: Subdirectories don't affect command names - `/create-branch` works regardless of location.
## Best Practices
1. **Thin Wrappers** - Complex logic in skills, not commands
2. **Clear Descriptions** - "Run all tests and report failures" not "Tests"
3. **Argument Hints** - `[pr-number] [priority]` not `[args]`
4. **Specific Tools** - `Bash(git:*)` not `Bash(*)`
5. **Context First** - Gather info with `!` before instructions
6. **Heredocs** - Use for commit messages to prevent injection
## Testing and Troubleshooting
**Testing Methods**:
1. Manual invocation: `/your-command arg1 arg2`
2. Verify argument substitution: Check $1, $2 work
3. Test bash execution: Verify `!` commands run
**Common Issues**:
- Command not found → Check filename, restart Claude Code
- Arguments not substituting → Use $1 in content, not frontmatter
- Bash not running → Add `allowed-tools: Bash(...)`
- Permission denied → Check tool permissions
**See [reference.md](reference.md) for complete troubleshooting guide with diagnose and fix steps.**
## Validation Checklist
Before finalizing a command:
- [ ] Description is clear and concise
- [ ] Argument hints provided (if using args)
- [ ] Tool permissions specified (if using tools)
- [ ] Arguments use proper format ($ARGUMENTS or $1, $2, etc.)
- [ ] Bash commands have `!` and backticks
- [ ] Bash permissions match commands used
- [ ] Heredocs used for multi-line strings
- [ ] File tested with sample arguments
## Summary
**Essential Elements**:
1. Clear description (what it does)
2. Argument hints (what to provide)
3. Proper argument substitution ($ARGUMENTS or $1-$9)
4. Tool permissions (if using tools)
5. Context gathering (using `!` for bash)
**Success Criteria**:
- Command shows in `/help`
- Arguments substitute correctly
- Bash commands execute
- Claude produces expected result
- Tool permissions work