Skill Metadata

Field	Value
Version	1.0.0
Tier	Ops
Auto-load	When designing slash commands

What It Does

Slash command 설계 및 최적화 방법을 제공합니다. Argument parsing, tool permissions, agent orchestration을 포함한 command 구조를 다룹니다.

When to Use

새로운 slash command를 생성할 때
기존 command를 최적화하거나 리팩토링할 때
Workflow entry point를 설계할 때
User-facing automation을 구축할 때

Designing Slash Commands

Slash commands are user-facing entry points that orchestrate sub-agents, manage approvals, and coordinate multi-step workflows. They follow the Plan → Execute → Sync cadence.

Command File Structure

Location: .claude/commands/

---
name: command-name
description: Brief description of what the command does
argument-hint: "[param1] [param2] [optional-param]"
tools: Read, Write, Task, Bash(git:*)
model: sonnet
---

# Command Title

Brief description of functionality.

## Usage

- `/command-name param1 param2` — Basic usage
- Parameter descriptions
- Expected behavior

## Agent Orchestration

1. Call specific agent for task
2. Handle results
3. Provide user feedback

Command Design Patterns

Pattern 1: Planning Command

---
name: /alfred:1-plan
description: Write SPEC requirements in EARS syntax
argument-hint: "[title]"
tools: Read, Write, Task
model: sonnet
---

# SPEC Planning Command

Initiates SPEC authoring via spec-builder sub-agent.

## Usage

`/alfred:1-plan "User authentication system"`

## Agent Orchestration

1. Invoke spec-builder agent
2. Gather requirements via EARS patterns
3. Create SPEC file in `.moai/specs/`
4. Suggest next step: `/alfred:2-run`

Pattern 2: Code Review Command

---
name: /review-code
description: Trigger automated code review with quality analysis
argument-hint: "[file-pattern] [--strict]"
tools: Read, Glob, Grep, Task
model: sonnet
---

# Code Review Command

Analyzes code quality against TRUST 5 principles.

## Usage

- `/review-code src/**/*.ts` — Review TypeScript files
- `/review-code . --strict` — Strict mode (fail on warnings)

## Agent Orchestration

1. Scan files matching pattern
2. Invoke code-reviewer agent
3. Generate report with findings
4. Suggest fixes with severity levels

Pattern 3: Deployment Command

---
name: /deploy
description: Deploy application with safety gates
argument-hint: "[env] [--force]"
tools: Read, Write, Task, Bash(git:*)
model: haiku
---

# Deployment Command

Orchestrates multi-step deployment with approval gates.

## Usage

- `/deploy staging` — Deploy to staging
- `/deploy production --force` — Force production deploy

## Agent Orchestration

1. Validate deployment readiness
2. Run pre-deployment checks
3. Ask for user approval
4. Execute deployment
5. Monitor post-deployment

Argument Parsing Pattern

# Inside command execution
$ARGUMENTS              # Entire argument string
$1, $2, $3            # Individual arguments
$@                    # All arguments as array

# Example: /my-command arg1 arg2 --flag
# $ARGUMENTS = "arg1 arg2 --flag"
# $1 = "arg1"
# $2 = "arg2"
# $3 = "--flag"

High-Freedom: Orchestration Strategies

Sequential Execution

Command: /plan-and-implement
├─ Phase 1: spec-builder (SPEC creation)
└─ Phase 2: code-builder (TDD implementation)

Parallel Execution

Command: /analyze-project
├─ Agent 1: security-auditor (vulnerability scan)
├─ Agent 2: performance-analyzer (bottleneck detection)
└─ Agent 3: architecture-reviewer (design review)

Conditional Branching

Command: /fix-errors
├─ Check: Are tests failing?
│  ├─ YES → debug-helper agent
│  └─ NO → suggest next steps

Medium-Freedom: Command Templates

Status Check Command

name: /status
description: Show project status summary
argument-hint: "[--verbose]"
tools: Read, Bash(git:*)
model: haiku
---

# Status Check

Displays project health: SPEC status, test results, Git state.

## Checks

1. SPEC completeness
2. Test coverage
3. Git branch status
4. Recent commits
5. TODO items

Bulk Operation Command

name: /migrate
description: Run migration across multiple files
argument-hint: "[from] [to] [--preview]"
tools: Read, Glob, Bash
model: sonnet
---

# Migration Command

Migrates code patterns across project.

## Usage

- `/migrate v1-api v2-api --preview` — Show changes without applying
- `/migrate v1-api v2-api` — Apply migration

Low-Freedom: Safety & Approval Patterns

Approval Gate Pattern

# Inside command execution

echo "🔴 This action is destructive. Review carefully:"
echo "  • Will delete 10 files"
echo "  • Cannot be undone"
echo ""
read -p "Type 'yes' to confirm: " confirm

if [[ "$confirm" != "yes" ]]; then
  echo "❌ Cancelled"
  exit 1
fi

# Execute dangerous operation

Dry-Run Pattern

if [[ "${3:-}" == "--preview" ]]; then
  echo "🔍 Preview mode (no changes)"
  # Show what would happen
  exit 0
fi

# Execute actual changes

Command Registry

# List all commands
/commands

# View command details
/commands view /deploy

# Create new command
/commands create

# Edit command
/commands edit /deploy

# Delete command
/commands delete /deploy

Command Validation Checklist

name is kebab-case (e.g., /review-code)
description clearly explains purpose
argument-hint shows expected parameters
tools list is minimal and justified
model is haiku or sonnet
Agent orchestration is clearly defined
Arguments are properly parsed
Safety gates are in place for dangerous operations
Feedback to user is clear and actionable

Best Practices

✅ DO:

Design commands around workflows, not tools
Use agents for complex logic
Include preview/dry-run modes for risky operations
Provide clear feedback at each step
Link to next command in suggestions

❌ DON'T:

Make commands do too much (limit to 1 coherent workflow)
Require multiple parameters without defaults
Skip approval gates for destructive operations
Leave users guessing what happened

Reference: Claude Code Slash Commands documentation Version: 1.0.0

moai-cc-commands