# Visualize

> Visualize

- Skill: `nightdreams-bat/visualize` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nightdreams-bat/visualize`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nightdreams-bat/visualize/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Nightdreams-bat (https://skillmd.com/u/nightdreams-bat)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nightdreams-bat/visualize

---


# Visualize

A picture earns its place only when it shows something words can't — shape, structure, direction, relationship, geometry. This skill produces ONE such picture, guarantees it is **correct**, and drops it into the lesson so it renders inline in the Obsidian log.

You are the **creative director**: you decide the exact idea and distill it to its fewest carrying elements.

## When to visualize (and when not to)

The `teach` system builds a **dependency graph in the learner's head** — unconditional truths at the root, derived facts hanging off them. A visual is powerful exactly when it makes that structure (or a geometry) visible. Reach for one when:

- The idea is a **structure or relationship**: dependencies, a system with parts and arrows, a flow/pipeline, a sequence of exchanges, a state machine, a tree/hierarchy, a comparison, a containment (what's inside vs outside).
- The idea is **spatial or geometric**: coordinate geometry, a number line, vectors, a function's shape, a physical arrangement.

Do NOT visualize when prose or a single equation already carries it. A decorative diagram that just restates the sentence next to it adds noise and a chance to be wrong. When in doubt, don't — a missing visual is cheaper than a false one.

## Two paths

The original system dispatched a `mermaid-maker` or `svg-maker` subagent that rendered a PNG and *looked at it* before returning. Claude Code doesn't need the rendering pipeline — Obsidian renders mermaid natively, and SVG embeds directly — but it also doesn't get that free verification. So verification becomes an explicit step you own (see below).

### Path A — mermaid (default)

For anything **nodes-and-edges**: dependency graphs, flowcharts, sequence/state/ER/class diagrams, trees, mindmaps, timelines. This fits the dependency-graph pedagogy directly, so it's the default.

Write the mermaid block **straight into the lesson file and into your chat reply**. No file, no subagent:

````markdown
```mermaid
graph TD
  P[packet] --> O[ordering]
  P --> R[retransmit on loss]
  O --> S[reliable stream]
  R --> S
```
````

Obsidian renders it natively; the terminal shows the source, which is fine.

### Path B — SVG

For **positions-and-shapes**: exact coordinates, geometry figures, number lines, vectors, plots, custom layouts that Mermaid's auto-layout can't express.

Use the `diagram-maker` skill to author it, then save the `.svg` into `D:\V A U L T\StudyVault\viz\viz-<slug>-<unix-timestamp>.svg` and embed it by filename:

```markdown
![[viz-triangle-similarity-1756137600.svg|500]]
```

Unique timestamped filenames keep Obsidian's by-filename embed resolution unambiguous.

## One idea, fewest elements

The most common failure is **cramming** — every extra label makes the picture harder to read AND harder to lay out correctly. Before drawing, prune to the fewest elements that carry the idea, and for each ask: *"if I delete this, is the idea still clear?"* If yes, delete it.

If you're about to draw more than ~7 nodes, stop and simplify. A diagram of 4 nodes that each pull weight beats one of 12 that fight for space.

Be concrete about what the picture must show, not vague about the topic:

- BAD: "a diagram about how TCP works"
- GOOD: "`graph TD`: node `packet` at top; arrows down to `ordering` and `retransmit on loss`; both arrows down into `reliable stream`. No title. Shows that reliability is built FROM packets, not alongside them."

## Verify before you embed

Nothing renders the picture back to you here, so **correctness is entirely on you**. Before the block goes in the lesson, check it deliberately:

- **Every arrow points the right way.** Is each dependency actually true — does A really derive from B, or did you draw it backwards? A wrong edge is worse than no diagram: it plants a false connection in exactly the graph you're trying to build correctly.
- **Every label is correct and unambiguous**, and short — a term or short phrase, never a sentence. Long labels wreck mermaid layout.
- **The geometry is derived, not eyeballed** (SVG path): re-do the arithmetic for coordinates, angles, and proportions rather than guessing them.
- **Mermaid syntax is valid.** Watch the usual breakers: parentheses, quotes, or `-` inside node labels — wrap the label in `["..."]`. Reserved words like `end` need quoting. LaTeX does not work inside mermaid labels.
- **Would the learner read the intended idea from this picture alone?** If not, it's not carrying its weight.

If you can't make a correct, sensible picture of the idea, say so and skip the visual — don't ship a diagram you're unsure of.

## Then let it carry the idea

Introduce the visual in a sentence, then stop — don't narrate every element back in prose. The point of the picture is that it says what prose couldn't.

---

*Ported from [amosblomqvist/learn](https://github.com/amosblomqvist/learn).*