Mohamed-El-Sharqawy/agent-tutor / .agents/skills/agent-tutor-visualize
agent-tutor-visualize
VerifiedBuild 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... | Use | Mermaid type |
|---|---|---|
| A process, flow, or decision | Flowchart | flowchart LR / TB |
| A taxonomy or breakdown | Mind map | mindmap |
| Interactions over time | Sequence diagram | sequenceDiagram |
| A chronology or evolution | Timeline | timeline |
| System structure / behavior | Class / state diagram | classDiagram, stateDiagram-v2 |
| Data relationships | ER diagram | erDiagram |
| A 2×2 comparison of options | Quadrant chart | quadrantChart |
| Proportions | Pie chart | pie |
| Side-by-side feature comparison | Table (not a diagram) | — |
| A spatial layout, annotated figure, or custom illustration | SVG | — |
If none fits, don't force it. A crisp table often beats a mediocre diagram.
2. Mermaid rules
- Validate before embedding. If a
mermaid_linttool is available, run it on the code and fix all errors. Otherwise self-check against this list (and prefer simple constructs — they render everywhere). - Keep it under ~15 nodes. Split into two diagrams if needed.
- Short labels (< 20 chars). Detail belongs in the note text, not in boxes.
- Direction:
LRfor pipelines/steps,TBfor hierarchies and mindmaps. - Quote labels containing special characters:
A["Node (with parens)"]. - Renderers support core Mermaid only — no
initdirectives, no plugins, no icon packs, no HTML inside labels (except<br/>). - 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.
- If an
svg_savetool 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. - Requirements:
xmlnsattribute,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 externalhref). SVG files are static pictures only. - Embed with a relative link or wikilink to
Learning/<Subject>/assets/<name>.svg. - 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
| Role | Color |
|---|---|
| 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 |
|---|---|---|
|  |  |  |
- 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.svgper subject — donuts first, thencompletion.svgandforecast.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"wheredash = 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, anglea = 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").
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 470k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |