gh-racurry-neat-little-package-plugins-box-factory/skills/slash-command-design/SKILL.md

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