# Skill Patterns Reference

Common patterns used in Claude Code skills.

## Pattern 1: Subcommands

Route to different behaviors based on first argument. Used by: efcore, gitflow.

```yaml
---
name: my-tool
description: Multi-command tool
argument-hint: "<command> [options]"
disable-model-invocation: true
---

<quick_start>
` ` `bash
/my-tool status
/my-tool create
/my-tool deploy
` ` `
</quick_start>

<parameters>
<subcommands>
| Command | Description |
|---------|-------------|
| `status` | Show current status |
| `create` | Create new item |
| `deploy` | Deploy to environment |
</subcommands>
</parameters>

<entry_point>
**ROUTING LOGIC:**
1. Parse command from input
2. Route to command-specific step:

| Command | Route To |
|---------|----------|
| `status` | `steps/status/step-00-init.md` |
| `create` | `steps/create/step-00-init.md` |
| `deploy` | `steps/deploy/step-00-init.md` |
</entry_point>
```

## Pattern 2: Flags (Enable/Disable)

Toggle behavior with flags. Used by: controller.

```yaml
<parameters>
<flags>
**Enable flags (lowercase):**
| Short | Long | Description |
|-------|------|-------------|
| `-a` | `--auto` | Skip confirmations |
| `-v` | `--verbose` | Detailed output |

**Disable flags (UPPERCASE):**
| Short | Long | Description |
|-------|------|-------------|
| `-A` | `--no-auto` | Disable auto mode |
| `-V` | `--no-verbose` | Disable verbose |
</flags>
</parameters>
```

Parsing in step-00-init:
```
Enable flags (lowercase - turn ON):
  -a or --auto    → {auto_mode} = true
  -v or --verbose → {verbose} = true

Disable flags (UPPERCASE - turn OFF):
  -A or --no-auto    → {auto_mode} = false
  -V or --no-verbose → {verbose} = false
```

## Pattern 3: Dynamic Context Injection

Inject runtime information into skill content. Used by: efcore.

```yaml
---
name: my-skill
description: Skill with runtime context
---

## Current state (auto-injected)
- Branch: !`git branch --show-current`
- Files: !`ls -la src/ | head -10`
- Version: !`node -p "require('./package.json').version"`
```

The `` !`command` `` syntax runs the command before skill content is sent to Claude.

## Pattern 4: Argument Placeholders

Access user arguments in skill content.

```markdown
## Task
Process the following: $ARGUMENTS

## Specific arguments
First arg: $1
Second arg: $2
All args: $ARGUMENTS
```

## Pattern 5: XML-Style Sections

Structure skill content with XML tags. Standard sections:

| Section | Purpose | When to use |
|---------|---------|-------------|
| `<objective>` | One-paragraph purpose statement | Always |
| `<quick_start>` | Usage examples | Always |
| `<parameters>` | Flags, subcommands, parsing | When skill has args |
| `<workflow>` | High-level numbered steps | Always |
| `<state_variables>` | Persistent variables table | Progressive skills |
| `<entry_point>` | First step to load | Progressive skills |
| `<step_files>` | Step file mapping table | Progressive skills |
| `<execution_rules>` | Key constraints | Always |
| `<security_rules>` | Mandatory security checks | When security-critical |
| `<success_criteria>` | Completion conditions | Always |

## Pattern 6: State Variables

Persist data across progressive steps.

```xml
<state_variables>
| Variable | Type | Description |
|----------|------|-------------|
| `{name}` | string | Item name |
| `{scope}` | string | Target scope |
| `{auto_mode}` | boolean | Skip confirmations |
| `{items}` | object[] | Collected items |
</state_variables>
```

Variables are referenced as `{variable_name}` throughout steps and are maintained in conversation context.

## Pattern 7: AskUserQuestion Integration

Use AskUserQuestion for interactive choices.

```yaml
AskUserQuestion:
  header: "Short Label"        # Max 12 chars
  question: "Full question?"
  options:
    - label: "Option A (Recommended)"
      description: "What this option does"
    - label: "Option B"
      description: "What this option does"
  multiSelect: false           # true for checkboxes
```

## Pattern 8: Skill Chaining

Call other skills from within a skill.

```markdown
After completing this step:
1. Run `/other-skill arg1`
2. Continue with next step
```

Or use the Skill tool:
```
Use Skill tool: skill="other-skill", args="arg1 arg2"
```

## Pattern 9: MCP Tool Integration

Call MCP tools from skill steps.

```markdown
### Validate conventions
Call `mcp__smartstack__validate_conventions` with:
  - target: "{entity_path}"
  - type: "controller"
```

## Pattern 10: Compact Output Tables

Display results in scannable tables, not prose.

```markdown
| Property | Value |
|----------|-------|
| Name | {name} |
| Status | OK |
| Files | 3 created |
```
