command-optimization

name	command-optimization
description	CLI command development specialist. Use when creating commands, designing argument parsing, automating tasks, or implementing CLI best practices. Specializes in command design patterns and user experience.
author	Joseph OBrien
status	unpublished
updated	2025-12-23
version	1.0.1
tag	skill
type	skill

Command Optimization

This skill specializes in creating, designing, and optimizing command-line interfaces. It focuses on command design patterns, argument parsing, task automation, and CLI best practices.

When to Use This Skill

• When creating new CLI commands
• When designing command interfaces
• When optimizing existing commands
• When implementing argument parsing
• When automating tasks via CLI
• When improving command user experience

What This Skill Does

1. Command Design: Creates well-structured CLI commands
2. Argument Parsing: Designs intuitive argument and option structures
3. Task Automation: Automates repetitive tasks through commands
4. User Experience: Improves command usability and feedback
5. Error Handling: Implements robust error handling and validation
6. Documentation: Creates clear command documentation and help text

How to Use

Create Command

Create a command to generate React components

Design a CLI command for database migrations

Optimize Command

Improve the user experience of this command

Command Design Patterns

Task-Oriented Commands

Structure:

• Clear action verb (generate, create, build)
• Target object (component, migration, test)
• Options for customization
• Helpful output and feedback

Example:

# Good: Clear and actionable
npm run generate:component UserProfile

# Bad: Unclear purpose
npm run make UserProfile

Analysis Commands

Structure:

• Analysis type (analyze, check, audit)
• Target to analyze
• Output format options
• Actionable recommendations

Example:

# Good: Clear analysis command
npm run analyze:dependencies -- --outdated

# Bad: Vague command
npm run check

Argument Handling

File/Directory Arguments

Pattern:

• Accept single file or directory
• Support glob patterns
• Validate existence
• Handle permissions

Example:

# Single file
lint src/utils.js

# Directory
lint src/

# Glob pattern
lint "src/**/*.js"

Configuration Options

Common Options:

• --config: Custom configuration file
• --output: Output directory or format
• --verbose: Detailed logging
• --dry-run: Preview without execution
• --force: Override safety checks

Error Handling

Input Validation

Check:

• File/directory existence
• Read/write permissions
• File format validity
• Required dependencies
• Configuration syntax

Error Messages

Good Error Messages:

• Clear description of the problem
• Specific location (file, line)
• Suggested fix
• Context about why it failed

Example:

# Good
Error: Configuration file not found: .eslintrc.json
  Run 'npm run init:config' to create it.

# Bad
Error: File not found

Examples

Example 1: Component Generator Command

Input: Create a command to generate React components

Output:

## Command: generate:component

### Usage
```bash
npm run generate:component ComponentName [options]

Options

• --path <path>: Output path (default: src/components)
• --type <type>: Component type (functional|class) (default: functional)
• --with-tests: Generate test file
• --with-styles: Generate stylesheet

Examples

# Basic component
npm run generate:component UserCard

# With options
npm run generate:component UserCard --path src/features/users --with-tests --with-styles

Implementation

// scripts/generate-component.js
const componentName = process.argv[2];
const options = parseArgs(process.argv.slice(3));

if (!componentName) {
  console.error('Error: Component name required');
  console.log('Usage: npm run generate:component <Name>');
  process.exit(1);
}

generateComponent(componentName, options);

Example 2: Database Migration Command

Input: Create a database migration command

Output:

## Command: db:migrate

### Usage
```bash
npm run db:migrate [migration-name] [options]

Options

• --create <table>: Create new migration for table
• --rollback: Rollback last migration
• --status: Show migration status
• --to <version>: Migrate to specific version

Examples

# Create migration
npm run db:migrate --create users

# Run migrations
npm run db:migrate

# Check status
npm run db:migrate --status

# Rollback
npm run db:migrate --rollback

## Reference Files

- **`references/SLASH_COMMAND.template.md`** - Slash command template with frontmatter, dynamic context, and workflow structure

## Best Practices

### Command Design

1. **Clear Names**: Use descriptive, action-oriented names
2. **Consistent Patterns**: Follow project conventions
3. **Helpful Defaults**: Sensible defaults for common use cases
4. **Good Feedback**: Clear output and progress indicators
5. **Error Handling**: Graceful failure with helpful messages

### User Experience

- **Progressive Disclosure**: Show basic usage, advanced options in help
- **Validation**: Validate inputs early with clear errors
- **Confirmation**: Ask for confirmation on destructive operations
- **Dry Run**: Support --dry-run for preview
- **Verbose Mode**: --verbose for detailed output

### Documentation

- **Help Text**: Clear, concise help for each command
- **Examples**: Include practical examples
- **Error Messages**: Explain what went wrong and how to fix
- **README**: Document commands in project README

## Related Use Cases

- Creating project-specific commands
- Automating development tasks
- Building CLI tools
- Improving command usability
- Standardizing command patterns