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

This skill provides interpretive guidance and best practices for creating Claude Code slash commands. It helps you understand what the docs mean and how to create excellent commands.

Workflow Selection

If you need to...	Go to...
Understand command vs agent vs skill	Decision Framework
See basic command structure	Quick Start
Learn frontmatter fields	Frontmatter Fields
Use arguments in commands	Argument Syntax
Execute bash or reference files	Advanced Features
Decide delegation vs direct implementation	Best Practices
Avoid common mistakes	Common Pitfalls
Validate before completing	Quality Checklist

Quick Start

Create a command at .claude/commands/my-command.md:

---
description: Brief description of what this command does
argument-hint: expected-args
---

Command prompt content here.
Use $1, $2 for individual arguments or $ARGUMENTS for all.

Delegation pattern (recommended for complex tasks):

---
description: Run full test suite and analyze failures
---

Use the test-runner agent to execute all tests and provide detailed failure analysis.

Official Documentation

Claude Code changes rapidly and is post-training knowledge. Fetch these docs when creating commands to ensure current syntax:

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

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

Run `git status` and display the output.

Benefits:

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

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.

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)

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:

If caller specifies exact path → use that
If in plugin context → use plugins/[name]/commands/
Default → .claude/commands/ (project-level)
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

slash-command-design