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: ]

Each task is a node with id

task_id

Node label format:

\n

Node shapes

Task nodes: rounded rectangles:

task_id(["\n"])

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