Skill System Workflow

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.

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

Architecture

1) Recipe matching (goal -> 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)

2) Dynamic planning (no recipe -> custom 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

3) Mermaid output (every plan -> diagram)

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

How To Use

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

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)

list-recipes

List available workflow recipes.

Enumerate files in
```
recipes/
```
For each file: return
```
name
```
and
```
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

Recipe Format Reference

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

Mermaid Conventions

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

Node shapes

Task nodes: rounded rectangles:
```
task_id(["<agent_type>\\n<name>"])
```
Optional start/end anchors (if used): circles:
```
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

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

skill-system-workflow

NPX Install

Tags

SKILL.md Content