workflow-skill-designer

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]

Pattern 6: Interactive Preference Collection (SKILL.md Responsibility)

Workflow preferences (auto mode, force explore, etc.) MUST be collected via AskUserQuestion in SKILL.md before dispatching to phases. Phases reference these as workflowPreferences.{key} context variables.

Anti-Pattern: Command-line flags (--yes, -e, --explore) parsed within phase files via $ARGUMENTS.includes(...).

// CORRECT: In SKILL.md (before phase dispatch)
const prefResponse = AskUserQuestion({
  questions: [
    { question: "是否跳过确认？", header: "Auto Mode", options: [
      { label: "Interactive (Recommended)", description: "交互模式" },
      { label: "Auto", description: "跳过所有确认" }
    ]}
  ]
})
workflowPreferences = { autoYes: prefResponse.autoMode === 'Auto' }

// CORRECT: In phase files (reference only)
const autoYes = workflowPreferences.autoYes

// WRONG: In phase files (flag parsing)
const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')

Pattern 7: Direct Phase Handoff

When one phase needs to invoke another phase within the same skill, read and execute the phase document directly. Do NOT use Skill() routing back through SKILL.md.

// CORRECT: Direct handoff (executionContext already set)
Read("phases/02-lite-execute.md")
// Execute with executionContext (Mode 1)

// WRONG: Skill routing (unnecessary round-trip)
Skill(skill="workflow-lite-plan", args="--in-memory")

Pattern 8: Phase File Hygiene

Phase files are internal execution documents. They MUST NOT contain:

Prohibited	Reason	Correct Location
Flag parsing ($ARGUMENTS.includes(...))	Preferences collected in SKILL.md	SKILL.md via AskUserQuestion
Invocation syntax (/skill-name "...")	Not user-facing docs	Removed or SKILL.md only
Conversion provenance (Source: Converted from...)	Implementation detail	Removed
Skill routing for inter-phase (Skill(skill="..."))	Use direct phase read	Direct Read("phases/...")

Pattern 9: Compact Recovery (Phase Persistence)

Multi-phase workflows span long conversations. Context compression (compact) will naturally summarize earlier phase documents. The strategy uses 双重保险: TodoWrite 跟踪 active phase 保护其不被压缩，sentinel 作为兜底在压缩发生时触发恢复。

Design principle: TodoWrite in_progress = active phase → protect from compact | Sentinel = re-read fallback if protection fails.

Double insurance mechanism:

Layer	Role	Mechanism
1. Active Phase Protection	预防	TodoWrite in_progress 标记当前 phase → compact 时保留该 phase 完整内容，不压缩
2. Sentinel Re-read	恢复	Phase 文件嵌入标识符 → 若仍被压缩，检测到 sentinel-only 状态时立即 re-read

When to apply: 任何通过 direct handoff (Pattern 7) 跨 phase 执行的场景，尤其是后续 phase 包含复杂执行协议（多 Step、agent 调度、CLI 编排）时。

---

Layer 1: Active Phase Protection (TodoWrite 联动)

TodoWrite 已经跟踪每个 phase 的执行状态。利用此信息驱动 compact 策略：

TodoWrite status → Compact behavior:
  ┌─ completed  → ✅ 可压缩（已完成，不再需要完整内容）
  ├─ in_progress → 🛡️ 禁止压缩（正在执行，必须保留完整协议）
  └─ pending    → ✅ 可压缩（尚未加载，无内容）

SKILL.md Execution Flow 中标注 compact 联动:

## Execution Flow

> **⚠️ COMPACT DIRECTIVE**: Context compression MUST check TodoWrite phase status.
> The phase currently marked `in_progress` is the active execution phase — preserve its FULL content.
> Only compress phases marked `completed` or `pending`.

Phase 1: Requirements Analysis    ← TodoWrite tracks status
   └─ Ref: phases/01-xxx.md
Phase 2: Execution Engine         ← TodoWrite tracks status
   └─ Ref: phases/02-xxx.md
...

TodoWrite 状态转换 时自动更新 compact 保护范围:

Phase 1: in_progress 🛡️  →  completed ✅   (compact 可压缩 Phase 1)
Phase 2: pending ✅       →  in_progress 🛡️ (compact 保护 Phase 2)

---

Layer 2: Sentinel Re-read (兜底恢复)

即使有 Layer 1 保护，compact 仍可能在极端场景（超长上下文、多轮 agent 调度）下压缩 active phase。Sentinel 确保恢复能力：

Phase 文件顶部嵌入 sentinel:

> **📌 COMPACT SENTINEL [Phase N: {phase-name}]**
> This phase contains {M} execution steps (Step N.1 — N.{M}).
> If you can read this sentinel but cannot find the full Step protocol below, context has been compressed.
> Recovery: `Read("phases/0N-xxx.md")`

Sentinel 设计特点：

• 结构化、醒目 → compact 会将其作为关键信息保留在摘要中
• 包含 step 数量 → 提供自检依据（"应该看到 M 个 Step，但只有摘要"）
• 包含 re-read 路径 → 无需查表即可恢复

---

Phase Reference Table (整合双重保险)

| Phase | Document | Purpose | Compact |
|-------|----------|---------|---------|
| 1 | phases/01-xxx.md | Planning | TodoWrite 驱动 |
| 2 | phases/02-xxx.md | Execution | TodoWrite 驱动 + 🔄 sentinel |

**Compact Rules**:
1. **TodoWrite `in_progress`** → 保留完整内容，禁止压缩
2. **TodoWrite `completed`** → 可压缩为摘要
3. **🔄 sentinel fallback** → 带此标记的 phase 包含 compact sentinel；若 compact 后仅存 sentinel 而无完整 Step 协议，**必须立即 `Read("phases/0N-xxx.md")` 恢复后再继续**

---

Checkpoint (执行步骤前双重验证)

> **⚠️ CHECKPOINT**: Before proceeding, verify:
> 1. This phase is TodoWrite `in_progress` (active phase protection)
> 2. Full protocol (Step N.X — N.{M}) is in active memory, not just sentinel
> If only sentinel remains → `Read("phases/0N-xxx.md")` now.

Handoff 注释

// Phase N is tracked by TodoWrite — active phase protection applies.
// Sentinel fallback: if compressed despite protection, re-read triggers automatically.
Read("phases/0N-xxx.md")

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 workf

---

Content truncated.