vibbs/agent-skills

Architecture Explainer

Produces one self-contained HTML file per explainer: runtime, topology, prose, typeface and styling inlined, no network calls at runtime. Host it anywhere, open it offline, <iframe> it into a page, or attach it to an email.

The model

One topology, many projections. The system is authored once, in full depth. Everything else is a selector over that single graph — never a second diagram.

TOPOLOGY   nodes + edges + metadata        ← the only thing you author
──────────────────────────────────────
PERSONA    resolution policy — vocabulary, collapse depth, which facts surface
LENS       concern overlay — which edges exist, which fact each node advertises
ERA        past / present / planned — presence and status styling
BEATS      narrative — camera, focus, prose, in sequence

Two rules the runtime enforces and you must not fight:

1. Colour belongs to the lens. Node kind is carried by shape — folded corner for a source, spine for a store, figure for a human step, chamfered for a gate. Never reintroduce a colour-per-kind scheme; it turns the diagram into a rainbow and makes lens switching meaningless.
2. A diagram without a guided tour is not finished. The linter fails the build on zero beats. This is the rule that keeps these self-explanatory rather than pretty.

Workflow — follow in order

1. Interview. Do not invent the system.

The single biggest failure mode is generating a plausible-looking architecture the user never described. Ask before writing anything. Use your agent's structured question tool if it has one.

Cover:

• The tiers. What are the 5–8 top-level stages or groups? These become the L1 boxes.
• Components per tier. Only what's worth showing. "Postgres" is a box; its tables are not.
• The lifecycle. Walk one representative request or job end to end. This produces the edges.
• Who reads it. Exec / architect / engineer is the usual set, but ask — it might be "client / our team", or "student / practitioner".
• Which concerns matter. Data flow plus 2–4 of: cost, latency, trust & governance, failure modes, ownership, security. Each lens needs its own edges or facts.
• Whether there's a history. v0 → today → planned is the highest-value axis for client work and roadmaps. Skip it if the system has no meaningful past.
• The argument. What should a reader believe after reading it? This becomes the beats. If the user has no argument, the explainer has no spine — push for one.

2. Pick the primary axis

Depth is rarely the interesting one. Ask what the diagram is for:

Purpose	Primary axis
Teaching how it works	Time — beats walking one request through
Client / stakeholder pitch	Era — what exists, what's proposed
Design review, risk	Lens — failure modes, trust boundaries
Onboarding, reference	Depth — tiers then components

3. Write the spec

Read references/spec-format.md in full before writing one. It is the complete node / edge / beat reference with every optional field.

Copy assets/runtime/specs/llm-eval.js as the worked example — it exercises every feature and is a good shape to imitate. Write the new spec to specs/<name>.js, then point src/spec.js at it (one line — the entry point and the linter both read it through there).

4. Build

Copy assets/runtime to a working directory first and build there. Do not run npm install inside the installed skill folder — it is often a shared or symlinked install location.

cp -R <skill-dir>/assets/runtime ./explainer
cd explainer
npm install            # needs network; ~20s
npm run build          # lints the spec first, then emits dist/index.html

The lint output tells you the projection count. If it fails, fix the spec — never weaken the linter. Every rule it enforces exists because a real diagram shipped without it and was worse. See references/spec-format.md for what each rule means.

5. Verify visually — mandatory, both form factors

This is the most-skipped step and the most consequential. The layout maths is non-trivial and failures are silent: a clipped label, an edge routed through five boxes, a camera that frames empty space. Do not declare done without looking.

node scripts/shots.mjs        # desktop matrix → shots/

Then screenshot at phone size yourself (390×844) and open and inspect the images. Check:

• Every persona × era combination renders without overlap or clipping.
• Each lens actually changes the picture — if two lenses look identical, their edge sets are wrong.
• Beat framing. Step through beats; each should frame its focus with visible context, not empty space and not the whole system.
• Labels. Nothing clipped, nothing sitting on top of a box.
• Phone. Reflowed to one column, readable at 100%, controls not overflowing.
• Console. Zero errors, including inside a sandboxed iframe.

If something looks wrong, read references/troubleshooting.md before changing layout code.

6. Deliver

Give the user the built dist/index.html. Tell them the file is self-contained and can be hosted, embedded, or opened offline.

Claude Code / Claude apps only. Send the file with SendUserFile. If it's something the user will revisit — most explainers are — also persist it with create_artifact.

Non-negotiables

• Every node has a why — one sentence on why the box exists at all, not what it is.
• Anything an executive can see has exec-level detail in exec vocabulary.
• At least 6 beats, each with real prose. Thin beats produce a slideshow, not an argument.
• ≤34 leaf nodes. Past that, split into multiple explainers rather than cramming.
• One theme per build. Readers get a light/dark toggle, nothing more.

Adapting

• Different visual direction — src/themes.js holds five (house, swiss, editorial, draft, shadcn). Change THEME_ID in src/App.jsx. If you add a typeface you must set metrics.charFactor correctly or every label clips; see references/troubleshooting.md.
• More personas / lenses / eras — pure spec data, no code changes.
• Generating from source — a script that walks a repo and emits the DIAGRAM tree is a reasonable extension, but the why, detail and beats still have to come from a human.

Scope

This builds explanatory figures, not live dashboards, not free-form drawing tools, and not infrastructure inventories. If the user wants an editable diagram they'll keep dragging around, they want drawio instead. If they want one number on a page, they want a chart.