Agent Tutor Visualize

Agent Tutor — Visualize

Good visuals are not decoration — they encode structure that text can't. Use this skill whenever a lesson note would benefit from a picture.

Vault root: OBSIDIAN_VAULT env var, else learning/ in the current workspace. Subject assets go to <vault>/Learning/<Subject>/assets/.

1. Choose the right form

If none fits, don't force it. A crisp table often beats a mediocre diagram.

2. Mermaid rules

1. Validate before embedding. If a mermaid_lint tool is available, run it on the code and fix all errors. Otherwise self-check against this list (and prefer simple constructs — they render everywhere).
2. Keep it under ~15 nodes. Split into two diagrams if needed.
3. Short labels (< 20 chars). Detail belongs in the note text, not in boxes.
4. Direction: LR for pipelines/steps, TB for hierarchies and mindmaps.
5. Quote labels containing special characters: A["Node (with parens)"].
6. Renderers support core Mermaid only — no init directives, no plugins, no icon packs, no HTML inside labels (except <br/>).
7. One diagram per idea. A diagram that needs a paragraph of explanation is too complicated.

Embed directly in the note:

```mermaid
flowchart LR
    A[Input] --> B{Decision}
    B -- yes --> C[Path 1]
    B -- no --> D[Path 2]
```

3. SVG rules

Use SVG when Mermaid can't express it: spatial layouts, annotated figures, simple scenes, custom concept maps with precise positioning.

1. If an svg_save tool is available, use it — it validates the markup and writes to <vault>/Learning/<Subject>/assets/<name>.svg. Otherwise write the file yourself after checking the requirements below.
2. Requirements: xmlns attribute, viewBox, width="100%", font-size ≥ 14, inline attributes only (no CSS classes), transparent background, works on light and dark themes. Security: no <script> elements, no <foreignObject>, no references to remote URLs (no external href). SVG files are static pictures only.
3. Embed with a relative link or wikilink to Learning/<Subject>/assets/<name>.svg.
4. Keep it under ~100 elements. Simple shapes + text beat elaborate art every time.

4. Dashboard charts

The Dashboard is not a report. Text tables carry the data (links, dates); charts carry the state at a glance. All dashboard charts are SVG images — full color control, they render in Obsidian, on GitHub, and in any browser, and the agent writes them with plain file tools. Mermaid stays for lesson diagrams (section 2); the Dashboard grid is SVG only, because Mermaid code blocks cannot sit inside a table cell.

Html-mode dashboards are the exception (output_format.dashboard: html in the learner profile): their charts are the inline SVG progress rings rendered by the tutor skill's html dashboard templates (Cards overview + per-subject focus pages) — no assets/ chart files, no markdown grid, none of the recipes below. The fixed palette carries over: the html rings use the same hues. Everything else in this section applies to markdown dashboards (the default).

Fixed palette — vibrant, no variety

One cyan hue plus neutrals, chosen to work on light and dark themes. Do not introduce other colors.

The grid

Embed the charts in a markdown table so they render side by side in Obsidian and on GitHub:

| Progress | Completion | Reviews due |
|---|---|---|
| ![](<subject>/assets/progress.svg) | ![](<subject>/assets/completion.svg) | ![](<subject>/assets/forecast.svg) |

• Use standard image syntax with paths relative to Learning/Dashboard.md — portable everywhere (wikilink embeds do not render on GitHub).
• Multiple active subjects: one progress.svg per subject — donuts first, then completion.svg and forecast.svg. Start a new row after three cells.
• Update the charts whenever the tables change — a stale chart is worse than text.

Donut — <subject>/assets/progress.svg

Deterministic, ~15 elements:

• Circle r="45", stroke-width="16", fill="none".
• Track circle: full ring, neutral #3f3f46.
• Progress arc: same radius, accent #22d3ee, stroke-dasharray="<dash> 282.7" where dash = 282.7 · fraction (C = 2·π·45 ≈ 282.7). Rotate -90° around center so it starts at 12 o'clock.
• Center text: the percentage (font-size ≥ 28, #0891b2). Labels under the donut in #8b8b8b: subject, n/m topics, phase.
• Obey the SVG rules in section 3 (transparent background, no scripts, no remote references).

Completion pie — <subject>/assets/completion.svg

Two slices, viewBox="0 0 200 200", center (100,100), radius 80:

• Completed fraction f = done / total, angle a = f · 360° from 12 o'clock clockwise.
• Arc end point: x = 100 + 80·sin(a), y = 100 − 80·cos(a).
• Completed slice (accent): M 100 100 L 100 20 A 80 80 0 {1 if a > 180° else 0} 1 {x} {y} Z
• Remainder (neutral): M 100 100 L {x} {y} A 80 80 0 {1 if a < 180° else 0} 1 100 20 Z
• Center: done/total (font-size ≥ 28, #0891b2). Caption in #8b8b8b.

Review forecast — <subject>/assets/forecast.svg

Bars, one per day for the next 7 days, viewBox="0 0 340 200":

• 7 bars: width 28, spacing 42, baseline y=150. Scale: 1 note = 60 px (height = value · 60).
• Value 0 → a 3 px neutral stub at the baseline.
• Bars accent #22d3ee, baseline and stubs #3f3f46, day labels (font-size 14) and title #8b8b8b.

5. Delegating to subagents

If the agent supports delegation/subagents (e.g. pi's subagent tool with mermaid-maker / svg-maker agents, or Claude Code subagents), hand off complex or high-effort visuals so the main conversation stays focused:

• Pass the concept, the audience level, and relevant note content.
• Review and validate the returned diagram before embedding.

The diagram and illustration work can run in parallel when a lesson needs both.

6. Placement in notes

• Diagram goes right after the concept it explains — never in an "appendix" at the bottom.
• Give every visual a one-line caption explaining what to notice (*Figure: notice how X feeds back into Y*).
• Reference the figure in the text ("as shown below").