visualize
GitHub生成自包含HTML文件以可视化系统、架构或代码流程。采用优雅设计，支持Mermaid图表和SVG，强调视觉优先与准确性，避免ASCII艺术。
Trigger Scenarios
Install
npx skills add NeverSight/learn-skills.dev --skill visualize -g -y
SKILL.md
Frontmatter
{
"name": "visualize",
"license": "MIT",
"metadata": {
"author": "Andy Pai",
"version": "1.2",
"upstream_skill": "https:\/\/github.com\/nicobailon\/visual-explainer"
},
"description": "Generate a self-contained HTML visualization to explain a system, plan, code flow, or concept. Use when the user asks to visualize, diagram, explain visually, or walk through a system, architecture, plan, or code flow. Outputs a single HTML file opened in the browser."
}
Visualize
Generate a single, self-contained HTML file that visually explains a system, plan, code flow, or concept. The output opens in the browser — never fall back to ASCII art when this skill is loaded.
Default aesthetic: the "HTML effectiveness" editorial gallery style. Use an ivory page, serif display headings, clay accents, quiet card grids, simple SVG illustrations, and generous whitespace. The page should feel like something the user wants to read, not a dashboard skin.
When to Use
- Visualize a complicated plan or proposal
- Explain key primitives before implementing a plan
- Visual explanation of steps from a third-party repo or blog post
- Understand a module's code flow or execution path
Workflow
- Understand what the user wants to see — the subject, the audience, the level of detail.
- Read
./templates/base.htmlto absorb the tech stack and HTML-effectiveness style. Read it each time, do not rely on memory. - Pick the format (see Format Guide below).
- For Mermaid diagrams with 10+ nodes, also read
./references/mermaid-tips.md. - Adapt the base template for this specific visualization. Reuse the structure, swap the visual area content.
- Write to
~/.agent/diagrams/<descriptive-name>.htmland open in the browser.
Format Guide
| Intent | Approach |
|---|---|
| Flows, processes, sequences | SVG/CSS boxes and arrows first; Mermaid.js when the graph is large |
| Architecture, system overview | SVG/CSS module map or card grid |
| Comparisons, data | HTML <table> |
| Step-by-step concepts | Numbered sections and cards |
| Timelines, roadmaps | CSS timeline in the visual area |
| Code review / PR explanation | Annotated diff cards, severity labels, reviewer focus list |
| Prompt/config tuning | Purpose-built editor with copy/export button |
Tech Stack
Every generated file uses:
- Preact + htm — ESM CDN imports, no build step
- Plain CSS custom properties — no build step or generated CSS
- System fonts — serif display, sans body, mono metadata
- Mermaid.js CDN — add only when diagrams are needed
No other dependencies. No build step.
For the full HTML-effectiveness design tokens (colors, typography, layout, motion), see ./references/design-system.md.
Principles
- One primary visual anchor per request, plus supporting evidence visuals when reviewing a plan or system
- Visual first — the main content is a diagram, chart, or table, not prose
- Adapt the base template — don't start from scratch
- Correct over pretty — the visualization must accurately represent the information
- Interactive when it helps comprehension (step-through, hover, collapse)
- Export when the page edits data — include copy as JSON/Markdown/prompt when the artifact is a tuner or editor
- Never use
innerHTMLwith user-provided content (XSS prevention)
Avoiding Escaped Backticks in Output
The Write tool can corrupt JavaScript template literals, writing literal \`` and ${` instead of real backticks and interpolations. This breaks all htm tagged templates. To prevent it:
- Extract data into separate
constvariables above the htm templates. Mermaid chart definition strings, config arrays, long text — declare them as plain constants first, then reference the variable insidehtml\...``. - Keep htm expressions simple. Pass variables by reference (
${myVar},${myArray.map(...)}). Do not build complex multi-line strings or nested template literals inline within anhtml\...`` block. - Verify after writing. Re-read the first 30 lines of the
<script type="module">block in the written file and confirm there are no escaped sequences (\`` or${). If Chrome DevTools MCP is available, check the browser console forSyntaxError` after opening the file.
Before Delivering
- First screen test: is a meaningful visual visible without scrolling?
- File opens cleanly: no console errors, no broken fonts?
Output
Write to ~/.agent/diagrams/ with a descriptive filename (auth-flow.html, pipeline-overview.html).
Open in browser:
- macOS:
open ~/.agent/diagrams/filename.html - Linux:
xdg-open ~/.agent/diagrams/filename.html
Tell the user the file path and name the visuals you included.
Update Check
On first use in a session, silently check for a newer version:
- Fetch
https://raw.githubusercontent.com/abpai/skills/main/versions.json. - Compare the version for
visualizeagainst this file'smetadata.version. - If the remote version is newer, pause before the main task and ask:
visualize update available (local {X.Y} → remote {A.B}). Would you like me to update it for you first? I can run
npx skills update visualizefor you. - If the user says yes, run the update before continuing.
- If the user says no, continue with the current local version.
- If the fetch fails or web access is unavailable, skip silently.
Version History
- e0220ca Current 2026-07-05 22:20
