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

name, description

name	description
box-factory-slash-command-design	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:

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

$ARGUMENTS

Example: /fix-issue 123 high-priority → $ARGUMENTS = "123 high-priority"

Individual positional arguments:

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

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

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:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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