Command Development Skill

A Claude Code skill for advanced slash command authoring — covering frontmatter configuration, dynamic arguments, conditional logic, multi-step workflows, and command composition patterns for Claude Code projects.

When to Use This Skill

Choose this skill when:

• Building complex multi-step commands with conditional logic
• Creating command libraries for team standardization
• Developing parameterized commands with validation
• Building commands that compose other commands
• Implementing advanced command patterns (templates, generators, workflows)

Consider alternatives when:

• You need simple one-step commands (use the command-creator skill)
• You need programmatic automation (use a scripting language)
• You need CI/CD pipelines (use GitHub Actions or similar)

Quick Start

Copy
# Set up a command development workspace
mkdir -p .claude/commands

# Create an advanced command with full frontmatter
claude "help me create a command for database migration with rollback support"

Copy
# .claude/commands/db-migrate.md
---
description: Run database migrations with safety checks and rollback
arguments:
  - name: direction
    description: Migration direction (up, down, or status)
    required: true
    default: up
  - name: steps
    description: Number of migration steps (for rollback)
    required: false
    default: "1"
---

# Database Migration: $ARGUMENTS.direction

## Pre-flight checks
1. Verify database connection is working
2. Check current migration status with `npx prisma migrate status`
3. If direction is "status", show current state and stop here

## Execute migration
4. If direction is "up":
   - Run `npx prisma migrate deploy` to apply pending migrations
   - Run `npx prisma generate` to update the client
5. If direction is "down":
   - Identify the last $ARGUMENTS.steps migrations
   - Run rollback for each migration in reverse order
   - Verify schema matches expected state

## Post-migration
6. Run a quick smoke test on critical database queries
7. Report migration result: what was applied/rolled back and current state

Core Concepts

Frontmatter Options

Field	Type	Description
description	string	Command help text (shown in / menu)
arguments	array	List of typed, documented parameters
arguments[].name	string	Variable name for $ARGUMENTS.name
arguments[].description	string	Help text for this parameter
arguments[].required	boolean	Whether invocation fails without it
arguments[].default	string	Fallback value when not provided

Command Composition

Copy
# .claude/commands/release.md
---
description: Full release workflow combining multiple steps
arguments:
  - name: version
    description: Semantic version number (e.g., 1.2.3)
    required: true
---

# Release v$ARGUMENTS.version

Execute these steps in order:

1. Run the /test command to verify all tests pass
2. Run the /lint command to check code quality
3. Update version in package.json to $ARGUMENTS.version
4. Run the /changelog command to generate release notes
5. Create git tag v$ARGUMENTS.version
6. Run the /deploy production command
7. Create GitHub release with the generated changelog

Conditional Workflow Patterns

Copy
# .claude/commands/setup.md
---
description: Set up development environment based on project type
arguments:
  - name: project_type
    description: Type of project (frontend, backend, fullstack)
    required: true
---

# Environment Setup: $ARGUMENTS.project_type

Detect which package manager is in use (npm, yarn, pnpm, or bun).

If $ARGUMENTS.project_type is "frontend" or "fullstack":
- Install frontend dependencies
- Set up environment variables from .env.example
- Build the frontend dev server config

If $ARGUMENTS.project_type is "backend" or "fullstack":
- Install backend dependencies
- Set up database (check for Docker, use local fallback)
- Run database migrations
- Seed development data

For all types:
- Verify the development server starts without errors
- Print a summary of the setup with next steps

Configuration

Parameter	Type	Default	Description
description	string	—	Required help text for the command
arguments	array	[]	Command parameters with name, description, required, default
arguments[].name	string	—	Variable name referenced as $ARGUMENTS.name
arguments[].required	boolean	false	Whether invocation requires this argument
arguments[].default	string	""	Fallback value when argument is omitted

Best Practices

1. Design commands as declarative workflows, not imperative scripts — describe the desired outcome and let Claude determine the implementation; "ensure all tests pass" is more resilient than "run jest --coverage --bail."

2. Use default argument values to reduce friction — set sensible defaults for optional arguments so the most common usage requires zero configuration; users can override when needed.

3. Structure multi-step commands with numbered steps — Claude follows numbered instructions more reliably than unstructured prose; each step should be a single clear action with a verifiable outcome.

4. Include error handling instructions in the command body — tell Claude what to do when a step fails: "If the migration fails, roll back to the previous state and report the error" prevents undefined behavior.

5. Document commands with usage examples — add a comment block at the end of the command showing common invocations like /deploy staging, /deploy production --skip-tests so users know the expected patterns.

Common Issues

Command does too much and takes too long — Break monolithic commands into composable smaller commands. A /release command should call /test, /build, /deploy rather than reimplementing everything inline.

Arguments with spaces or special characters break — Arguments are passed as strings, but special characters can cause issues. When documenting arguments, specify expected format (e.g., "version number like 1.2.3" or "environment name: staging or production").

Command behavior varies between runs — Natural language instructions can be interpreted differently. Add explicit success criteria ("verify the server responds with HTTP 200 at /api/health") and constraints ("do not modify files outside the src/ directory").