workflow-skill-designer

工作流 Skill 设计器

用于创建遵循协调器 + 阶段模式的结构化工作流 Skill 的元 Skill。生成完整的 Skill 包，其中 SKILL.md 作为协调器，phases/ 文件夹存放执行细节。

架构概览

┌─────────────────────────────────────────────────────────────────┐
│  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

目标输出结构

此元 Skill 生成的 Skill 遵循以下结构：

.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

核心设计模式

从成功的工作流 Skill 实现（workflow-plan、project-analyze 等）中提取的模式：

模式 1：协调器 + 渐进式加载

SKILL.md = 纯协调器。包含：

• 架构图（ASCII）
• 执行流程，带有 Ref: phases/0N-xxx.md 标记
• 阶段参考文档表（按需读取）
• 阶段间的数据流
• 核心规则和错误处理

阶段文件 = 完整的执行细节。包含：

• 完整的 Agent 提示词、bash 命令、代码实现
• 验证清单、错误处理
• 输入/输出规范
• 下一阶段链接

关键规则：SKILL.md 通过 Ref: 标记引用阶段文档。阶段文档仅在该阶段执行时读取，不会一次性全部读取。

模式 2：TodoWrite 关联/折叠

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

模式 3：阶段间数据流

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

每个阶段通过以下方式接收前序阶段的输出：

• 内存变量（sessionId、contextPath 等）
• 会话目录文件（.workflow/active/{sessionId}/...）
• 规划备注（累积的约束文档）

模式 4：条件阶段执行

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

模式 5：输入结构化

用户输入（自由文本）→ 第 1 阶段之前转换为结构化格式：

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

模式 6：交互式偏好收集（SKILL.md 职责）

必须在分派到各阶段之前，通过 SKILL.md 中的 AskUserQuestion 收集工作流偏好（自动模式、强制探索等）。阶段通过 workflowPreferences.{key} 上下文变量引用这些偏好。

反模式：通过 $ARGUMENTS.includes(...) 在阶段文件中解析命令行标志（--yes、-e、--explore）。

// 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')

模式 7：直接阶段交接

当某个阶段需要在同一 Skill 中调用另一阶段时，直接读取并执行该阶段文档。不要使用 Skill() 路由回 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")

模式 8：阶段文件规范

阶段文件是内部执行文档。不得包含：

禁止内容	原因	正确位置
标志解析（$ARGUMENTS.includes(...)）	偏好在 SKILL.md 中收集	通过 AskUserQuestion 在 SKILL.md 中收集
调用语法（/skill-name "..."）	非面向用户的文档	删除或仅放在 SKILL.md 中
转换来源说明（Source: Converted from...）	实现细节	删除
阶段间的 Skill 路由（Skill(skill="...")）	使用直接阶段读取	直接 Read("phases/...")

模式 9：紧凑恢复（阶段持久化）

多阶段工作流会跨越漫长的对话。上下文压缩（compact）自然会总结较早的阶段文档。该策略采用双重保险：TodoWrite 跟踪活动阶段，保护其不被压缩；sentinel 则作为兜底，在发生压缩时触发恢复。

设计原则：TodoWrite in_progress = 活动阶段 → 防止被 compact 压缩 | Sentinel = 若保护失效则重新读取。

双重保险机制：

层	作用	机制
1. 活动阶段保护	预防	TodoWrite in_progress 标记当前阶段 → compact 时保留该阶段的完整内容，不进行压缩
2. Sentinel 重读	恢复	阶段文件中嵌入标识符 → 若仍被压缩，检测到仅剩 sentinel 的状态时立即重新读取

适用场景：任何通过直接交接（模式 7）跨阶段执行的场景，尤其是后续阶段包含复杂执行协议（多步骤、Agent 调度、CLI 编排）时。

---

第 1 层：活动阶段保护（TodoWrite 联动）

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

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

SKILL.md 执行流程中标注 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)

---

第 2 层：Sentinel 重读（兜底恢复）

即使有第 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")

执行流程

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 文档（按需读取）：

Phase	文档	用途
1	phases/01-requirements-analysis.md	从多种来源分析工作流需求
2	phases/02-orchestrator-design.md	生成包含编排模式的 SKILL.md
3	phases/03-phase-design.md	生成保留完整执行细节的 Phase 文件
4	phases/04-validation.md	验证结构、引用与集成

输入来源

此 meta-skill 接受来自多种来源的工作流定义：

来源	描述	示例
现有命令	转换 .claude/commands/ 编排器 + 子命令	plan.md + session/start.md + tools/*.md
文本描述	用户以自然语言描述工作流	"创建一个 3 阶段的代码审查工作流"
需求文档	结构化需求文件	包含 phases/agents/outputs 的 requirements.md
现有 skill	重构/重新设计现有 skill	将扁平 skill 重构为多个 Phase

Frontmatter 转换规则

从命令格式转换为 skill 格式时：

命令字段	Skill 字段	转换方式
name	name	添加分组前缀：plan → workflow-plan
description	description	追加触发短语：Triggers on "xxx"
argument-hint	(已移除)	参数在 Input Processing 部分处理
examples	(已移除)	示例移至内联文档
allowed-tools	allowed-tools	展开通配符：Skill(*) → Skill，添加常用工具
group	(已移除)	内嵌到 name 前缀中

编排器内容映射

哪些内容放入 SKILL.md，哪些放入 Phase 文件：

SKILL.md（协调器）

部分	内容	来源
Frontmatter	name、description、allowed-tools	命令 frontmatter（已转换）
架构概览	Phase 流程的 ASCII 图	由执行结构推导
关键设计原则	协调规则	从命令协调器角色提取
执行流程	带 Ref: 标记的 Phase 序列 + Phase Reference 表	命令执行流程
核心规则	编排约束	命令核心规则
输入处理	结构化格式转换	命令输入处理
数据流	Phase 间数据传递	命令数据流
TodoWrite 模式	附加/折叠生命周期	命令 TodoWrite 部分
Phase 后更新	Phase 之间的规划笔记/状态更新	命令 Phase 间更新代码
错误处理	失败恢复	命令错误处理
协调器检查清单	Phase 前/后操作	命令协调器检查清单
相关命令	前置条件与后续操作	命令相关命令

阶段文件（执行细节）

内容	规则
完整的 Agent 提示词	按源命令原样保留
Bash 命令块	原样保留
代码实现	原样保留
验证清单	原样保留
错误处理细节	原样保留
输入/输出规范	如果源中没有，则添加
阶段标题	添加 # Phase N: {Name}
目标部分	添加 ## Objective，并附上项目符号列表
下一阶段链接	添加 ## Next Phase，并附上指向下一阶段的链接

关键规则：阶段文件必须忠实保留源内容。不要总结、缩写或简化。阶段文件就是执行指令——必须保留每条 Bash 命令、每个 Agent 提示词和每个验证步骤。

SKILL.md 模板

---
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}
...

## Interactive Preference Collection

Collect workflow preferences via AskUserQuestion before dispatching to phases:
{AskUserQuestion code with preference derivation → workflowPreferences}

## Auto Mode Defaults

When `workflowPreferences.autoYes === true`: {auto-mode behavior}.

## Execution Flow

{Phase sequence with Ref: markers}

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

| Phase | Document | Purpose | Compact |
|-------|----------|---------|---------|
| 1 | [phases/01-xxx.md](phases/01-xxx.md) | ... | TodoWrite 驱动 |
| N | [phases/0N-xxx.md](phases/0N-xxx.md) | ... | TodoWrite 驱动 + 🔄 sentinel |
...

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

## 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 N: {Phase Name}

> **📌 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")`
> _(Include for phases marked 🔄 in SKILL.md Phase Reference table — see Pattern 9)_

{One-sentence description of this phase's goal.}

## Objective

- {Goal 1}
- {Goal 2}

## Execution

### Step N.1: {Step Name}

{Full execution detail: commands, agent prompts, code}

### Step N.2: {Step Name}

> **⚠️ 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.
> _(Add checkpoints before critical execution steps: agent dispatch, CLI launch, review — see Pattern 9)_

{Full execution detail}

## Output

- **Variable**: `{variableName}` (e.g., `sessionId`)
- **File**: `{output file path}`
- **TodoWrite**: Mark Phase N completed, Phase N+1 in_progress

## Next Phase

Return to orchestrator, then auto-continue to [Phase N+1: xxx](0N+1-xxx.md).

设计决策框架

设计新的工作流技能时，请回答以下问题：

问题	影响	示例
有多少个阶段？	目录结构	通常为 3-7 个阶段
哪些阶段是有条件执行的？	编排器逻辑	“仅当 conflict_risk >= medium 时执行阶段 3”
各阶段之间会传递哪些数据？	数据流部分	sessionId、contextPath、configFlags
哪些阶段会使用 Agent？	阶段文件复杂度	Agent 提示词需要原样保留
TodoWrite 的粒度是什么？	TodoWrite 模式	有些阶段包含子任务，其他阶段则是原子操作
是否有规划备注模式？	阶段后更新	跨阶段累积状态的文档
如何恢复错误？	错误处理	重试一次后报告，还是回滚
是否需要收集偏好？	交互式偏好收集	在 SKILL.md 中通过 AskUserQuestion 收集，并作为 workflowPreferences 传递
阶段 N 是否会将任务交接给阶段 M？	直接阶段交接（模式 7）	直接读取阶段文档，而非通过 Skill() 路由
较长上下文之后是否仍要执行后续阶段？	紧凑恢复（模式 9）	添加标记和检查点，并在阶段参考表中标记 🔄