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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.4 KB |
SKILL.md
View on GitHub---
name: agent-tutor-visualize
version: 2
description: 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.
license: MIT
---
# 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
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
| 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:
```markdown
| 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.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").
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: 472k | Updated | Claude CodeCodex | Unverified | 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 |