aiskillstore/when-creating-slash-commands-use-slash-command-encoder

Slash Command Encoder SOP

Overview

Create ergonomic slash commands (/command) for fast, unambiguous access to micro-skills with auto-discovery, intelligent routing, parameter validation, and command chaining.

Agents & Responsibilities

coder

Role: Command implementation and handler logic Responsibilities:

• Implement command handlers
• Create validation logic
• Build routing mechanisms
• Test command functionality

base-template-generator

Role: Generate command templates and boilerplate Responsibilities:

• Create command templates
• Generate documentation
• Build example commands
• Create test scaffolding

Phase 1: Design Command Interface

Objective

Design command syntax, parameters, and behavior specifications.

Scripts

# Generate command template
npx claude-flow@alpha command template \
  --name "analyze" \
  --description "Analyze codebase for patterns" \
  --output commands/analyze.js

# Define command schema
cat > command-schema.json <<EOF
{
  "name": "analyze",
  "alias": "a",
  "description": "Analyze codebase for patterns",
  "parameters": [
    {
      "name": "path",
      "type": "string",
      "required": true,
      "description": "Path to analyze"
    },
    {
      "name": "depth",
      "type": "number",
      "required": false,
      "default": 3,
      "description": "Analysis depth"
    }
  ],
  "examples": [
    "/analyze ./src",
    "/analyze ./src --depth 5"
  ]
}
EOF

# Validate schema
npx claude-flow@alpha command validate --schema command-schema.json

Command Design Patterns

Simple Command:

/deploy

Command with Arguments:

/analyze ./src

Command with Flags:

/test --watch --coverage

Command with Subcommands:

/git commit -m "message"
/git push origin main

Memory Patterns

# Store command definition
npx claude-flow@alpha memory store \
  --key "commands/analyze/schema" \
  --file command-schema.json

Phase 2: Generate Command Code

Objective

Implement command handler with validation, routing, and execution logic.

Scripts

# Generate command handler
npx claude-flow@alpha command generate \
  --schema command-schema.json \
  --output commands/analyze-handler.js

# Implement validation logic
npx claude-flow@alpha command add-validation \
  --command analyze \
  --rules validation-rules.json

# Add routing logic
npx claude-flow@alpha command add-routing \
  --command analyze \
  --route-to "task-orchestrator"

# Build command registry
npx claude-flow@alpha command registry build \
  --commands ./commands \
  --output command-registry.json

Command Handler Template

// commands/analyze-handler.js
module.exports = {
  name: 'analyze',
  alias: 'a',
  description: 'Analyze codebase for patterns',

  parameters: [
    {
      name: 'path',
      type: 'string',
      required: true,
      validate: (value) => {
        if (!fs.existsSync(value)) {
          throw new Error(`Path not found: ${value}`);
        }
        return true;
      }
    },
    {
      name: 'depth',
      type: 'number',
      required: false,
      default: 3,
      validate: (value) => {
        if (value < 1 || value > 10) {
          throw new Error('Depth must be between 1 and 10');
        }
        return true;
      }
    }
  ],

  async execute(args) {
    const { path, depth } = args;

    // Validate parameters
    this.validateParameters(args);

    // Route to appropriate agent
    const result = await this.routeToAgent('code-analyzer', {
      action: 'analyze',
      path,
      depth
    });

    return result;
  },

  validateParameters(args) {
    for (const param of this.parameters) {
      const value = args[param.name];

      if (param.required && value === undefined) {
        throw new Error(`Required parameter missing: ${param.name}`);
      }

      if (value !== undefined && param.validate) {
        param.validate(value);
      }
    }
  },

  async routeToAgent(agentType, payload) {
    // Implementation of agent routing
    return await claudeFlow.agent.execute(agentType, payload);
  }
};

Phase 3: Test Command

Objective

Validate command functionality with comprehensive testing.

Scripts

# Test command registration
npx claude-flow@alpha command test-register --command analyze

# Test parameter validation
npx claude-flow@alpha command test \
  --command analyze \
  --input '{"path": "./src", "depth": 3}'

# Test error handling
npx claude-flow@alpha command test \
  --command analyze \
  --input '{"path": "./nonexistent"}' \
  --expect-error

# Run integration tests
npx claude-flow@alpha command test-suite \
  --commands ./commands \
  --output test-results.json

Test Cases

// tests/analyze-command.test.js
describe('analyze command', () => {
  it('should validate required parameters', async () => {
    await expect(
      commands.analyze.execute({})
    ).rejects.toThrow('Required parameter missing: path');
  });

  it('should validate path exists', async () => {
    await expect(
      commands.analyze.execute({ path: './nonexistent' })
    ).rejects.toThrow('Path not found');
  });

  it('should use default depth', async () => {
    const result = await commands.analyze.execute({ path: './src' });
    expect(result.config.depth).toBe(3);
  });

  it('should accept custom depth', async () => {
    const result = await commands.analyze.execute({
      path: './src',
      depth: 5
    });
    expect(result.config.depth).toBe(5);
  });
});

Phase 4: Document Usage

Objective

Create comprehensive documentation for command usage.

Scripts

# Generate command documentation
npx claude-flow@alpha command docs \
  --command analyze \
  --output docs/commands/analyze.md

# Generate help text
npx claude-flow@alpha command help-text \
  --command analyze \
  --output commands/analyze-help.txt

# Build command catalog
npx claude-flow@alpha command catalog \
  --all \
  --output docs/command-catalog.md

# Generate usage examples
npx claude-flow@alpha command examples \
  --command analyze \
  --count 5 \
  --output docs/examples/analyze-examples.md

Documentation Template

# /analyze Command

## Description
Analyze codebase for patterns, complexity, and improvement opportunities.

## Syntax

/analyze <path> [--depth <number>]

## Parameters

### path (required)
- Type: string
- Description: Path to analyze
- Example: `./src`, `./components`

### --depth (optional)
- Type: number
- Default: 3
- Range: 1-10
- Description: Analysis depth level

## Examples

```bash
# Basic usage
/analyze ./src

# With custom depth
/analyze ./src --depth 5

# Analyze specific directory
/analyze ./components --depth 2

Output

Returns analysis report with:

• Complexity metrics
• Pattern detection results
• Improvement recommendations
• File statistics

Related Commands

• /test - Run tests on analyzed code
• /optimize - Apply optimization recommendations
• /refactor - Refactor based on analysis

## Phase 5: Deploy Command

### Objective
Install command to system and verify functionality.

### Scripts

```bash
# Build command package
npx claude-flow@alpha command build \
  --commands ./commands \
  --output dist/commands.bundle.js

# Install to system
npx claude-flow@alpha command install \
  --from dist/commands.bundle.js \
  --global

# Verify installation
npx claude-flow@alpha command list --installed

# Test installed command
npx claude-flow@alpha analyze ./src --depth 3

# Update command registry
npx claude-flow@alpha command registry update

# Generate shell completions
npx claude-flow@alpha command completions \
  --shell bash \
  --output ~/.bash_completion.d/claude-flow-commands

Installation Validation

# Check command is registered
if npx claude-flow@alpha command exists analyze; then
  echo "✓ Command installed successfully"
else
  echo "✗ Command installation failed"
  exit 1
fi

# Test command execution
RESULT=$(npx claude-flow@alpha analyze ./src)
if [ $? -eq 0 ]; then
  echo "✓ Command execution successful"
else
  echo "✗ Command execution failed"
  exit 1
fi

Success Criteria

• [ ] Command interface designed
• [ ] Handler implemented
• [ ] Tests passing
• [ ] Documentation complete
• [ ] Command deployed

Performance Targets

• Command registration: <100ms
• Parameter validation: <50ms
• Command execution: <2s
• Help text generation: <100ms

Best Practices

1. Clear Naming: Use descriptive command names
2. Parameter Validation: Validate all inputs
3. Error Messages: Provide helpful error messages
4. Documentation: Include examples and usage
5. Testing: Comprehensive test coverage
6. Versioning: Version commands properly
7. Backwards Compatibility: Maintain compatibility
8. Auto-Discovery: Support command discovery

Common Issues & Solutions

Issue: Command Not Found

Symptoms: Command not recognized Solution: Run command install and verify registry

Issue: Parameter Validation Fails

Symptoms: Unexpected validation errors Solution: Check parameter types and validation rules

Issue: Command Execution Timeout

Symptoms: Command hangs Solution: Add timeout handling, check agent availability

Integration Points

• micro-skills: Commands trigger micro-skills
• task-orchestrator: Route to orchestrator
• memory-coordinator: Store command history

References

• CLI Design Patterns
• Command Interface Best Practices
• Parameter Validation Techniques