Create Skills Workflow

• Multi-phase workflows (3+ distinct steps)
• Skills that need state persistence across steps
• Interactive workflows with user decision points
• Skills with optional/conditional steps
• Workflows that save outputs for review

Don't use for:

• Simple single-action skills
• Skills that complete in one step
• Pure research/exploration skills

Phase 1: Design the Workflow

Ask yourself:

• What are the distinct phases of this workflow?
• What must complete before the next step can start?
• Which steps are optional or conditional?
• Where do users need to make decisions?

1.2 Map Dependencies

Step 1 ──► Step 2 ──► Step 3 ──┬──► Step 4a (if condition)
                               └──► Step 4b (else)

1.3 Define State Variables

What data needs to persist across steps?

state_variables:
  - task_description: string # What to do
  - task_id: string # Unique identifier
  - auto_mode: boolean # Skip confirmations
  - results: object # Accumulated results

skills/{skill-name}/
├── SKILL.md                    # Main entry point
├── steps/
│   ├── step-00-init.md         # Initialization (parse flags, setup)
│   ├── step-01-{name}.md       # First step
│   ├── step-02-{name}.md       # Second step
│   └── ...
└── references/                 # Optional: templates, patterns
    └── ...

2.2 Naming Conventions

• Steps: step-NN-{descriptive-name}.md
• NN = two-digit number (00, 01, 02...)
• Use kebab-case for names
• Keep names short but descriptive

• Step Template - Base structure for any step
• Ask Patterns - AskUserQuestion patterns
• State Management - Persisting data across steps
• Workflow Patterns - Common workflow designs
• Prompt Engineering - Best practices for prompts

Phase 2: Build the Skill

Step 1: Create SKILL.md

Use this structure:

---
name: { skill-name }
description: { what it does }
argument-hint: { flags and args }
---

<objective>
{Clear goal statement}
</objective>

<parameters>
{Flags and arguments}
</parameters>

<state_variables>
{Data that persists across steps}
</state_variables>

<entry_point>
Load `steps/step-00-init.md`
</entry_point>

<step_files>
{Table of all steps}
</step_files>

Step 2: Create step-00-init.md

Always start with an init step that:

• Parses flags and arguments
• Sets up state variables
• Creates output folders (if needed)
• Loads the first "real" step

Step 3: Create Each Step File

Use the step template from references/step-template.md

Step 4: Test the Workflow

Run through the workflow to ensure:

• State persists correctly
• Transitions work
• Conditional steps trigger properly
• Error handling works

Critical Patterns to Follow (BMAD-Inspired)

1. Micro-File Architecture

ALWAYS: Each step is a self-contained file with embedded rules
ALWAYS: Load one step at a time (progressive loading)
NEVER: Load all steps upfront
NEVER: Assume knowledge from future steps

Why: Saves context, disciplined execution, clear boundaries

2. Mandatory Execution Rules Section

Every step MUST start with this:

## MANDATORY EXECUTION RULES (READ FIRST):

- 🛑 NEVER {critical forbidden action}
- ✅ ALWAYS {critical required action}
- 📋 YOU ARE A {role}, not a {anti-role}
- 💬 FOCUS on {this step's scope} only
- 🚫 FORBIDDEN to {boundary violation}

3. Execution Protocols Section

## EXECUTION PROTOCOLS:

- 🎯 Show your analysis before taking any action
- 💾 Update document/frontmatter after each phase
- 📖 Complete this step fully before loading next
- 🚫 FORBIDDEN to load next step until {criteria}

4. Context Boundaries Section

## CONTEXT BOUNDARIES:

- Variables from previous steps are available in memory
- Previous context = what's in output document + frontmatter
- Don't assume knowledge from future steps
- {Resource} loaded on-demand when needed

5. Your Task Statement

One clear sentence describing the step's purpose:

## YOUR TASK:

Initialize the workflow by parsing flags and setting up state.

6. User Decisions with AskUserQuestion

CRITICAL: NEVER use plain text "[C] Continue" prompts. ALWAYS use AskUserQuestion.

**If `{auto_mode}` = true:**
→ Use recommended option automatically

**If `{auto_mode}` = false:**
Use AskUserQuestion:

```yaml
questions:
  - header: "Continue"
    question: "Ready to proceed to the next step?"
    options:
      - label: "Continue (Recommended)"
        description: "Proceed to next phase"
      - label: "Review first"
        description: "I want to review before continuing"
      - label: "Go back"
        description: "Return to previous step"
    multiSelect: false
```

### 7. Success Metrics & Failure Modes
```markdown
## SUCCESS METRICS:

✅ {Criterion 1}
✅ {Criterion 2}
✅ Frontmatter properly updated

## FAILURE MODES:

❌ {Failure 1}
❌ {Failure 2}
❌ **CRITICAL**: Not using AskUserQuestion for user input

8. Frontmatter State Tracking

Track progress in document frontmatter:

---
stepsCompleted: [1, 2, 3]
task_description: "Add auth middleware"
selected_approach: "jwt"
---

9. Critical Tags

Use <critical> tags for essential reminders:

<critical>
Remember: This step is ONLY about analysis - don't plan or implement!
</critical>

10. Next Step Routing

## NEXT STEP:

After user confirms via AskUserQuestion, load `./step-02-plan.md`

<critical>
Remember: {Important boundary reminder}
</critical>

Common Mistakes to Avoid

❌ Loading all steps at once → Use micro-file architecture, one step at a time

❌ Plain text prompts like "[C] Continue" → ALWAYS use AskUserQuestion tool for ANY user input

❌ Missing MANDATORY EXECUTION RULES section → Every step MUST start with rules using 🛑✅📋💬🚫 emojis

❌ No CONTEXT BOUNDARIES section → Always define what's in scope and what's not

❌ Vague YOUR TASK statement → Must be ONE clear sentence describing step's purpose

❌ Forgetting state handoff → Each step must document available variables from previous steps

❌ Missing SUCCESS METRICS / FAILURE MODES → Every step needs ✅ success criteria and ❌ failure modes

❌ Not handling auto_mode → Check auto_mode before ANY AskUserQuestion call

❌ No frontmatter state tracking → Track stepsCompleted array in document frontmatter

❌ Missing <critical> reminders → End each step with critical boundary reminder

❌ Hardcoding paths → Use relative paths and state variables

Structure:

• Micro-file architecture - each step self-contained
• Clear step progression with dependencies
• State variables documented and persisted in frontmatter

Each Step Has:

• MANDATORY EXECUTION RULES section with emojis
• EXECUTION PROTOCOLS section
• CONTEXT BOUNDARIES section
• YOUR TASK - one clear sentence
• Numbered EXECUTION SEQUENCE
• SUCCESS METRICS with ✅ checkmarks
• FAILURE MODES with ❌ marks
• NEXT STEP routing section
• <critical> reminder at the end

User Interaction:

• ALL user decisions use AskUserQuestion (never plain text)
• Auto mode skips AskUserQuestion calls
• Save mode outputs to files with frontmatter

State Management:

• stepsCompleted array tracked in frontmatter
• Resume detection checks existing documents
• State variables passed between steps

Quick Start

To create a new workflow skill:

1. Define your steps and their dependencies
2. Create the folder structure
3. Copy and customize SKILL.md template
4. Create step-00-init.md for initialization
5. Create each step using the step template
6. Test the workflow end-to-end

Reference files to consult:

• references/step-template.md - Step file structure
• references/ask-patterns.md - User interaction patterns
• references/state-management.md - State persistence
• references/workflow-patterns.md - Common workflows
• references/prompt-engineering.md - Prompt best practices