workflow-skill-designer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Workflow Skill Designer

Workflow Skill 设计器

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.

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

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

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

本元技能生成的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

Core Design Patterns

核心设计模式

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

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

Pattern 1: Orchestrator + Progressive Loading

模式1：Orchestrator + 渐进式加载

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.

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

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

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

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

关键规则：SKILL.md通过

Ref:

标记引用阶段文档。阶段文档仅在该阶段执行时才会读取，而非一次性全部加载。

Pattern 2: TodoWrite Attachment/Collapse

模式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

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

模式3：阶段间数据流

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)

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

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

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

Pattern 4: Conditional Phase Execution

模式4：条件式阶段执行

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

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

Pattern 5: Input Structuring

模式5：输入结构化

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

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

用户输入（自由文本）→ 转换为结构化格式后进入阶段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

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

阶段参考文档（按需读取）：

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

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

本元技能支持从多源接收工作流定义：

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

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

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

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

Orchestrator Content Mapping

协调器内容映射

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

SKILL.md与阶段文件的内容划分：

SKILL.md (Coordinator)

SKILL.md（协调器）

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

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

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.

内容	规则
完整Agent提示词	完全保留源命令中的内容
Bash命令块	完全保留
代码实现	完全保留
验证清单	完全保留
错误处理细节	完全保留
输入/输出规范	若源中不存在则添加
阶段标题	添加 `# Phase N: {Name}`
目标章节	添加 `## Objective` 及项目符号
下一阶段链接	添加 `## Next Phase` 及下一阶段链接

关键规则：阶段文件必须与源内容完全一致。不得总结、缩写或简化。阶段文件就是执行指令——每一条bash命令、每一个Agent提示词、每一个验证步骤都必须完整保留。

SKILL.md Template

SKILL.md模板

markdown

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

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

{Principle}: {Description} ...

{Principle}: {Description} ...

Auto Mode

When

--yes

-y

: {auto-mode behavior}.

When

--yes

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

{Phase sequence with Ref: markers}

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

Phase	Document	Purpose
1	phases/01-xxx.md	...
...

Core Rules

{Rule} ...

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

undefined

{Prerequisites and follow-ups}

undefined

Phase File Template

阶段文件模板

markdown

undefined

markdown

undefined

Phase N: {Phase Name}

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

Objective

{Goal 1}
{Goal 2}

{Goal 1}
{Goal 2}

Execution

Step N.1: {Step Name}

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

Step N.2: {Step Name}

{Full execution detail}

Output

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

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.

undefined

Return to orchestrator, then auto-continue to Phase N+1: xxx.

undefined

Design Decision Framework

设计决策框架

When designing a new workflow skill, answer these questions:

Question	Impact	Example
How many phases?	Directory structure	3-7 phases typical
Which phases are conditional?	Orchestrator logic	"Phase 3 only if conflict_risk >= medium"
What data flows between phases?	Data Flow section	sessionId, contextPath, configFlags
Which phases use agents?	Phase file complexity	Agent prompts need verbatim preservation
What's the TodoWrite granularity?	TodoWrite Pattern	Some phases have sub-tasks, others are atomic
Is there a planning notes pattern?	Post-Phase Updates	Accumulated state document across phases
What's the error recovery?	Error Handling	Retry once then report, vs rollback
Does it need auto mode?	Auto Mode section	Skip confirmations with --yes flag

设计新工作流Skill时，需回答以下问题：

问题	影响	示例
需要多少个阶段？	目录结构	典型为3-7个阶段
哪些阶段是条件式执行的？	协调器逻辑	"当conflict_risk >= medium时才执行阶段3"
阶段间传递哪些数据？	数据流章节	sessionId、contextPath、configFlags
哪些阶段使用Agent？	阶段文件复杂度	Agent提示词需要完整保留
TodoWrite的粒度是多少？	TodoWrite模式	部分阶段包含子任务，其他为原子任务
是否有规划笔记模式？	阶段后更新	跨阶段累积状态文档
错误恢复机制是什么？	错误处理	重试一次后报告，还是回滚
是否需要自动模式？	自动模式章节	使用--yes标志跳过确认步骤