跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

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>.md beside <name>.html when possible, and ask before replacing an existing companion file.
  • Open generated pages in the browser when running normally. In Pi package installs, use visual_explainer with prepare for planning/context and render only after the complete HTML document exists. MCP hosts use visual-explainer-mcp, which defaults render tools to open: false. Use viewer: "glimpse" only when the user wants a native Glimpse window and glimpseui is 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.render also adds missing html 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:

NeedRead
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

ContentDefault representation
Flowchart, pipeline, state machine, decision treeMermaid
Sequence, ER/schema, class, C4, topology-focused architectureMermaid
Text-heavy architecture, module internals, implementation plansCSS grid cards, optionally with a Mermaid overview
15+ element architectureHybrid: small Mermaid overview + CSS detail cards
Comparison/audit/status matrixSemantic HTML <table>
Timeline/roadmapCSS timeline
Dashboard/metricsCSS grid + charts/KPIs
Slide deck100dvh 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
阅读完整来源 ↗