Drawio Kernel Agent

Use the agent's built-in model for reasoning. Do not call OpenAI, Anthropic, Gemini, or any hosted model API.

Files in this Skill

• scripts/validate_ir.mjs: Validate IR JSON and print validation result.
• scripts/compile_ir.mjs: Compile valid IR JSON to .drawio XML.
• scripts/_load_kernel.mjs: Resolve kernel module path with fallback logic.
• references/ir-template.json: Minimal IR starting template.
• vendor/drawio-kernel/kernel.mjs: Bundled deterministic compiler.
• vendor/drawio-kernel/schema.json: IR JSON schema.

Kernel resolution priority in scripts:

1. DRAWIO_KERNEL_FILE
2. DRAWIO_KERNEL_ROOT/kernel.mjs
3. Bundled vendor/drawio-kernel/kernel.mjs
4. <cwd>/tools/drawio-kernel/kernel.mjs
5. Legacy relative ../../../tools/drawio-kernel/kernel.mjs

Execution Workflow

Phase 1 — Structure (topology only)

1. Read the user request and infer diagram intent (entities, relationships, flow direction).
2. Produce a topology-only IR JSON: nodes with id, type, label and edges with source, target, label. Do not assign coordinates yet.

Phase 2 — Layout (assign coordinates)

3. Review the topology and assign x, y, width, height to each node. Follow layout heuristics:
   • Align to grid (multiples of 10).
   • Top-down flow: increment y by height + gap per level.
   • Left-right branching: offset x for parallel paths.
   • Containers: ensure children fit inside parent bounds with padding.
   • Edge-aware placement: position nodes to minimize edge crossings. Place heavily connected nodes closer together. Avoid layouts that force edges to cross through unrelated nodes.
4. Validate the complete IR:

node skills/drawio/scripts/validate_ir.mjs --in /tmp/diagram.ir.json

5. Compile IR to draw.io XML:

node skills/drawio/scripts/compile_ir.mjs --in /tmp/diagram.ir.json --out /tmp/diagram.drawio

Phase 3 — Visual Review & Refinement

6. Export to PNG:

/Applications/draw.io.app/Contents/MacOS/draw.io --export --format png --scale 2 --output /tmp/diagram.png /tmp/diagram.drawio

7. Read the exported PNG with the Read tool. Self-review with edge routing as top priority:

   Edge issues (check first):

   • Crossing: edges crossing each other unnecessarily — reorder node positions or add waypoints to reroute
   • Overlap with nodes: edges passing through unrelated nodes — add waypoints to route around them
   • Ambiguous routing: unclear which node an edge connects to — use orthogonal routing ("orthogonal": true) and explicit waypoints
   • Label collision: edge labels overlapping edges or nodes

   Node issues:

   • Overlap: nodes or labels covering each other
   • Clipping: text truncated inside node bounds
   • Alignment: uneven spacing or misaligned parallel branches
   • Readability: font too small, labels unclear

8. If issues found: fix the IR (adjust coordinates, sizes, or styles), re-validate, re-compile, re-export, and re-review. Maximum 2 refinement rounds.

9. Return the .drawio path and .png preview path. Use inline XML only when user explicitly asks.

IR Requirements

• Keep node IDs unique and stable.
• Ensure each edge references existing source and target node IDs.
• Use coordinates aligned to multiples of 10 whenever possible.
• Prefer supported node types:
  • process
  • start_end
  • decision
  • data_store
  • text
  • container

Reasoning Boundaries

• Phase 1 (Structure): focus on what nodes/edges exist and how they connect. Do not think about positions.
• Phase 2 (Layout): focus on spatial arrangement. Do not change topology.
• Phase 3 (Review): focus on visual quality. Only adjust coordinates, sizes, and styles — do not add/remove nodes.
• Let deterministic code handle validation and XML assembly.
• If compile fails, repair IR once and retry automatically.
• If user intent is ambiguous, choose a conservative flowchart and state assumptions.

Prohibited Actions

• Do not send prompts to external model providers.
• Do not expose or depend on runtime /api/generate endpoints.
• Do not claim API-based generation.