🔥 chore(skills): moved everything to universal .agents folder, introduced mise...

.DS_Store

installed_at: '2026-02-25T00:58:21+00:00'

skill_id: git/visual-explainer

git_repo: https://github.com/nicobailon/visual-explainer

skill_path: C:\Users\Jan.Reimes\AppData\Local\Temp\skilz-git-yvx3xwe8

git_sha: 92f59e6a5ba139ba029ea17b8da89d448d846aa6

skilz_version: 1.10.0

install_mode: copy

canonical_path: null

# Changelog

## [0.1.3] - 2026-02-24

- Extended `classDef` color warning to also cover per-node `style` directives — both hardcode text color that breaks in the opposite color scheme

- Renamed `.node` card classes to `.ve-card` to fix CSS collision with Mermaid's internal `.node` class that broke diagram layout (PR #7)

## [0.1.2] - 2026-02-19

- Added sequence diagram syntax guidance to "Writing Valid Mermaid" — curly braces, brackets, and ampersands in message labels silently break rendering

## [0.1.1] - 2026-02-19

- Prompts no longer require the `pi-prompt-template-model` extension — each prompt now explicitly loads the skill itself

- Added "Writing Valid Mermaid" section to `libraries.md` (quoting special chars, simple IDs, max node count, arrow styles, pipe escaping)

- Fixed mobile scroll offset in `responsive-nav.md` — section headings now clear the sticky nav bar via `scroll-margin-top`

- Added video preview to README

## [0.1.0] - 2026-02-16

Initial release.

### Skill

- Core workflow: Think (pick aesthetic) → Structure (read template) → Style (apply design) → Deliver (write + open)

- 11 diagram types with rendering approach routing (Mermaid, CSS Grid, HTML tables, Chart.js)

- 9 aesthetic directions (monochrome terminal, editorial, blueprint, neon, paper/ink, sketch, IDE-inspired, data-dense, gradient mesh)

- Mermaid deep theming with `theme: 'base'` + `themeVariables`, hand-drawn mode, ELK layout

- Zoom controls (buttons, scroll-to-zoom, drag-to-pan) required on all Mermaid containers

- Proactive table rendering — agent generates HTML instead of ASCII for complex tables

- Optional AI-generated illustrations via surf-cli + Gemini Nano Banana Pro

- Both light and dark themes via CSS custom properties and `prefers-color-scheme`

- Quality checks: squint test, swap test, overflow protection, zoom controls verification

### References

- `css-patterns.md` — theme setup, depth tiers, node cards, grid layouts, data tables, status badges, KPI cards, before/after panels, connectors, animations (fadeUp, fadeScale, drawIn, countUp), collapsible sections, overflow protection, generated image containers

- `libraries.md` — Mermaid (CDN, ELK, deep theming, hand-drawn mode, CSS overrides, diagram examples), Chart.js, anime.js, Google Fonts with 13 font pairings

- `responsive-nav.md` — sticky sidebar TOC on desktop, horizontal scrollable bar on mobile, scroll spy

### Templates

- `architecture.html` — CSS Grid card layout, terracotta/sage palette, depth tiers, flow arrows, pipeline with parallel branches

- `mermaid-flowchart.html` — Mermaid flowchart with ELK + handDrawn mode, teal/cyan palette, zoom controls

- `data-table.html` — HTML table with KPI cards, status badges, collapsible details, rose/cranberry palette

### Prompt Templates

- `/generate-web-diagram` — generate a diagram for any topic

- `/diff-review` — visual diff review with architecture comparison, KPI dashboard, code review, decision log

- `/plan-review` — plan vs. codebase with current/planned architecture, risk assessment, understanding gaps

- `/project-recap` — project mental model snapshot for context-switching

- `/fact-check` — verify factual accuracy of review pages and plan docs against actual code

MIT License

Copyright (c) 2025 Nico Bailon

Permission is hereby granted, free of charge, to any person obtaining a copy

of this software and associated documentation files (the "Software"), to deal

in the Software without restriction, including without limitation the rights

to use, copy, modify, merge, publish, distribute, sublicense, and/or sell

copies of the Software, and to permit persons to whom the Software is

furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all

copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,

OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

SOFTWARE.

<p>

  <img src="banner.png" alt="visual-explainer" width="1100">

</p>

# visual-explainer

**An agent skill that turns complex terminal output into styled HTML pages you actually want to read.**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](LICENSE)

Ask your agent to explain a system architecture, review a diff, or compare requirements against a plan. Instead of ASCII art and box-drawing tables, it generates a self-contained HTML page and opens it in your browser:

```

> draw a diagram of our authentication flow

> /diff-review

> /plan-review ~/docs/refactor-plan.md

```

Each one produces a single `.html` file with real typography, dark/light theme support, and interactive Mermaid diagrams with zoom and pan. No build step, no dependencies beyond a browser.

https://github.com/user-attachments/assets/55ebc81b-8732-40f6-a4b1-7c3781aa96ec

## Why

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.

Tables are worse. 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.

## Install

The skill follows the [Agent Skills specification](https://agentskills.io/specification). Clone it into your agent's skills directory:

```bash

# Pi

git clone https://github.com/nicobailon/visual-explainer.git ~/.pi/agent/skills/visual-explainer

# Claude Code

git clone https://github.com/nicobailon/visual-explainer.git ~/.claude/skills/visual-explainer

# Other agents — point at the directory containing SKILL.md,

# or paste its contents into your system prompt

```

For Pi, restart after cloning. To get the slash commands (`/diff-review`, `/plan-review`, etc.), copy the prompt templates:

```bash

cp ~/.pi/agent/skills/visual-explainer/prompts/*.md ~/.pi/agent/prompts/

```

If you have [surf-cli](https://github.com/nicobailon/surf-cli) installed, the skill can also generate illustrations via Gemini Nano Banana Pro and embed them in pages. The agent detects surf automatically and skips image generation if it's not there.

## Usage

The agent loads the skill when you mention diagrams, architecture, flowcharts, schemas, or visualizations. It also kicks in automatically when it's about to dump a complex table in the terminal (4+ rows or 3+ columns) — it renders HTML instead and opens it in the browser. Output goes to `~/.agent/diagrams/`.

The skill ships with five prompt templates:

| Command | What it does |

|---------|-------------|

| `/generate-web-diagram` | Generate an HTML diagram for any topic |

| `/diff-review` | Visual diff review with architecture comparison, code review, decision log |

| `/plan-review` | Compare a plan against the codebase with risk assessment |

| `/project-recap` | Mental model snapshot for context-switching back to a project |

| `/fact-check` | Verify accuracy of a review page or plan doc against actual code |

`/diff-review` is probably the most useful. Run it with no arguments to diff against `main`, or pass any git ref:

```

/diff-review                   # feature branch vs main (default)

/diff-review abc123            # single commit

/diff-review main..HEAD        # committed changes only

/diff-review #42               # pull request

```

It generates a full page with before/after architecture diagrams, KPI dashboard, structured Good/Bad/Ugly code review, decision log with confidence indicators, and re-entry context for your future self.

`/plan-review` does something similar but for implementation plans — pass it a plan file and it cross-references every claim against the actual codebase, produces current vs. planned architecture diagrams, and flags risks and gaps:

```

/plan-review ~/docs/refactor-plan.md

```

`/project-recap` is designed for context-switching back to a project after days away. It scans recent git activity and produces an architecture snapshot, decision log, and cognitive debt hotspots. `/fact-check` takes any document that makes claims about code and verifies every one of them.

## How It Works

```

SKILL.md (workflow + design principles)

    ↓

references/           ← agent reads before each generation

├── css-patterns.md   (layouts, animations, theming, depth tiers)

├── libraries.md      (Mermaid theming, Chart.js, anime.js, font pairings)

└── responsive-nav.md (sticky sidebar TOC for multi-section pages)

    ↓

templates/            ← agent reads the matching reference template

├── architecture.html (CSS Grid cards — terracotta/sage palette)

├── mermaid-flowchart.html (Mermaid + ELK + handDrawn — teal/cyan palette)

└── data-table.html   (tables with KPIs and badges — rose/cranberry palette)

    ↓

~/.agent/diagrams/filename.html → opens in browser

```

The agent picks an aesthetic direction, reads the right reference template, generates a self-contained HTML file with both light and dark themes, and opens it. The three templates use deliberately different palettes so the agent learns variety rather than defaulting to one look. The skill handles 11 diagram types — Mermaid for anything with connections (flowcharts, sequences, ER, state machines, mind maps), CSS Grid for text-heavy architecture overviews, HTML tables for data, Chart.js for dashboards — and routes to the right approach automatically.

To customize the output directory, browser command, or add your own diagram types and CSS patterns, edit the files directly. The agent reads them fresh each time.

## Limitations

- Requires a browser to view — no inline terminal rendering

- Switching OS theme requires a page refresh for Mermaid SVGs (CSS-styled elements respond instantly)

- Results vary by model capability — the skill provides design guidance, not pixel-perfect specs

## Credits

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.

## License

MIT