505 lines
14 KiB
Markdown
505 lines
14 KiB
Markdown
---
|
|
name: box-factory-slash-command-design
|
|
description: Interpretive guidance for designing Claude Code slash commands. Helps you apply official documentation effectively and create high-quality commands. Use when creating or reviewing slash commands.
|
|
---
|
|
|
|
# Slash Command Design Skill
|
|
|
|
This skill provides interpretive guidance and best practices for creating Claude Code slash commands. **ALWAYS fetch current official documentation before creating commands** - this skill helps you understand what the docs mean and how to create excellent commands.
|
|
|
|
## Required Reading Before Creating Commands
|
|
|
|
Fetch these docs with WebFetch every time:
|
|
|
|
- **https://code.claude.com/docs/en/slash-commands.md** - Core specification and examples
|
|
- **https://code.claude.com/docs/en/settings#tools-available-to-claude** - Verify tool names
|
|
- **https://code.claude.com/docs/en/model-config.md** - Model selection guidance
|
|
|
|
## Core Understanding
|
|
|
|
### Commands Are User-Triggered, Not Autonomous
|
|
|
|
**Key distinction:**
|
|
|
|
- **Commands** = User explicitly invokes with `/command-name`
|
|
- **Agents** = Claude autonomously delegates based on context
|
|
- **Skills** = Knowledge that loads when relevant
|
|
|
|
**Quality test:** If you want this to happen automatically based on context, it's an agent, not a command.
|
|
|
|
### Command Structure
|
|
|
|
Commands are Markdown files with optional YAML frontmatter:
|
|
|
|
```markdown
|
|
---
|
|
description: Brief description (optional, defaults to first line)
|
|
argument-hint: [expected-args]
|
|
allowed-tools: Tool1, Tool2
|
|
model: sonnet
|
|
disable-model-invocation: false
|
|
---
|
|
|
|
Command prompt content goes here.
|
|
Use $1, $2 for individual arguments or $ARGUMENTS for all.
|
|
```
|
|
|
|
## Frontmatter Fields (Official Specification)
|
|
|
|
All fields are optional:
|
|
|
|
| Field | Purpose | Default |
|
|
|-------|---------|---------|
|
|
| `description` | Brief command description for `/help` | First line of prompt |
|
|
| `argument-hint` | Expected arguments (e.g., `[pr-number] [priority]`) | None |
|
|
| `allowed-tools` | Restrict to specific tools (e.g., `Bash(git:*)`) | Inherits from conversation |
|
|
| `model` | Specific model to use | Inherits from conversation |
|
|
| `disable-model-invocation` | Prevents SlashCommand tool from auto-invoking | false |
|
|
|
|
**Best practice:** Always include `description` even though it's optional - improves discoverability and Claude's ability to use the SlashCommand tool.
|
|
|
|
## Argument Syntax (Official Specification)
|
|
|
|
**All arguments as single string:**
|
|
|
|
```markdown
|
|
$ARGUMENTS
|
|
```
|
|
|
|
Example: `/fix-issue 123 high-priority` → `$ARGUMENTS = "123 high-priority"`
|
|
|
|
**Individual positional arguments:**
|
|
|
|
```markdown
|
|
$1, $2, $3, etc.
|
|
```
|
|
|
|
Example: `/review-pr 456 high alice` → `$1="456"`, `$2="high"`, `$3="alice"`
|
|
|
|
**Official guidance:** "Use individual arguments (`$1`, `$2`) for complex commands with multiple parameters"
|
|
|
|
**Best practice:** Use `$1, $2` when you need arguments in different parts of the prompt or want to provide defaults. Keep argument parsing simple - if you need validation or complex logic, delegate to an agent.
|
|
|
|
## Advanced Features (Official Specification)
|
|
|
|
### Bash Execution with `!` Prefix
|
|
|
|
Execute bash commands before the prompt runs:
|
|
|
|
```markdown
|
|
---
|
|
allowed-tools: Bash(git:*)
|
|
---
|
|
|
|
!git status
|
|
|
|
Review the git status above and suggest next steps.
|
|
```
|
|
|
|
### File References with `@` Prefix
|
|
|
|
Include file contents in the prompt:
|
|
|
|
```markdown
|
|
Review @src/utils/helpers.js for potential improvements.
|
|
```
|
|
|
|
Multiple files: `Compare @src/old.js with @src/new.js`
|
|
|
|
### Subdirectory Namespacing
|
|
|
|
Organize commands in subdirectories:
|
|
|
|
```
|
|
.claude/commands/frontend/component.md → /component (project:frontend)
|
|
.claude/commands/backend/endpoint.md → /endpoint (project:backend)
|
|
```
|
|
|
|
Command name comes from filename, subdirectory appears in `/help` as namespace label.
|
|
|
|
## Decision Framework
|
|
|
|
### Command vs Agent vs Skill
|
|
|
|
**Use Command when:**
|
|
|
|
- User wants explicit control over when it runs
|
|
- Simple, deterministic operation
|
|
- Wrapping a bash script or tool sequence
|
|
- "I want to type `/something` to make X happen"
|
|
|
|
**Use Agent when:**
|
|
|
|
- Want autonomous delegation based on context
|
|
- Need isolated context window
|
|
- Require specific tool restrictions
|
|
- Complex decision-making involved
|
|
|
|
**Use Skill when:**
|
|
|
|
- Multiple contexts need the same knowledge
|
|
- Substantial procedural expertise
|
|
- Progressive disclosure would save tokens
|
|
|
|
## Best Practices (Opinionated Guidance)
|
|
|
|
### Delegation Pattern
|
|
|
|
Most robust commands delegate to specialized agents rather than implementing complex logic:
|
|
|
|
```markdown
|
|
---
|
|
description: Run full test suite and analyze failures
|
|
---
|
|
|
|
Use the test-runner agent to execute all tests and provide detailed failure analysis.
|
|
```
|
|
|
|
**Why this works:**
|
|
|
|
- Keeps command simple and focused
|
|
- Leverages specialized agent capabilities
|
|
- Avoids reimplementing logic
|
|
- Agent gets isolated context for complex work
|
|
|
|
**When to use:** Any command that needs file reading/parsing, complex decision trees, error recovery logic, or multi-step state management.
|
|
|
|
### Tool Restriction Pattern
|
|
|
|
For simple, deterministic operations, restrict tools for security and clarity:
|
|
|
|
```markdown
|
|
---
|
|
description: Show git status
|
|
allowed-tools: Bash(git status:*)
|
|
model: haiku
|
|
---
|
|
|
|
Run `git status` and display the output.
|
|
```
|
|
|
|
**Benefits:**
|
|
|
|
- Fast execution (haiku model)
|
|
- Restricted permissions
|
|
- Clear, single-purpose command
|
|
|
|
### Simple Sequential Pattern
|
|
|
|
**Commands CAN handle sequential bash operations** when they're straightforward and don't require file inspection or complex parsing:
|
|
|
|
```markdown
|
|
---
|
|
description: Install GitHub CLI if not present
|
|
allowed-tools: Bash
|
|
model: haiku
|
|
---
|
|
|
|
Check if gh CLI is installed. If not, provide installation instructions for the user's platform.
|
|
|
|
Simple workflow:
|
|
1. Check: `which gh` or `command -v gh`
|
|
2. If not found, provide platform-specific install guidance
|
|
3. Verify with `gh --version` if installed
|
|
4. Output success message or next steps
|
|
```
|
|
|
|
**This pattern is OK in commands when you have:**
|
|
|
|
✅ **3-5 sequential bash steps** - Simple linear workflow
|
|
✅ **Basic conditionals** - Simple if/else (installed vs not installed)
|
|
✅ **Simple verification** - Exit codes, command success/failure
|
|
✅ **User-facing instructions** - Output guidance, next steps
|
|
|
|
**When to keep it in a command:**
|
|
|
|
- Checking if a tool is installed (`which`, `command -v`)
|
|
- Installing via package manager (`brew install`, `apt-get install`)
|
|
- Running simple verification (`--version`, `status` checks)
|
|
- Providing user instructions based on results
|
|
- Linear workflows without branching complexity
|
|
|
|
**Rule of thumb:** If you can write it as 3-5 bash commands with simple if/else logic and no file reading, keep it in the command.
|
|
|
|
**Delegate to an agent when you need:**
|
|
|
|
❌ **File reading/parsing** - Requires Read, Grep, or complex text processing
|
|
❌ **Complex decision trees** - Framework detection, config file parsing, multi-path logic
|
|
❌ **Error recovery logic** - Retries, fallbacks, multiple failure modes
|
|
❌ **State management** - Tracking across multiple steps, rollback capability
|
|
❌ **Multiple tool orchestration** - Coordinating Read + Grep + Write + Bash
|
|
|
|
**Example requiring agent delegation:**
|
|
|
|
```markdown
|
|
# ❌ Too complex for command - needs agent
|
|
---
|
|
description: Set up test environment
|
|
---
|
|
|
|
Detect test framework by:
|
|
1. Read package.json, check for jest/mocha/vitest dependencies
|
|
2. Read test config files (.jestrc, mocha.opts, vitest.config.ts)
|
|
3. Scan for existing test files in src/, tests/, __tests__/
|
|
4. Parse configuration to determine coverage settings
|
|
5. Install missing dependencies based on framework
|
|
6. Generate framework-specific config if missing
|
|
7. Create example test files following detected patterns
|
|
8. Verify setup with test run
|
|
```
|
|
|
|
**Why this needs an agent:**
|
|
|
|
- Requires Read tool for multiple files
|
|
- Complex decision tree (framework detection)
|
|
- Config file parsing
|
|
- State management across steps
|
|
- Multiple failure modes to handle
|
|
- Error recovery (config generation, dependency installation)
|
|
|
|
**Better approach:**
|
|
|
|
```markdown
|
|
---
|
|
description: Set up test environment for current project
|
|
---
|
|
|
|
Use the test-setup agent to detect the test framework, install dependencies, and configure the testing environment.
|
|
```
|
|
|
|
**The threshold:**
|
|
|
|
- **Commands:** `which gh && gh --version || echo "Install with: brew install gh"`
|
|
- **Agents:** Anything requiring Read/Grep/Parse or complex multi-step decision-making
|
|
|
|
### Generation Pattern
|
|
|
|
For creating files/code, be specific about structure and requirements:
|
|
|
|
```markdown
|
|
---
|
|
description: Create a new React component with TypeScript
|
|
argument-hint: component-name
|
|
---
|
|
|
|
Create a new React component named `$1` in the components directory.
|
|
|
|
Include:
|
|
- TypeScript interface for props
|
|
- Basic component structure with proper typing
|
|
- Export statement
|
|
- Test file in __tests__ directory
|
|
|
|
Follow project conventions for imports and file structure.
|
|
```
|
|
|
|
## Common Pitfalls (Best Practices)
|
|
|
|
### Pitfall #1: Knowledge Storage in Commands
|
|
|
|
**Problem:** Using commands to store documentation instead of actions
|
|
|
|
**Example of wrong pattern:**
|
|
|
|
```markdown
|
|
---
|
|
description: Show API documentation standards
|
|
---
|
|
|
|
Our API documentation standards:
|
|
[50 lines of guidelines...]
|
|
```
|
|
|
|
**Why it's wrong:** This is knowledge, not an action. Commands should DO things.
|
|
|
|
**Better approach:** Create a skill for standards, command for action:
|
|
|
|
```markdown
|
|
---
|
|
description: Generate API documentation for current file
|
|
---
|
|
|
|
Use the api-documentation skill to generate comprehensive API docs for the current file.
|
|
```
|
|
|
|
### Pitfall #2: Reimplementing Agent Logic
|
|
|
|
**Problem:** Commands with complex logic that agents handle better
|
|
|
|
**Example of wrong pattern:**
|
|
|
|
```markdown
|
|
---
|
|
description: Run tests
|
|
---
|
|
|
|
First, scan for test files in src/, tests/, and __tests__.
|
|
Then determine the test framework by checking package.json.
|
|
If Jest, run `npm test`. If pytest, run `pytest -v`.
|
|
Parse the output for failures and categorize by severity...
|
|
```
|
|
|
|
**Why it's wrong:** Too much logic, too many decisions, better in isolated context.
|
|
|
|
**Better approach:**
|
|
|
|
```markdown
|
|
---
|
|
description: Run full test suite
|
|
---
|
|
|
|
Use the test-runner agent to execute the full test suite and analyze failures.
|
|
```
|
|
|
|
### Pitfall #3: Overly Complex Arguments
|
|
|
|
**Problem:** Arguments that need extensive parsing or validation
|
|
|
|
**Example of questionable pattern:**
|
|
|
|
```markdown
|
|
/deploy env=staging branch=main force=true rollback=false
|
|
```
|
|
|
|
**Why it's questionable:** No argument validation, no type checking, brittle parsing.
|
|
|
|
**Better approach:** Keep arguments simple, let agent handle complexity:
|
|
|
|
```markdown
|
|
---
|
|
description: Deploy to specified environment
|
|
argument-hint: environment
|
|
---
|
|
|
|
Deploy to $1 environment. The deployer agent will handle validation, rollback strategy, and confirmation.
|
|
```
|
|
|
|
### Pitfall #4: Scope Creep
|
|
|
|
**Problem:** Single command tries to do too much
|
|
|
|
**Example:**
|
|
|
|
```markdown
|
|
description: Test, lint, format, commit, and deploy
|
|
```
|
|
|
|
**Why it fails:** Multiple distinct operations with different failure modes.
|
|
|
|
**Better:** Separate commands or orchestrator agent that coordinates multiple specialized agents.
|
|
|
|
## Command Quality Checklist
|
|
|
|
Before finalizing a command:
|
|
|
|
**Structure (from official docs):**
|
|
|
|
- ✓ Valid YAML frontmatter (if used)
|
|
- ✓ Proper markdown formatting
|
|
- ✓ Filename is kebab-case (becomes command name)
|
|
|
|
**Best Practices (opinionated):**
|
|
|
|
- ✓ Includes `description` field for discoverability
|
|
- ✓ Uses `argument-hint` if arguments expected
|
|
- ✓ Action-oriented (not knowledge storage)
|
|
- ✓ Delegates to agents for complex logic (file parsing, decision trees, error recovery)
|
|
- ✓ Simple sequential bash is OK (3-5 steps, basic if/else)
|
|
- ✓ Arguments are simple (if present)
|
|
- ✓ Clear, single-purpose design
|
|
- ✓ Appropriate tool restrictions (if needed)
|
|
- ✓ Model choice matches complexity (haiku for simple, sonnet for complex)
|
|
|
|
## Path Resolution
|
|
|
|
**Official locations:**
|
|
|
|
- **Project-level:** `.claude/commands/` (shared with team)
|
|
- **User-level:** `~/.claude/commands/` (personal, all projects)
|
|
- **Plugin context:** `plugins/[name]/commands/` (when creating plugin commands)
|
|
|
|
**Resolution logic:**
|
|
|
|
1. If caller specifies exact path → use that
|
|
2. If in plugin context → use `plugins/[name]/commands/`
|
|
3. Default → `.claude/commands/` (project-level)
|
|
4. User-level → only when explicitly requested
|
|
|
|
## Name Normalization
|
|
|
|
Command names must be kebab-case (filename without .md extension):
|
|
|
|
**Transform these:**
|
|
|
|
- "Run Tests" → `run-tests.md`
|
|
- "create_component" → `create-component.md`
|
|
- "DeployStaging" → `deploy-staging.md`
|
|
|
|
## Example: Good Command Design
|
|
|
|
**Before (from hypothetical docs):**
|
|
|
|
```markdown
|
|
---
|
|
description: Create component
|
|
---
|
|
|
|
Create a new component.
|
|
```
|
|
|
|
**Issues:**
|
|
|
|
- ❌ Description too vague
|
|
- ❌ Prompt lacks specifics
|
|
- ❌ No argument handling when clearly needed
|
|
- ❌ No guidance on structure
|
|
|
|
**After (applying best practices):**
|
|
|
|
```markdown
|
|
---
|
|
description: Create a new React component with TypeScript and tests
|
|
argument-hint: component-name
|
|
---
|
|
|
|
Create a new React component named `$1`.
|
|
|
|
Requirements:
|
|
- Location: src/components/$1/$1.tsx
|
|
- TypeScript interface for props
|
|
- Proper exports (default and named)
|
|
- Test file: src/components/$1/__tests__/$1.test.tsx
|
|
- Storybook file: src/components/$1/$1.stories.tsx
|
|
|
|
Follow project conventions:
|
|
- Use existing component patterns as reference
|
|
- Include JSDoc comments
|
|
- Export types separately
|
|
```
|
|
|
|
**Improvements:**
|
|
|
|
- ✅ Specific description (React + TypeScript + tests)
|
|
- ✅ Clear argument placeholder and hint
|
|
- ✅ Detailed deliverables listed
|
|
- ✅ References project conventions
|
|
- ✅ Actionable and unambiguous
|
|
|
|
## Documentation References
|
|
|
|
These are the authoritative sources. Fetch them before creating commands:
|
|
|
|
**Core specifications:**
|
|
|
|
- https://code.claude.com/docs/en/slash-commands.md - Command structure, examples, patterns
|
|
|
|
**Tool verification:**
|
|
|
|
- https://code.claude.com/docs/en/settings#tools-available-to-claude - Current tool list
|
|
|
|
**Model selection:**
|
|
|
|
- https://code.claude.com/docs/en/model-config.md - Model guidance
|
|
|
|
**Remember:** Official docs provide structure and features. This skill provides best practices and patterns for creating excellent commands.
|