skill-system-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill System Workflow

Skill系统工作流

Dynamic orchestration engine that plans multi-step agent work as DAGs (Directed Acyclic Graphs) and always produces a renderable Mermaid diagram.

This skill is designed to bridge: (1) repeatable best-practice playbooks (recipes) and (2) one-off, context-specific plans generated on demand.

这是一款动态编排引擎，可将多步骤Agent工作规划为DAG（有向无环图），并且始终生成可渲染的Mermaid图表。

该Skill旨在连接两类内容：(1) 可重复使用的最佳实践手册（recipes），以及(2) 根据需求生成的一次性、特定上下文的规划。

Overview

概述

Input: a goal (and optional context)
Output: a
```
workflow-dag.yaml
```
document plus a Mermaid
```
flowchart TD
```
diagram
Planning strategy: try to match a pre-defined recipe first; otherwise generate a custom DAG in one pass

输入：目标（可选上下文）
输出：
```
workflow-dag.yaml
```
文档以及Mermaid
```
flowchart TD
```
图表
规划策略：首先尝试匹配预定义的recipe；否则一次性生成自定义DAG

Architecture

架构

1) Recipe matching (goal -> recipe)

1) Recipe匹配（目标 -> Recipe）

When a goal resembles a common workflow, the planner matches the goal against

recipes/*.yaml

using each recipe's

trigger_patterns

Benefits: consistent structure, fewer planning errors, repeatable waves, easier to refine over time
Output: a DAG derived from the recipe, then customized with goal-specific details (files, commands, constraints)

当目标与常见工作流相似时，规划器会使用每个recipe的

trigger_patterns

将目标与

recipes/*.yaml

进行匹配。

优势：结构一致、规划错误更少、可重复执行、便于随时间优化
输出：基于recipe生成的DAG，然后根据目标的具体细节（文件、命令、约束）进行定制

2) Dynamic planning (no recipe -> custom DAG)

2) 动态规划（无匹配Recipe -> 自定义DAG）

If no recipe matches strongly, the planner uses

prompts/plan-workflow.md

to generate a custom workflow DAG.

The planner explicitly separates independent tasks (parallelizable) from dependent tasks (sequential)
The planner assigns an
```
agent_type
```
per task based on strengths (explore vs librarian vs oracle vs build)
The planner keeps each task atomic and verifiable

如果没有找到匹配度高的Recipe，规划器会使用

prompts/plan-workflow.md

生成自定义工作流DAG。

规划器会明确区分独立任务（可并行执行）和依赖任务（需按顺序执行）
规划器会根据不同Agent的优势（探索型、图书馆型、先知型、构建型）为每个任务分配
```
agent_type
```
规划器确保每个任务具备原子性和可验证性

3) Mermaid output (every plan -> diagram)

3) Mermaid输出（所有规划 -> 图表）

Every plan includes a Mermaid diagram so the workflow is easy to review, discuss, and iterate.

One subgraph per wave
Dependencies are explicit edges
Nodes are styled by task
```
status
```

所有规划都会包含Mermaid图表，以便于工作流的审查、讨论和迭代。

每个wave对应一个子图
依赖关系通过明确的边表示
节点根据任务
```
status
```
设置样式

How To Use

使用方法

plan

plan

Analyze a goal and produce a workflow DAG plus Mermaid visualization.

Read all files in
```
recipes/
```
Match
```
goal
```
against
```
trigger_patterns
```
If a match exists: use the recipe as the base plan and tailor it to the goal
Otherwise: use
```
prompts/plan-workflow.md
```
to generate a custom DAG
Generate Mermaid from the DAG using the conventions in this document

Procedure:

scripts/plan-and-visualize.md

分析目标并生成工作流DAG及Mermaid可视化内容。

读取
```
recipes/
```
目录下的所有文件
将
```
goal
```
与
```
trigger_patterns
```
进行匹配
如果找到匹配项：以Recipe为基础规划，并根据目标进行定制
否则：使用
```
prompts/plan-workflow.md
```
生成自定义DAG
根据本文档中的规范，基于DAG生成Mermaid图表

操作步骤：

scripts/plan-and-visualize.md

visualize

visualize

Convert an existing DAG YAML into a Mermaid flowchart.

Parse
```
waves[*].tasks[*]
```
and build
```
flowchart TD
```
Use one Mermaid
```
subgraph
```
per wave
Add edges for
```
depends_on
```
Apply status styling (pending/running/done/failed)

将现有的DAG YAML转换为Mermaid流程图。

解析
```
waves[*].tasks[*]
```
并构建
```
flowchart TD
```
每个wave对应一个Mermaid
```
subgraph
```
为
```
depends_on
```
添加边
应用状态样式（pending/running/done/failed）

list-recipes

list-recipes

List available workflow recipes.

Enumerate files in
```
recipes/
```
For each file: return
```
name
```
and
```
description
```

列出可用的工作流Recipe。

枚举
```
recipes/
```
目录下的文件
对于每个文件：返回
```
name
```
和
```
description
```

File Layout

文件结构

```
prompts/plan-workflow.md
```
: one-pass dynamic DAG planning prompt
```
schema/workflow-dag.yaml
```
: workflow DAG shape specification
```
schema/recipe.yaml
```
: recipe shape specification
```
recipes/*.yaml
```
: reusable workflow templates
```
scripts/plan-and-visualize.md
```
: human procedure for plan -> DAG -> Mermaid

```
prompts/plan-workflow.md
```
：一次性动态DAG规划提示词
```
schema/workflow-dag.yaml
```
：工作流DAG结构规范
```
schema/recipe.yaml
```
：Recipe结构规范
```
recipes/*.yaml
```
：可复用的工作流模板
```
scripts/plan-and-visualize.md
```
：从规划到DAG再到Mermaid的人工操作步骤

Recipe Format Reference

Recipe格式参考

Recipes are small YAML documents that describe reusable waves and tasks.

```
name
```
: recipe identifier (must match the filename without extension)
```
trigger_patterns
```
: goal keywords/phrases that indicate the recipe is applicable
```
waves
```
: ordered execution waves
```
waves[*].parallel
```
: whether tasks in the wave can be performed simultaneously
```
waves[*].tasks[*].depends_on
```
: task ids from earlier waves that must complete first

See:

schema/recipe.yaml

Recipe是描述可复用wave和任务的小型YAML文档。

```
name
```
：Recipe标识符（必须与不带扩展名的文件名一致）
```
trigger_patterns
```
：表明该Recipe适用的目标关键词/短语
```
waves
```
：按顺序执行的wave
```
waves[*].parallel
```
：该wave中的任务是否可同时执行
```
waves[*].tasks[*].depends_on
```
：必须先完成的早期wave中的任务ID

参考：

schema/recipe.yaml

Mermaid Conventions

Mermaid规范

Diagram structure

图表结构

Graph direction:
```
flowchart TD
```
One subgraph per wave:
- ```
subgraph waveN [Wave N: <description>]
```
Each task is a node with id
```
task_id
```
Node label format:
- ```
<agent_type>\n<task name>
```

图表方向：
```
flowchart TD
```
每个wave对应一个子图：
- ```
subgraph waveN [Wave N: <描述>]
```
每个任务是一个ID为
```
task_id
```
的节点
节点标签格式：
- ```
<agent_type>\n<任务名称>
```

Node shapes

节点形状

Task nodes: rounded rectangles:
```
task_id(["<agent_type>\\n<name>"])
```
Optional start/end anchors (if used): circles:
```
start((Start))
```
,
```
end((End))
```

任务节点：圆角矩形：
```
task_id(["<agent_type>\\n<名称>"])
```
可选的开始/结束锚点（若使用）：圆形：
```
start((Start))
```
,
```
end((End))
```

Status styling

状态样式

Use Mermaid classes based on each task's

status

classDef pending fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#92400e
classDef running fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,stroke-dasharray: 5 5,color:#1e40af
classDef done fill:#d1fae5,stroke:#10b981,stroke-width:2px,color:#065f46
classDef failed fill:#fee2e2,stroke:#ef4444,stroke-width:3px,color:#991b1b

Convention:

```
pending
```
: not started
```
running
```
: in progress
```
done
```
: completed successfully
```
failed
```
: needs intervention

根据每个任务的

status

使用Mermaid类：

classDef pending fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#92400e
classDef running fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,stroke-dasharray: 5 5,color:#1e40af
classDef done fill:#d1fae5,stroke:#10b981,stroke-width:2px,color:#065f46
classDef failed fill:#fee2e2,stroke:#ef4444,stroke-width:3px,color:#991b1b

规范：

```
pending
```
：未开始
```
running
```
：进行中
```
done
```
：成功完成
```
failed
```
：需要干预

Operational Notes

操作注意事项

Keep waves small (2-6 tasks) so the diagram remains readable.
Prefer parallelism inside a wave; use
```
depends_on
```
for cross-wave ordering.
Every task should have a clear verification outcome (tests, diagnostics, file outputs, or explicit checks).

skill

{
  "schema_version": "2.0",
  "id": "skill-system-workflow",
  "version": "1.0.0",
  "capabilities": ["workflow-plan", "workflow-visualize", "workflow-list-recipes"],
  "effects": ["fs.read", "db.read"],
  "operations": {
    "plan": {
      "description": "Analyze a goal and produce an execution plan as a DAG with Mermaid visualization.",
      "input": {
        "goal": {"type": "string", "required": true, "description": "User's goal or task description"},
        "context": {"type": "string", "required": false, "description": "Additional context (files, constraints)"}
      },
      "output": {
        "description": "Workflow DAG YAML + Mermaid diagram",
        "fields": {"dag": "YAML", "mermaid": "string"}
      },
      "entrypoints": {
        "agent": "Follow scripts/plan-and-visualize.md procedure"
      }
    },
    "visualize": {
      "description": "Convert an existing DAG YAML to a Mermaid flowchart.",
      "input": {
        "dag_yaml": {"type": "string", "required": true, "description": "DAG YAML content"}
      },
      "output": {
        "description": "Mermaid flowchart string",
        "fields": {"mermaid": "string"}
      },
      "entrypoints": {
        "agent": "Apply Mermaid conventions from SKILL.md to the DAG"
      }
    },
    "list-recipes": {
      "description": "List available workflow recipes.",
      "input": {},
      "output": {
        "description": "Array of recipe names and descriptions",
        "fields": {"recipes": "array"}
      },
      "entrypoints": {
        "agent": "List files in recipes/ directory"
      }
    }
  },
  "stdout_contract": {
    "last_line_json": false,
    "note": "Agent-executed procedures; output is DAG YAML + Mermaid text."
  }
}

保持wave规模较小（2-6个任务），以便图表保持可读性。
优先在wave内使用并行执行；跨wave的顺序依赖使用
```
depends_on
```
。
每个任务都应有明确的验证结果（测试、诊断、文件输出或显式检查）。