asgeirf/flow-graph

Flow Graph Skill

Generate graph visualizations rendered as GIF and WebM video files with animated traffic flowing along edges. You describe a process or graph in natural language, then this skill produces a video of the diagram.

Workflow

1. Understand the Request

Parse the user's description to identify:

• Nodes — entities, states, steps, or concepts
• Edges — relationships, transitions, data flows
• Layout — flowchart (top-down), pipeline (left-right), state machine (radial), etc.
• Mode — static with traffic (default) or step-by-step build-up (only if user explicitly asks)

2. Generate Graph JSON

Create a graph-data.json file. Default to static mode — define all nodes and edges upfront. The engine renders the complete graph immediately with animated traffic flowing along edges.

Static mode (default — use this unless asked for build-up animation):

{
  "settings": {
    "width": 1280, "height": 720,
    "background": "#1a1a2e",
    "duration": 5000,
    "traffic": true
  },
  "nodes": [
    { "id": "a", "label": "Start", "position": [400, 50] },
    { "id": "b", "label": "Process", "position": [400, 200] },
    { "id": "c", "label": "End", "position": [400, 350] }
  ],
  "edges": [
    { "id": "e1", "source": "a", "target": "b" },
    { "id": "e2", "source": "b", "target": "c" }
  ]
}

Step mode (advanced — only when user asks for build-up sequences):

{
  "settings": {
    "width": 1280, "height": 720,
    "background": "#1a1a2e",
    "animationDuration": 500,
    "fitViewOnComplete": true
  },
  "steps": [
    { "type": "addNode", "node": { "id": "1", "label": "Start", "position": [200, 100] }, "delay": 600 },
    { "type": "addEdge", "edge": { "id": "e1-2", "source": "1", "target": "2", "animated": true }, "delay": 400 },
    { "type": "highlight", "ids": ["1"], "color": "#e94560", "delay": 800 },
    { "type": "fitView", "padding": 0.2, "delay": 500 },
    { "type": "wait", "delay": 1500 }
  ]
}

Step types: addNode, addEdge, highlight, moveNode, removeNode, removeEdge, updateStyle, fitView, zoom, pan, wait

See references/graph-schema.md for full details on both modes.

3. Write the JSON File

Write the graph JSON to a temporary file, e.g. /tmp/my-graph.json.

4. Setup (first run only)

Install the skill's dependencies if not yet done:

cd <skill-dir> && npm install --prefer-offline --no-audit --no-fund
cd <skill-dir>/assets/flow-template && npm install --prefer-offline --no-audit --no-fund
npx playwright install chromium

Where <skill-dir> is the directory containing this SKILL.md file.

5. Record the Animation

Run the recording script:

node <skill-dir>/scripts/record.mjs /tmp/my-graph.json ./output --format both

This will produce output.webm and output.gif in the current directory.

Layout Patterns

Top-down flowchart — Increment Y by ~150 per row, center X:

{ "id": "a", "label": "Step 1", "position": [400, 50] }
{ "id": "b", "label": "Step 2", "position": [400, 200] }

Left-to-right pipeline — Increment X by ~200, same Y:

{ "id": "src", "label": "Source", "position": [50, 150] }
{ "id": "dst", "label": "Dest",   "position": [250, 150] }

Branching / decision — Fork at the decision node with different X offsets:

{ "id": "decide", "position": [400, 300] }
{ "id": "yes",    "position": [250, 450] }
{ "id": "no",     "position": [550, 450] }

Recording Options

node record.mjs <graph-data.json> <output-path> [options]

Options:
  --format gif|webm|both   Output format (default: both)
  --width  <number>        Viewport width override
  --height <number>        Viewport height override

The script handles everything: copies the template to a temp directory, injects the graph data, starts a Vite dev server, records with Playwright, converts via ffmpeg, and cleans up.

Design Tips

Static mode (default)

• Set duration to 4000-6000ms for a good looping clip
• Traffic animation flows automatically on all edges — no per-edge config needed
• Set "traffic": false in settings if you want a still diagram
• Style key nodes with colored backgrounds or borders to show roles (source, sink, decision)
• Use edge label to annotate relationships

Step mode (build-up animation)

• Use delay: 400-800 for node/edge additions (fast enough to be engaging, slow enough to follow)
• Add a highlight step after key nodes appear to draw attention
• End with fitView + wait to show the complete graph for 1-2 seconds
• Use animated: true on edges to show data flow direction
• Style decision nodes with borderRadius: "50%" for diamond/circle shapes
• Keep total animation under 15 seconds for best GIF file size

Prerequisites

• Node.js 20+
• ffmpeg (for GIF conversion) — brew install ffmpeg
• Playwright browsers — npx playwright install chromium