# Pedagogical Figure Designer

> Detects which pedagogical figures are needed in a course, TD, TP, exam, or project, then specifies and generates them in SVG, TikZ, PlantUML, or ASCII. Use when an instructor or orchestrator needs rigorous, reusable, source-based figures for computing, systems, networks, algorithms, AI, cybersecurity, or professional reskilling materials.

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

---


# Pedagogical Figure Designer

## Goal
Turn abstract technical content into precise, reusable pedagogical figures that improve understanding without adding conceptual noise.

## Inputs
Read these first when available:
- `mission.json`
- the course, TD, TP, exam, or project draft
- `shared/figure-policy/figure-policy.md`
- the format-specific guidance in `references/`

## Main responsibilities
1. Detect which concepts actually require a figure.
2. Reject decorative figures with no pedagogical value.
3. Write a compact figure specification before drawing.
4. Choose the most suitable source format among SVG, TikZ, PlantUML, and ASCII.
5. Generate source files that are readable, editable, and reusable.
6. Provide a short pedagogical justification for each figure.
7. Keep the level of abstraction aligned with the audience: L1, L2, L3, M1, M2, or professional reskilling.

## Output contract
For each figure, produce:
- a figure identifier;
- a short title;
- the pedagogical purpose;
- the target level;
- the chosen format;
- the source file;
- a short caption;
- a short note explaining why this figure is useful.

When relevant, also produce:
- a simplified variant;
- a detailed variant;
- an exam-safe black-and-white variant;
- an ASCII fallback for text-only environments.

## When to use each format
### Use PlantUML for
- UML class diagrams;
- sequence diagrams;
- state machines;
- activity diagrams;
- component and deployment views;
- lightweight software architecture views;
- protocol interactions.

### Use TikZ for
- mathematically precise diagrams;
- trees, graphs, grids, and geometric or algorithmic figures in LaTeX workflows;
- figures that must integrate cleanly into lecture notes, exams, or handouts compiled with LaTeX.

### Use SVG for
- architecture diagrams;
- pipelines;
- process graphs;
- memory layouts;
- block diagrams;
- reusable figures intended for slides, web pages, or later editing in a vector editor.

### Use ASCII for
- terminal-only materials;
- code comments or plain-text handouts;
- quick but faithful representations of trees, pipes, process hierarchies, directory layouts, and simple flows.

## Mandatory figure specification step
Before generating code, write a compact specification containing:
- `figure_id`
- `title`
- `context_document`
- `target_level`
- `pedagogical_objective`
- `concepts_covered`
- `format_chosen`
- `why_this_format`
- `granularity`
- `must_show`
- `must_not_show`
- `caption`
- `accessibility_notes`

If the specification is weak or ambiguous, stop and refine it before generating the figure source.

## Design rules
- Prefer one pedagogical idea per figure.
- Avoid overloaded diagrams.
- Define labels and symbols explicitly.
- Avoid introducing concepts not already present in the material.
- Prefer monochrome-safe designs unless color carries essential meaning.
- Use consistent naming with the surrounding course material.
- Keep figures editable from source.
- Never produce bitmap-only figures when a source language is possible.

## Quality checks
For every generated figure, verify:
- scientific correctness;
- consistency with the surrounding text;
- appropriate abstraction level;
- readability at normal print or slide scale;
- no hidden ambiguity in labels or arrows;
- no unnecessary decorative elements.

## Typical use cases
- add a process/thread memory model figure to an OS lecture;
- generate a PlantUML sequence diagram for a client-server TP;
- produce a TikZ graph traversal figure for an algorithms exam;
- generate an ASCII pipeline diagram for a Unix shell exercise;
- create an SVG architecture view for a fil rouge project.

## Deliverables
When asked to support an existing pedagogical artifact, generate:
1. `figures/figure-index.md` with the list of recommended or produced figures;
2. `figures/specs/` containing one specification file per figure;
3. `figures/src/` containing source files in `.svg`, `.tex`, `.puml`, or `.txt`;
4. optional `figures/captions.md` for reusable captions.