Visual Explainer
Agent skill that generates rich HTML pages or slide decks for diagrams, diff reviews, plan audits, data tables, and project recaps
nicobailon · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add nicobailon/visual-explainer技能说明
name: visual-explainer description: Generate self-contained HTML visual explanations for systems, code changes, plans, data, and technical concepts. Use for diagrams, architecture overviews, diff or plan reviews, project recaps, comparison tables, slide decks, and other visual explanations. license: MIT compatibility: Requires a browser to view generated HTML files. Optional surf-cli for AI image generation. metadata: author: nicobailon version: "0.11.0"
Visual Explainer
Generate self-contained HTML pages that explain systems, code changes, plans, data, and technical concepts visually. Use this skill for diagram requests, architecture overviews, diff/plan reviews, project recaps, comparison tables, slide decks, and any visual explanation.
Trigger and delivery rules
- Prefer an HTML page over terminal ASCII when the output is inherently visual.
- If a table would have 4+ rows or 3+ columns, render it as HTML and give only a short chat summary.
- Write files to
~/.agent/diagrams/or the explicit eval output path. Use descriptive filenames. - Generate a Markdown companion only when the user explicitly asks for AI-readable output or a source brief. Keep HTML as the final visual output; Markdown is a companion, never the source for HTML. Write
<name>.mdbeside<name>.htmlwhen possible, and ask before replacing an existing companion file. - Open generated pages in the browser when running normally. In Pi package installs, use
visual_explainerwithpreparefor planning/context andrenderonly after the complete HTML document exists. MCP hosts usevisual-explainer-mcp, which defaults render tools toopen: false. Useviewer: "glimpse"only when the user wants a native Glimpse window andglimpseuiis installed;viewer: "auto"may fall back to the browser. - The final page must be a complete self-contained HTML document, including embedded CSS, a self-contained favicon, and any needed JS. In Pi,
visual_explainer.renderalso adds missinghtml lang, missing viewport metadata, and display-math escaping for raw</>inside$$...$$.
Quick mode
Quick mode is opt-in. Use it only when --quick appears on /generate-web-diagram, /diff-review, /plan-review, or /project-recap. Default and all other prompt behavior remains full HTML generation.
For quick mode, read ./quick/README.md and ./quick/schema.json. Gather and verify the same source facts as full mode, but emit the compact JSON spec. In Pi, call the existing visual_explainer tool with action: "render_quick", filename, spec, and optional open or viewer. In other harnesses, save the JSON and call the local ./quick/render.mjs script. The renderer validates the spec and creates the complete HTML document.
Quick mode is not suitable for custom visual composition, slides, Mermaid-rich topology, or content that the schema cannot express. If it is not a fit, schema validation fails, or rendering errors, fall back to the normal full HTML workflow and render action. Do not use quick mode for slides, fact-check, visual plans, PPTX, themes, or updates.
Design judgment
Before writing any HTML:
- Calibrate treatment: diff reviews, memos, audits, and recaps get polished-utilitarian (real hierarchy, considered spacing, no flashy hero); showcases and narrative decks get editorial. A well-composed page is never wrong; an over-designed one sometimes is.
- Precedence: the user's words, then the project's existing design system (theme/token files, component styles), then this skill's choices. Check repo tokens before picking a palette for diff/plan reviews.
- Plan first: 4–6 named hex values, type roles, a one-sentence layout concept. Audit once — "would I produce this plan for any similar page?" — and revise the generic parts. (Generic: slate
#0f172a, indigo, Inter, hero plus three cards. Revised for a CLI recap: near-black green, phosphor text, amber accent, JetBrains Mono — terminal direction, layout follows the release timeline.) - Structure must encode something true: 01/02/03 markers only when order matters, eyebrow labels only when they classify, dividers only at real seams.
Reference routing
Read only the references needed for the current output:
| Need | Read |
|---|---|
| Text-heavy architecture/cards | ./templates/architecture.html |
| Mermaid flowcharts, sequence, ER, state, class, C4, data flow | ./templates/mermaid-flowchart.html, Mermaid sections in ./references/libraries.md |
| Data tables, comparisons, audits | ./templates/data-table.html |
| Slide decks | ./templates/slide-deck.html, ./references/slide-patterns.md |
| CSS layout, type scale, overflow, depth, collapsibles, SVG connectors, generated images | ./references/css-patterns.md |
| Pages with 4+ major sections | ./references/responsive-nav.md |
| Switchable themes or fonts, or a named palette (Dracula, Nord, Gruvbox…) | ./references/themes.md |
| Prose-heavy pages | “Prose Page Elements” in css-patterns.md, typography sections in libraries.md |
Choose the representation
| Content | Default representation |
|---|---|
| Flowchart, pipeline, state machine, decision tree | Mermaid |
| Sequence, ER/schema, class, C4, topology-focused architecture | Mermaid |
| Text-heavy architecture, module internals, implementation plans | CSS grid cards, optionally with a Mermaid overview |
| 15+ element architecture | Hybrid: small Mermaid overview + CSS detail cards |
| Comparison/audit/status matrix | Semantic HTML <table> |
| Timeline/roadmap | CSS timeline |
| Dashboard/metrics | CSS grid + charts/KPIs |
| Slide deck | 100dvh slides using slide template patterns |
Mermaid invariants
What to draw, before how:
- Depict the mechanism, not its name: the path a request takes through a cache says more than a box labeled "cache".
- Label every arrow (
writes,invalidates,polls every 30s); an unlabeled arrow only says "related somehow". - To compare options, draw the difference