command-development

What this skill does

# Commands vs Skills

Guide to choosing between `commands/` (flat files) and `skills/` (folders) for creating slash commands.

## When to Use

Activate when:
- User asks "commands or skills?"
- Discussing command structure
- Migrating from commands to skills
- Questions about slash command creation

## Commands and Skills are Equivalent

Both create slash commands that users invoke with `/plugin:name`:

| Aspect        | Commands                         | Skills                                    |
| :------------ | :------------------------------- | :---------------------------------------- |
| **Location**  | `commands/name.md`               | `skills/name/SKILL.md`                    |
| **Invocation**| `/plugin:name`                   | `/plugin:name`                            |
| **Features**  | Basic frontmatter, arguments     | Advanced frontmatter, supporting files    |
| **Use case**  | Simple, single-file commands     | Complex workflows, need supporting files  |
| **Status**    | Works, backward compatible       | **Preferred** for new development         |

## When to Use Each

**Use Skills** (`skills/name/SKILL.md`):
- **Preferred** for all new development
- Need supporting files (templates, examples, scripts)
- Want `user-invocable: false` for background skills
- Want `disable-model-invocation: true` for manual-only skills
- Complex workflows needing organization

**Use Commands** (`commands/name.md`):
- Maintaining existing commands
- Prefer flat file structure
- Very simple single-purpose commands
- Backward compatibility needed

## Command Structure

### File Location

```
plugin-name/
└── commands/
    ├── command1.md
    ├── command2.md
    └── subcommand/
        └── action.md      # For /plugin:subcommand:action
```

### Command Naming

**Plugin auto-prefixes command names**:

**File**: `commands/start.md`
**Plugin**: `workflow`
**Invoked as**: `/workflow:start`

**CRITICAL**: Don't duplicate prefix!
- ✓ File: `start.md` → `/workflow:start`
- ✗ File: `workflow:start.md` → `/workflow:workflow:start`

### Basic Command Format

```yaml
---
name: command-name
description: Brief description of what command does
usage: |
  /plugin:command <required-arg> [optional-arg] --flag value
examples:
  - /plugin:command example1
  - /plugin:command example2 --verbose
---

# Command Name

Detailed description of command purpose and behavior.

## Arguments

### Required
- `arg1` - Description of required argument

### Optional
- `arg2` - Description of optional argument (default: value)

### Flags
- `--flag` - Description of flag

## Process

1. Step one
2. Step two
3. Step three

## Examples

### Example 1: Basic Usage
```bash
/plugin:command basic-example
```

What happens:
- [Explain the outcome]

### Example 2: Advanced Usage
```bash
/plugin:command complex-example --flag value
```

What happens:
- [Explain the outcome]

## Integration

- Works with: [Related plugins/commands]
- Requires: [Dependencies if any]
```

## YAML Frontmatter

### Required Fields

```yaml
---
name: command-name        # Must match filename
description: Brief desc   # Shows in help text
---
```

### Full Frontmatter

```yaml
---
name: command-name
description: One-line description for command listing
usage: |
  /plugin:command <required> [optional] --flag value
  /plugin:command --help
examples:
  - /plugin:command example1
  - /plugin:command example2 --verbose
  - /plugin:command --interactive
aliases:
  - shortname
  - alternate-name
---
```

## Argument Patterns

### Positional Arguments

```yaml
---
usage: |
  /plugin:create <plugin-name> [directory]
---

# Create Command

## Arguments
- `plugin-name` (required) - Name of plugin to create
- `directory` (optional) - Target directory (default: ./plugins)

## Examples
```bash
/plugin:create my-plugin
/plugin:create my-plugin ./custom-dir
```
```

### Flags and Options

```yaml
---
usage: |
  /plugin:validate [path] --strict --format <json|text>
---

# Validate Command

## Flags
- `--strict` - Enable strict validation mode
- `--format <format>` - Output format: json or text (default: text)

## Examples
```bash
/plugin:validate                    # Current directory, text format
/plugin:validate --strict           # Strict mode
/plugin:validate --format json      # JSON output
/plugin:validate ./my-plugin --strict --format json
```
```

### Subcommands

```yaml
---
usage: |
  /plugin:add skill <name>
  /plugin:add command <name>
  /plugin:add agent <name>
  /plugin:add hook <event>
---

# Add Command

Adds a component to existing plugin.

## Subcommands

### skill
Add a new skill to the plugin.
```bash
/plugin:add skill my-skill
```

### command
Add a new command to the plugin.
```bash
/plugin:add command my-command
```

### agent
Add a new agent to the plugin.
```bash
/plugin:add agent my-agent
```

### hook
Add an event hook to the plugin.
```bash
/plugin:add hook PreToolUse
```
```

## Command Patterns

### Simple Action Command

**Purpose**: Single, straightforward action

```yaml
---
name: build
description: Build the project
usage: /plugin:build [--watch]
examples:
  - /plugin:build
  - /plugin:build --watch
---

# Build Command

Compiles the project.

## Process

1. Clean output directory
2. Compile source files
3. Copy assets
4. Generate build report

## Flags

- `--watch` - Watch mode for development
```

### Interactive Workflow Command

**Purpose**: Multi-step guided process

```yaml
---
name: init
description: Initialize new project interactively
usage: /plugin:init [project-name]
examples:
  - /plugin:init
  - /plugin:init my-project
---

# Init Command

Interactive project initialization.

## Process

1. **Prompt for project details**:
   - Project name (if not provided)
   - Description
   - License type
   - Dependencies

2. **Create structure**:
   - Generate directory layout
   - Create configuration files
   - Install dependencies

3. **Verify**:
   - Run validation
   - Show summary
```

### Multi-Action Command

**Purpose**: Multiple related actions in one command

```yaml
---
name: task
description: Manage tasks
usage: |
  /plugin:task create <title>
  /plugin:task list [--status pending|done]
  /plugin:task complete <id>
  /plugin:task delete <id>
examples:
  - /plugin:task create "Implement feature"
  - /plugin:task list
  - /plugin:task list --status pending
  - /plugin:task complete 1
---

# Task Command

Complete task management.

## Subcommands

### create
Create a new task.

### list
List all tasks, optionally filtered by status.

### complete
Mark a task as completed.

### delete
Delete a task.
```

### Delegating Command

**Purpose**: Routes to skills or agents

```yaml
---
name: start
description: Start workflow with auto-detection
usage: |
  /plugin:start <description>
  /plugin:start <description> --mode <auto|spec|plan|simple>
examples:
  - /plugin:start "Implement user authentication"
  - /plugin:start "Fix login bug" --mode simple
---

# Start Command

Initiates workflow with complexity detection.

## Process

1. **Analyze request**:
   - Parse description
   - Detect complexity
   - Identify project context

2. **Route to appropriate workflow**:
   - Complex → Spec + Validation
   - Medium → Spec + TDD
   - Simple → Simple Planning

3. **Hand off to skill/agent**:
   - Invoke appropriate skill
   - Or launch specialized agent
```

## Using AskUserQuestion

Commands can ask interactive questions:

```markdown
## Process

1. **Gather plugin details**:
   Use AskUserQuestion to ask:
   - Plugin name
   - Description
   - Components to include (commands, skills, agents, hooks)
   - Author name

2. **Create structure**:
   Based on user responses, generate plugin files

3. **Confirm**:
   Show what was created
```

Example in command:
```markdown
Ask user to choose components:
- [ ] Commands - User-invoked actions
- [ ] Skills - Guidance and workflows
- [ ] Agents - Autonomous workers
- [ ] Hooks - Event handlers

Then create the selected components.
```

## Integration Patterns

##