visual-explainer
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
- 最近更新
- 2026-07-16
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- visual-explainer
- license
- MIT
- metadata
- { "author": "nicobailon", "version": "0.8.1" }
- 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.
- compatibility
- Requires a browser to view generated HTML files. Optional surf-cli for AI image generation.
02 资源文件 19
- 参考文档.claude-plugin/plugin.json301 B
- 参考文档commands/diff-review.md1.9 KB
- 参考文档commands/fact-check.md1.1 KB
- 参考文档commands/generate-slides.md952 B
- 参考文档commands/generate-visual-plan.md1.3 KB
- 参考文档commands/generate-web-diagram.md699 B
- 参考文档commands/plan-review.md1.6 KB
- 参考文档commands/project-recap.md1.4 KB
- 参考文档commands/share.md1.4 KB
- 脚本extension.ts12.7 KB
- 参考文档references/css-patterns.md44.2 KB
- 参考文档references/libraries.md20.8 KB
- 参考文档references/responsive-nav.md5.7 KB
- 参考文档references/slide-patterns.md44.1 KB
- 脚本scripts/share.sh2.0 KB
- 参考文档templates/architecture.html17.1 KB
- 参考文档templates/data-table.html15.9 KB
- 参考文档templates/mermaid-flowchart.html21.2 KB
- 参考文档templates/slide-deck.html34.7 KB
03 SKILL.md 正文
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. - 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. - The final page must be a complete self-contained HTML document, including embedded CSS and any needed JS.
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, overflow, depth, collapsibles, SVG connectors, generated images | ./references/css-patterns.md |
| Pages with 4+ major sections | ./references/responsive-nav.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
- Use
theme: 'base'with customthemeVariablesmatching the page palette. - For complex diagrams use ELK layout when available.
- Never use bare
<pre class="mermaid">. - Use the canonical
diagram-shellpattern fromtemplates/mermaid-flowchart.html:.diagram-shell>.mermaid-wrap>.zoom-controls+.mermaid-viewport>.mermaid-canvas. - Every Mermaid diagram needs zoom in/out/reset/expand controls, Ctrl/Cmd+scroll zoom, drag panning, and click-to-expand.
- Prefer
flowchart TDfor complex diagrams. UseLRonly for simple 3–4 node linear flows. - Use
<br/>in quoted flowchart labels. Do not use escaped\nlabels. - Never define page-level
.node; Mermaid uses it internally. Use namespaced page classes such as.ve-card. - For 15+ elements, do not cram everything into one Mermaid diagram. Use the hybrid overview + cards pattern.
Layout and style invariants
- Use semantic HTML where it helps accessibility and copy/paste:
<table>, headings, lists,<details>, captions. - Use CSS custom properties for palette:
--bg,--surface,--border,--text,--text-dim, and 3–5 accents. - Pick a clear aesthetic direction before writing: blueprint, editorial, paper/ink, terminal, IDE-inspired, or data-dense.
- Avoid generic defaults: no body font that is only Inter, Roboto, Arial, Helvetica, or system-ui; no violet/fuchsia Tailwind-default accents as the main palette (
#8b5cf6,#7c3aed,#a78bfa,#d946ef); no cyan+magenta+purple neon dashboard; no gradient-mesh blobs. - Good font pair families: DM Sans + Fira Code; Instrument Serif + JetBrains Mono; IBM Plex Sans + IBM Plex Mono; Bricolage Grotesque + Fragment Mono; Plus Jakarta Sans + Azeret Mono.
- Good accent directions: terracotta+sage, teal+slate, rose+cranberry, amber+emerald, deep blue+gold.
- Prevent overflow:
min-width: 0on grid/flex children,overflow-wrap: break-wordfor long text, and scroll containers for wide tables/code. - Do not set
display: flexdirectly on<li>when list markers matter. - Use depth sparingly: hero/elevated only for primary sections; flat/recessed for reference material.
- Use entrance/hover animation only when it clarifies hierarchy. Respect
prefers-reduced-motion. Do not use continuous glow, pulse, or breathing effects on static content.
Slide deck mode
Use slides only when explicitly requested or when a command asks for slides. Slides are a different medium, not a paginated article:
- Each slide is one viewport (
100dvh) with no page-level scrolling. - Use larger type, fewer objects per slide, varied compositions, and visible navigation.
- Include slide nav chrome from
slide-deck.html: prev/next controls, slide count, keyboard navigation, and carousel dots/indicators. - Before writing HTML, inventory the source and map every source item to slides.
- Do not drop content to fit a fixed slide count. Add slides instead.
- Use the 10 slide types from
slide-patterns.md: Title, Section Divider, Content, Split, Diagram, Dashboard, Table, Code, Quote, Full-Bleed.
Optional generated images
If surf is available, generated images may be embedded as base64 for hero banners, conceptual illustrations, or educational visuals. Skip images for data-heavy, structural, or Mermaid/CSS-suitable content. Pages must stand on CSS, typography, and diagrams without images.
Final checklist
Before delivery, verify:
- complete HTML document;
- output written to the requested path;
- no console errors when opened;
- no horizontal overflow at normal desktop width;
- fonts load with fallbacks;
- tables preserve rows/columns and wrap long text;
- Mermaid diagrams use
diagram-shellwith zoom/pan/expand; - slides fit one viewport, include carousel dots, and preserve source coverage;
- visual hierarchy makes the main idea obvious in the first viewport;
- styling would still be recognizable if compared against a generic dark/violet template.
04 同仓库更多 Skills
to-prompt-opus
Use when preparing or rewriting prompts for Claude Opus 4.8, Anthropic API agents, XML-structured prompts, long-context document work, coding agents, research synthesis, frontend/design tasks, or model-specific prompt optimization. Do not use for GPT/OpenAI prompts or raw context packaging without Opus-specific tuning.
to-prompt-gpt
Use when preparing or rewriting prompts for GPT-5.5, OpenAI API agents, Responses workflows, coding agents, research synthesis, support assistants, or model-specific prompt optimization. Do not use for Claude/Opus prompts or raw context packaging without GPT-specific tuning.
plan-refactor-qa
Plans and runs qa-report before executing Compozy refactor tasks. Use when the user provides a refactor or issue slug and wants Codex to inspect the matching .compozy/tasks directory, related PRD/TechSpec/ADR/task artifacts, affected code, and existing tests, then invoke $qa-report with a repository-grounded prompt. Do not use to run tests, execute qa-execution, implement code, or perform post-refactor verification.
multi-tool-branch-review
Orchestrates a multi-tool branch review of the current git branch against a base branch. By default it runs two independent thermo-nuclear maintainability audits, one on Codex GPT-5.5 xhigh and one on Claude Opus xhigh, then consolidates the findings into a single remediation plan via writing-plans. If the user explicitly asks for native reviews, it can add the Claude native review pass, the Codex native review pass, or both. Use when the user wants a deep cross-model review of a branch or PR before merge, or asks to review this branch with multiple tools or models. Encodes known infra failure modes and their fixes (missing Claude ACP adapter, Codex MCP auth hangs, false-positive report files, long jobs orphaned inside subagents). Do not use for reviewing a single uncommitted snippet, for non-git work, for running only one reviewer, or when the user only wants a quick lint or test run.
create-pr-with-template
Create a GitHub Pull Request with gh CLI and prefer repository PR templates automatically. Use this whenever the user asks to open/create a PR, especially when template compliance is needed. If multiple templates exist, ask the user which template to use.
ui-craft
Provides guardrails for user-facing UI work: usability heuristics, accessibility floors, design-system discipline, component states, microcopy, motion, dark mode, responsive behavior, and human-AI UX. Use when designing, generating, reviewing, or refactoring visible product surfaces such as components, pages, dashboards, forms, dialogs, loading/empty/error states, or AI interfaces. Do not use for backend-only work, infrastructure, CLI/TUI design, or pure documentation editing.