Drawio Databricks Skill for Claude

Draw.io Databricks

Produce correct Databricks lakehouse architecture diagrams in draw.io. This skill

is a thin frontend; the deterministic engine, validator, and rules live in the

drawio-ai-kit package, reached via the drawio-ai CLI.

0. Preflight — the CLI must be installed

command -v drawio-ai >/dev/null 2>&1 || echo "Install the Kit first:  npm i -g github:sparklabx/drawio-ai-kit"

If drawio-ai is not on PATH, stop and tell the user to run

npm i -g github:sparklabx/drawio-ai-kit. Never run npm i -g yourself — nothing mutates the

user's global environment without their say-so.

1. Delegate the build (preferred when your harness supports it)

If your harness can spawn autonomous subagents that run shell commands AND read

images (e.g. Claude Code's Task tool, a general-purpose agent), run the whole

build loop in a subagent — the rules, icon searches, and every render/fix

iteration then cost this conversation nothing. If it can't (or the subagent

can't read images), skip to Inline path below — same loop, same rules.

Before spawning, resolve what the subagent cannot ask about: diagram scope,

output directory (absolute path under the user's project), filename. Run the

preflight above yourself. For a multi-diagram request, spawn one subagent per

diagram in parallel with distinct filenames.

Model routing — if your harness lets you choose the subagent's model, route by

task weight: a fast/cheap tier (Claude Haiku-class — must support vision) when

the request matches a template from the rules' Templates table (reproduction is

mechanical; the validator's advice strings teach every fix), your **default strong

model** for free-hand or novel architectures. If a cheap subagent returns VALIDATE

not ok or ITERATIONS > 3, respawn ONCE on the strong model before taking over

inline. Multi-diagram requests: route each diagram independently.

Subagent prompt (fill every <...>):

Build a Databricks lakehouse architecture .drawio diagram with the drawio-ai CLI.
Request: <user's request + clarifications, verbatim>
Output: <ABS_PROJECT_DIR>/<NAME>.drawio — never write inside the Kit, never into cwd.
Follow exactly:
1. Set ROOT="$(drawio-ai root)". Read $ROOT/docs/api-cheatsheet.md — the full layout-engine
   API in one file; never read library source.
2. Run `drawio-ai workflow` and `drawio-ai principles --mode databricks` — the source of
   truth. (Fallback if a command is blocked: read $ROOT/rules/*.md directly.)
3. Look up every icon with ONE batched `drawio-ai search "a, b, c"`; never recolor icons.
4. Scaffold, don't write: `drawio-ai scaffold --list`, pick the closest template, then
   `drawio-ai scaffold <name>.mjs -o <dir>/build.mjs` — the script arrives runnable and
   self-checking. Edit only the deltas; Write a new script only if no template is close
   AND you'd change more than half of it.
5. Each `node build.mjs` run prints validate JSON AND the render's machine-readable
   `issues` list. Fix from THAT checklist — all issues in one Edit round — then re-run.
   Loop until issues is empty.
6. Only when issues is empty: Read the PNG once as final visual confirmation. Target <= 2
   PNG reads total. Then render once WITHOUT --check for the final deliverable PNG.
Do NOT invoke any drawio skill — this prompt already contains the full procedure.
Do not ask questions — make the standard choice and record it under ASSUMPTIONS.
Return EXACTLY this block, nothing else:
DRAWIO: <absolute path to .drawio>
PNG: <absolute path to .png>
VALIDATE: <verbatim final validate JSON>
ICONS: <comma-separated icon names used>
ITERATIONS: <number of render/fix cycles>
SUMMARY: <one sentence describing the diagram>
ASSUMPTIONS: <choices made without asking, or "none">

Relay DRAWIO, PNG and SUMMARY to the user verbatim; do NOT re-read the

.drawio or PNG in this conversation — the subagent already ran the vision

self-check. If VALIDATE is not ok, take over via the Inline path (the build

.mjs and .drawio are on disk at the returned paths).

Inline path (no subagent support)

1. Shared Workflow

drawio-ai workflow

Prints the build → validate → render → write-to-project-path loop every diagram

follows. Read it; it is the source of truth for the process.

2. Domain rules

drawio-ai principles --mode databricks

Returns the Databricks rules + shared principles + catalog categories.

3. Build with the engine, then validate + render

Resolve the Kit's install dir, then import the engine by absolute path (the

Shared Workflow shows the exact pattern):

ROOT="$(drawio-ai root)"     # absolute path to the installed Kit

Build with the declarative layout engine (NO hand-written coordinates), then:

drawio-ai validate <file> → drawio-ai render <file> -o <file>.png (Read

the PNG for the vision self-check) → write the .drawio to an **absolute path

under the user's project** (never the Kit, never cwd).

Domain notes

Logical layers: medallion architecture `Bronze (raw) → Silver (cleaned) → Gold

(business-ready)`. Deployment split: the Databricks control plane is managed

by Databricks (no diagram representation needed); the data plane (compute)

lives in the customer's cloud account via PrivateLink or VNet injection — show

it nested inside the customer's VPC/cloud boundary. Unity Catalog governs

metadata across workspaces.

Self-check (before delivering)

• [ ] Built with the layout engine — no hand-written coordinates.
• [ ] drawio-ai validate → ok, no warnings, no advice.
• [ ] Every icon came from drawio-ai search (category colors intact).
• [ ] drawio-ai render vision self-check passed.
• [ ] Output written under the user's project, not the Kit.