Skip to content

Mohamed-El-Sharqawy/agent-tutor / .agents/skills/agent-tutor-visualize

agent-tutor-visualize

Verified

Build diagrams and visual explanations for learning notes - Mermaid diagram selection and syntax rules plus SVG illustration guidelines for lesson notes in a markdown vault. Use when a concept needs a picture such as flows, hierarchies, timelines, comparisons, or spatial layouts, and when creating or embedding diagrams in lesson notes.

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

The concept is...UseMermaid type
A process, flow, or decisionFlowchartflowchart LR / TB
A taxonomy or breakdownMind mapmindmap
Interactions over timeSequence diagramsequenceDiagram
A chronology or evolutionTimelinetimeline
System structure / behaviorClass / state diagramclassDiagram, stateDiagram-v2
Data relationshipsER diagramerDiagram
A 2×2 comparison of optionsQuadrant chartquadrantChart
ProportionsPie chartpie
Side-by-side feature comparisonTable (not a diagram)—
A spatial layout, annotated figure, or custom illustrationSVG—

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

RoleColor
Accent — progress arcs, pie slices, bars#22d3ee
Accent-deep — big numbers#0891b2
Neutral — tracks, remainder slices, gridlines, zero-stubs#3f3f46
Muted — labels and captions#8b8b8b

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").
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall