|
| 1 | +<p> |
| 2 | + <img src="banner.png" alt="visual-explainer" width="1100"> |
| 3 | +</p> |
| 4 | + |
| 5 | +# visual-explainer |
| 6 | + |
| 7 | +**An agent skill + prompt templates that replace ASCII diagrams with beautiful, self-contained HTML pages — architecture overviews, flowcharts, diff reviews, data tables, and more.** |
| 8 | + |
| 9 | +[](LICENSE) |
| 10 | + |
| 11 | +``` |
| 12 | +> draw a diagram of our authentication flow |
| 13 | +
|
| 14 | +> visualize the database schema |
| 15 | +
|
| 16 | +> /diff-review main |
| 17 | +``` |
| 18 | + |
| 19 | +The agent builds a styled HTML page — CSS Grid layouts, Mermaid flowcharts, Google Fonts, dark/light themes, staggered animations — and opens it in your browser. One file, no build step, no dependencies. |
| 20 | + |
| 21 | +## Why |
| 22 | + |
| 23 | +Every coding agent defaults to ASCII art when you ask for a diagram. Box-drawing characters, monospace alignment hacks, text arrows. It works for trivial cases, but anything beyond a 3-box flowchart turns into an unreadable mess that nobody would put in a presentation or share with a team. |
| 24 | + |
| 25 | +It gets worse with tables. Ask the agent to compare 15 requirements against a plan and you get a wall of pipes and dashes that wraps and breaks in the terminal. The data is there but it's painful to read. |
| 26 | + |
| 27 | +This skill replaces all of that with real HTML pages that look like someone designed them — because the agent follows a design-aware workflow with reference templates, CSS patterns, and font pairings before generating each diagram. |
| 28 | + |
| 29 | +## Install |
| 30 | + |
| 31 | +The skill follows the [Agent Skills specification](https://agentskills.io/specification). Clone it into your agent's skills directory: |
| 32 | + |
| 33 | +### Pi |
| 34 | + |
| 35 | +```bash |
| 36 | +git clone https://github.com/nicobailon/visual-explainer.git ~/.pi/agent/skills/visual-explainer |
| 37 | +``` |
| 38 | + |
| 39 | +Restart Pi. The skill auto-discovers from the skills directory. |
| 40 | + |
| 41 | +To get the slash commands (`/diff-review`, `/plan-review`, etc.), copy the prompt templates and install the [pi-prompt-template-model](https://github.com/nicobailon/pi-prompt-template-model) extension for skill auto-injection: |
| 42 | + |
| 43 | +```bash |
| 44 | +cp ~/.pi/agent/skills/visual-explainer/prompts/*.md ~/.pi/agent/prompts/ |
| 45 | +pi install npm:pi-prompt-template-model |
| 46 | +``` |
| 47 | + |
| 48 | +Without the extension the prompts still work as normal templates, but the agent won't get the skill auto-injected — it would need to discover and load it on its own. |
| 49 | + |
| 50 | +### Claude Code |
| 51 | + |
| 52 | +```bash |
| 53 | +git clone https://github.com/nicobailon/visual-explainer.git ~/.claude/skills/visual-explainer |
| 54 | +``` |
| 55 | + |
| 56 | +### Other agents |
| 57 | + |
| 58 | +Any agent that supports the Agent Skills spec can load the skill by pointing at the directory containing `SKILL.md`. If your agent doesn't support auto-discovery, paste the contents of `SKILL.md` into your system prompt directly. |
| 59 | + |
| 60 | +### Manual (no git) |
| 61 | + |
| 62 | +```bash |
| 63 | +mkdir -p ~/.agent/skills/visual-explainer |
| 64 | +curl -L https://github.com/nicobailon/visual-explainer/archive/refs/heads/main.tar.gz | \ |
| 65 | + tar -xz --strip-components=1 -C ~/.agent/skills/visual-explainer |
| 66 | +``` |
| 67 | + |
| 68 | +### Optional: AI-generated images |
| 69 | + |
| 70 | +If you have [surf-cli](https://github.com/nicobailon/surf-cli) installed with its Chrome extension, the skill can generate illustrations via Gemini Nano Banana Pro and embed them in diagrams — hero banners, conceptual illustrations, educational diagrams. The agent checks for surf availability automatically and skips image generation gracefully if it's not installed. Everything else works without it. |
| 71 | + |
| 72 | +## Usage |
| 73 | + |
| 74 | +**Ask naturally.** The agent sees the skill description and loads it when you mention diagrams, architecture, flowcharts, schemas, or visualizations: |
| 75 | + |
| 76 | +``` |
| 77 | +> draw a diagram of our authentication flow |
| 78 | +> visualize the database schema |
| 79 | +> create an architecture overview of the notification system |
| 80 | +``` |
| 81 | + |
| 82 | +**Proactive table rendering.** When the agent is about to render a complex ASCII table (4+ rows or 3+ columns), it generates a styled HTML table instead and opens it in the browser. Comparisons, audits, feature matrices, status reports — anything tabular gets the HTML treatment automatically. |
| 83 | + |
| 84 | +**Force-load** if the agent doesn't pick it up on its own: |
| 85 | + |
| 86 | +``` |
| 87 | +> /skill:visual-explainer draw the microservices architecture |
| 88 | +``` |
| 89 | + |
| 90 | +Output goes to `~/.agent/diagrams/` and the result opens in your browser. |
| 91 | + |
| 92 | +## Prompt Templates |
| 93 | + |
| 94 | +The skill ships with five prompt templates that become slash commands in Pi: |
| 95 | + |
| 96 | +| Command | What it does | |
| 97 | +|---------|-------------| |
| 98 | +| `/generate-web-diagram` | Generate an HTML diagram for any topic | |
| 99 | +| `/diff-review` | Visual diff review — before/after architecture, KPI dashboard, code review, decision log | |
| 100 | +| `/plan-review` | Compare a plan against the codebase — current vs. planned architecture, risk assessment | |
| 101 | +| `/project-recap` | Visual snapshot for context-switching back to a project after days away | |
| 102 | +| `/fact-check` | Verify factual accuracy of a review page, plan doc, or spec against the actual code | |
| 103 | + |
| 104 | +### `/diff-review` |
| 105 | + |
| 106 | +Accepts any git ref. Generates architecture comparison, file map, structured Good/Bad/Ugly code review, decision log with confidence indicators, and re-entry context. |
| 107 | + |
| 108 | +``` |
| 109 | +/diff-review main # feature branch vs main (default) |
| 110 | +/diff-review abc123 # single commit |
| 111 | +/diff-review main..HEAD # committed changes only |
| 112 | +/diff-review #42 # pull request |
| 113 | +/diff-review HEAD # uncommitted changes only |
| 114 | +``` |
| 115 | + |
| 116 | +### `/plan-review` |
| 117 | + |
| 118 | +Compares a codebase against an implementation plan. Current vs. planned architecture diagrams, change-by-change breakdown, dependency analysis, risk assessment, and Good/Bad/Ugly review of the plan itself. |
| 119 | + |
| 120 | +``` |
| 121 | +/plan-review ~/docs/refactor-plan.md # plan + working directory |
| 122 | +/plan-review ~/docs/refactor-plan.md ./src # plan + explicit path |
| 123 | +``` |
| 124 | + |
| 125 | +### `/project-recap` |
| 126 | + |
| 127 | +Mental model snapshot — architecture diagram, recent activity, decision log, working/broken/blocked dashboard, cognitive debt hotspots. Takes an optional time window: |
| 128 | + |
| 129 | +``` |
| 130 | +/project-recap # last 2 weeks (default) |
| 131 | +/project-recap 30d # last 30 days |
| 132 | +``` |
| 133 | + |
| 134 | +### `/fact-check` |
| 135 | + |
| 136 | +Extracts every verifiable claim from a document (file references, function names, line counts, behavior descriptions), re-checks each against the actual code, corrects inaccuracies, and adds a verification summary: |
| 137 | + |
| 138 | +``` |
| 139 | +/fact-check # most recent review page |
| 140 | +/fact-check ~/.agent/diagrams/diff-review.html # specific file |
| 141 | +/fact-check ~/Documents/docs/refactor-plan.md # plan doc |
| 142 | +``` |
| 143 | + |
| 144 | +## Diagram Types |
| 145 | + |
| 146 | +| Type | Rendering | When to use | |
| 147 | +|------|-----------|-------------| |
| 148 | +| Architecture (text-heavy) | CSS Grid cards + flow arrows | System overviews with rich descriptions | |
| 149 | +| Architecture (topology) | Mermaid | Service maps, connection diagrams | |
| 150 | +| Flowchart / Pipeline | Mermaid | CI/CD, data pipelines, processes | |
| 151 | +| Sequence | Mermaid | Service-to-service calls, request flows | |
| 152 | +| Data flow | Mermaid with edge labels | ETL, event streaming, message flows | |
| 153 | +| Schema / ER | Mermaid | Database schemas, entity relationships | |
| 154 | +| State machine | Mermaid | State transitions, decision trees | |
| 155 | +| Mind map | Mermaid | Hierarchical breakdowns, project structure | |
| 156 | +| Data table | HTML `<table>` | Comparisons, audits, feature matrices | |
| 157 | +| Timeline | CSS | Roadmaps, release history, project phases | |
| 158 | +| Dashboard | CSS Grid + Chart.js | Metrics overviews, KPI displays | |
| 159 | + |
| 160 | +The agent picks the right rendering approach automatically. Mermaid handles anything with connections and automatic edge routing. CSS Grid handles text-heavy content where card descriptions matter more than topology. HTML tables handle structured data. |
| 161 | + |
| 162 | +## How It Works |
| 163 | + |
| 164 | +``` |
| 165 | +SKILL.md (workflow + design principles) |
| 166 | + ↓ |
| 167 | +references/ ← agent reads on-demand before each generation |
| 168 | +├── css-patterns.md (layouts, animations, theming, depth tiers) |
| 169 | +├── libraries.md (Mermaid deep theming, Chart.js, anime.js, font pairings) |
| 170 | +└── responsive-nav.md (sticky sidebar TOC for multi-section pages) |
| 171 | + ↓ |
| 172 | +templates/ ← agent reads the matching reference template |
| 173 | +├── architecture.html (CSS Grid cards with flow arrows — terracotta/sage palette) |
| 174 | +├── mermaid-flowchart.html (Mermaid + ELK + handDrawn mode — teal/cyan palette) |
| 175 | +└── data-table.html (tables with KPIs and status badges — rose/cranberry palette) |
| 176 | + ↓ |
| 177 | +~/.agent/diagrams/filename.html → opens in browser |
| 178 | +``` |
| 179 | + |
| 180 | +The agent follows a four-step workflow: pick an aesthetic direction (9 options — monochrome terminal, editorial, blueprint, neon, paper/ink, sketch, IDE-inspired, data-dense, gradient mesh), read the right reference template, generate a self-contained HTML file with both light and dark theme support, and open it. Each template uses a deliberately different color palette so the agent absorbs variety rather than a single look. |
| 181 | + |
| 182 | +Every diagram is a single `.html` file with all styles inlined. The only external requests are Google Fonts and optional CDN libraries (Mermaid, Chart.js, anime.js). No build step, no npm, no bundler. Open it in any browser, send it to a colleague, drop it in a PR. |
| 183 | + |
| 184 | +## Customization |
| 185 | + |
| 186 | +Output directory and browser command are in `SKILL.md` under the "Deliver" section — edit to match your setup. To add diagram types, aesthetic directions, or CSS patterns, edit the respective files. The agent reads them fresh each time, so changes take effect immediately (unless you modify the frontmatter `description`, which needs a Pi restart for re-indexing). |
| 187 | + |
| 188 | +## Limitations |
| 189 | + |
| 190 | +- Diagrams require a browser to view — no inline terminal rendering |
| 191 | +- Mermaid diagrams initialize once at page load; switching OS theme requires a refresh for the Mermaid SVG (CSS-styled elements respond instantly) |
| 192 | +- Google Fonts need an internet connection on first load (system font fallbacks are included) |
| 193 | +- Very complex Mermaid diagrams (50+ nodes) may need the ELK layout engine for clean edge routing, which adds CDN weight |
| 194 | +- The agent picks aesthetics based on skill guidance, not pixel-perfect design specs — results vary by model capability |
| 195 | + |
| 196 | +## Credits |
| 197 | + |
| 198 | +Borrows ideas from [Anthropic's frontend-design skill](https://github.com/anthropics/skills) and [interface-design](https://github.com/Dammyjay93/interface-design), adapted for one-shot diagram generation. |
| 199 | + |
| 200 | +## License |
| 201 | + |
| 202 | +MIT |
0 commit comments