Workflow Skill Designer

Meta-skill for creating structured workflow skills following the orchestrator + phases pattern. Generates complete skill packages with SKILL.md as coordinator and phases/ folder for execution details.

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│  Workflow Skill Designer                                         │
│  → Analyze requirements → Design orchestrator → Generate phases  │
└───────────────┬─────────────────────────────────────────────────┘
                │
    ┌───────────┼───────────┬───────────┐
    ↓           ↓           ↓           ↓
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ Phase 1 │ │ Phase 2 │ │ Phase 3 │ │ Phase 4 │
│ Require │ │  Orch   │ │ Phases  │ │ Valid   │
│ Analysis│ │ Design  │ │ Design  │ │ & Integ │
└─────────┘ └─────────┘ └─────────┘ └─────────┘
     ↓           ↓           ↓           ↓
  workflow    SKILL.md    phases/     Complete
  config     generated   0N-*.md     skill pkg

Target Output Structure

The skill this meta-skill produces follows this structure:

.claude/skills/{skill-name}/
├── SKILL.md                    # Orchestrator: coordination, data flow, TodoWrite
├── phases/
│   ├── 01-{phase-name}.md      # Phase execution detail (full content)
│   ├── 02-{phase-name}.md
│   ├── ...
│   └── 0N-{phase-name}.md
├── specs/                      # [Optional] Domain specifications
└── templates/                  # [Optional] Reusable templates

Core Design Patterns

Patterns extracted from successful workflow skill implementations (workflow-plan, project-analyze, etc.):

Pattern 1: Orchestrator + Progressive Loading

SKILL.md = Pure coordinator. Contains:

Architecture diagram (ASCII)
Execution flow with
```
Ref: phases/0N-xxx.md
```
markers
Phase Reference Documents table (read on-demand)
Data flow between phases
Core rules and error handling

Phase files = Full execution detail. Contains:

Complete agent prompts, bash commands, code implementations
Validation checklists, error handling
Input/Output specification
Next Phase link

Key Rule: SKILL.md references phase docs via

Ref:

markers. Phase docs are read only when that phase executes, not all at once.

Pattern 2: TodoWrite Attachment/Collapse

Phase starts:
  → Sub-tasks ATTACHED to TodoWrite (in_progress + pending)
  → Orchestrator executes sub-tasks sequentially

Phase ends:
  → Sub-tasks COLLAPSED back to high-level summary (completed)
  → Next phase begins

Pattern 3: Inter-Phase Data Flow

Phase N output → stored in memory/variable → Phase N+1 input
                  └─ or written to session file for persistence

Each phase receives outputs from prior phases via:

In-memory variables (sessionId, contextPath, etc.)
Session directory files (.workflow/active/{sessionId}/...)
Planning notes (accumulated constraints document)

Pattern 4: Conditional Phase Execution

Phase N output contains condition flag
  ├─ condition met → Execute Phase N+1
  └─ condition not met → Skip to Phase N+2

Pattern 5: Input Structuring

User input (free text) → Structured format before Phase 1:

GOAL: [objective]
SCOPE: [boundaries]
CONTEXT: [background/constraints]

Execution Flow

Phase 1: Requirements Analysis
   └─ Ref: phases/01-requirements-analysis.md
      ├─ Input source: commands, descriptions, user interaction
      └─ Output: workflowConfig (phases, data flow, agents, conditions)

Phase 2: Orchestrator Design (SKILL.md)
   └─ Ref: phases/02-orchestrator-design.md
      ├─ Input: workflowConfig
      └─ Output: .claude/skills/{name}/SKILL.md

Phase 3: Phase Files Design
   └─ Ref: phases/03-phase-design.md
      ├─ Input: workflowConfig + source content
      └─ Output: .claude/skills/{name}/phases/0N-*.md

Phase 4: Validation & Integration
   └─ Ref: phases/04-validation.md
      └─ Output: Validated skill package

Phase Reference Documents (read on-demand):

Phase	Document	Purpose
1	phases/01-requirements-analysis.md	Analyze workflow requirements from various sources
2	phases/02-orchestrator-design.md	Generate SKILL.md with orchestration patterns
3	phases/03-phase-design.md	Generate phase files preserving full execution detail
4	phases/04-validation.md	Validate structure, references, and integration

Input Sources

This meta-skill accepts workflow definitions from multiple sources:

Source	Description	Example
Existing commands	Convert `.claude/commands/` orchestrator + sub-commands	`plan.md` + `session/start.md` + `tools/*.md`
Text description	User describes workflow in natural language	"Create a 3-phase code review workflow"
Requirements doc	Structured requirements file	`requirements.md` with phases/agents/outputs
Existing skill	Refactor/redesign an existing skill	Restructure a flat skill into phases

Frontmatter Conversion Rules

When converting from command format to skill format:

Command Field	Skill Field	Transformation
`name`	`name`	Prefix with group: `plan` → `workflow-plan`
`description`	`description`	Append trigger phrase: `Triggers on "xxx"`
`argument-hint`	(removed)	Arguments handled in Input Processing section
`examples`	(removed)	Examples moved to inline documentation
`allowed-tools`	`allowed-tools`	Expand wildcards: `Skill(*)` → `Skill` , add commonly needed tools
`group`	(removed)	Embedded in `name` prefix

Orchestrator Content Mapping

What goes into SKILL.md vs what goes into phase files:

SKILL.md (Coordinator)

Section	Content	Source
Frontmatter	name, description, allowed-tools	Command frontmatter (converted)
Architecture Overview	ASCII diagram of phase flow	Derived from execution structure
Key Design Principles	Coordination rules	Extracted from command coordinator role
Execution Flow	Phase sequence with `Ref:` markers + Phase Reference table	Command execution process
Core Rules	Orchestration constraints	Command core rules
Input Processing	Structured format conversion	Command input processing
Data Flow	Inter-phase data passing	Command data flow
TodoWrite Pattern	Attachment/collapse lifecycle	Command TodoWrite sections
Post-Phase Updates	Planning notes / state updates between phases	Command inter-phase update code
Error Handling	Failure recovery	Command error handling
Coordinator Checklist	Pre/post phase actions	Command coordinator checklist
Related Commands	Prerequisites and follow-ups	Command related commands

Phase Files (Execution Detail)

Content	Rule
Full agent prompts	Preserve verbatim from source command
Bash command blocks	Preserve verbatim
Code implementations	Preserve verbatim
Validation checklists	Preserve verbatim
Error handling details	Preserve verbatim
Input/Output spec	Add if not present in source
Phase header	Add `# Phase N: {Name}`
Objective section	Add `## Objective` with bullet points
Next Phase link	Add `## Next Phase` with link to next

Critical Rule: Phase files must be content-faithful to their source. Do NOT summarize, abbreviate, or simplify. The phase file IS the execution instruction - every bash command, every agent prompt, every validation step must be preserved.

SKILL.md Template

markdown

---
name: {skill-name}
description: {description}. Triggers on "{trigger1}", "{trigger2}".
allowed-tools: {tools}
---

# {Title}

{One-paragraph description of what this skill does and what it produces.}

## Architecture Overview

{ASCII diagram showing phases and data flow}

## Key Design Principles

1. **{Principle}**: {Description}
...

## Auto Mode

When `--yes` or `-y`: {auto-mode behavior}.

## Execution Flow

{Phase sequence with Ref: markers}

**Phase Reference Documents** (read on-demand when phase executes):

| Phase | Document | Purpose |
|-------|----------|---------|
| 1 | [phases/01-xxx.md](phases/01-xxx.md) | ... |
...

## Core Rules

1. {Rule}
...

## Input Processing

{How user input is converted to structured format}

## Data Flow

{Inter-phase data passing diagram}

## TodoWrite Pattern

{Attachment/collapse lifecycle description with examples}

## Post-Phase Updates

{State updates between phases}

## Error Handling

{Failure recovery rules}

## Coordinator Checklist

{Pre/post phase action list}

## Related Commands

{Prerequisites and follow-ups}

Phase File Template