Flow Graph Skill

Generate animated graph visualizations rendered as GIF and WebM video files. You describe a process or graph in natural language, then this skill produces a step-by-step animated build-up 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.
• Emphasis — which nodes/edges to highlight or animate specially

2. Generate Graph JSON

Create a graph-data.json file following the animation step schema. Each step adds a node, edge, highlight, or camera movement — building up the graph incrementally for visual storytelling.

Quick Reference (see references/graph-schema.md for full details):

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

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.

Common 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

• 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