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

1. Understand what the user wants to see — the subject, the audience, the level of detail.
2. Read ./templates/base.html to absorb the tech stack and HTML-effectiveness style. Read it each time, do not rely on memory.
3. Pick the format (see Format Guide below).
4. For Mermaid diagrams with 10+ nodes, also read ./references/mermaid-tips.md.
5. Adapt the base template for this specific visualization. Reuse the structure, swap the visual area content.
6. Write to ~/.agent/diagrams/<descriptive-name>.html and 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 innerHTML with 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:

1. Extract data into separate const variables above the htm templates. Mermaid chart definition strings, config arrays, long text — declare them as plain constants first, then reference the variable inside html\...``.
2. Keep htm expressions simple. Pass variables by reference (${myVar}, ${myArray.map(...)}). Do not build complex multi-line strings or nested template literals inline within an html\...`` block.
3. 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:

1. Fetch https://raw.githubusercontent.com/abpai/skills/main/versions.json.
2. Compare the version for visualize against this file's metadata.version.
3. 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 visualize for you.

4. If the user says yes, run the update before continuing.
5. If the user says no, continue with the current local version.
6. If the fetch fails or web access is unavailable, skip silently.