visualize v1.8.0A

Immutable. This exact content never changes and is served at /api/v1/blob/6308952619fb9381.

---
name: visualize
version: "1.8.0"
description: "Explain or present a topic: answer it with the SMALLEST view that makes the point — inline pseudocode, call tree, component tree, annotated file tree, or a matched-shape diff in chat — and render a set of things as ONE self-contained HTML document with a URL. Understands what you want (a codebase, modules, data, a plan, a comparison, an architecture, a set of items, or a structured report with findings), picks the right form, and builds a single portable HTML file — then opens it locally and optionally shares it as a short-lived URL. Triggers on: visualize, show me, explain this, make me a page, render this as HTML, show this as a diagram/page, turn this into a report, generate a report, put it on a page."
---

# visualize — one self-contained HTML for any set of things

Turns a request into **one HTML file** — content and layout inline, popular packages
(Mermaid, Tailwind) optionally via CDN — then gives the user a URL. Two modes:
**Visualize** (display a set of things: cards, tree, system map) and **Report** (a
structured document: exec summary, findings, recommendations —
[references/report.md](references/report.md)). `d2`/`figure` are manual-only
(`/skill:d2` / `/skill:figure`); when to hand off vs. build inline:
[references/routing.md](references/routing.md).

**Not every answer needs a page.** A pseudocode block, call tree, component tree, annotated
file tree, or a matched-shape **diff** placed next to the sentence it supports often answers the
question better — and smaller. See [references/code-forms.md](references/code-forms.md).

## Workflow

### 1. Understand — mode, then pattern, then structure

**First: does this need a page at all?** If one inline form answers it — pseudocode, call tree,
component tree, annotated file tree, or a diff matched to the shape — answer inline with
[references/code-forms.md](references/code-forms.md) and skip the rest. Build a page when the
content is a *set* to scan, share, or print, when the user named a deliverable ("for my deck",
"put it in the README"), or when no single inline form fits.

Mode = **report** when the deliverable is a *document* — "write a report", "evaluate",
"assess", "findings + recommendations" → [references/report.md](references/report.md).
Mode = **visualize** when it's a *display* of a set of things — "show the repo",
"compare", "map the platform" → structure from
[references/structures.md](references/structures.md). A report can *embed* a
visualization; the mode is set by the deliverable. Don't blur them.

Then the **d2 / figure routing check** ([references/routing.md](references/routing.md)):
complex technical diagram → recommend `/skill:d2` and stop; hand-drawn presentation
figure → recommend `/skill:figure`; otherwise build it here.

When behaviour, state, or risk is load-bearing, name the **semantic pattern** first ([references/patterns.md](references/patterns.md) — complexity budgets + static fallbacks); then the structure: `overview-grid`, `cards`, `before-after`, `list`, `timeline`, `flow`, `comparison`, `hierarchy`. One strong structure beats a kitchen sink.

### 2. Build — compose one HTML page

**Set the output target first** — `page` (default), `slide`, `doc`, `social`, `print`;
target changes canvas, density, and copy: [references/output.md](references/output.md).

**Instantiate, don't hand-roll.** Read the closest template (`cards`, `report`,
`system-map`, `repo-tree`, `mermaid`, `timeline`, `before-after`, `cheatsheet`,
`barchart` — all in `templates/`) for the scaffold — or compose from
page modules ([references/modules.md](references/modules.md)): copy the **shared base**
once (all module CSS lives there), then write **short class-based HTML** per module
(`header`, `legend`, `card-grid`, `tree`, `flow`, `table`, `section`, `exec-summary`,
`recommendations`, `mermaid`, `footer`). Never inline-duplicate styles per element.
When building, read [references/promptlib.md](references/promptlib.md) — the design moves that make a page *lovely*.

Write to the OS temp dir (`$TMPDIR` → `/tmp`, `%TEMP%` on Windows), filename `<slug>-<timestamp>.html`:

- **One file** — no local sibling files (`style.css`, `app.js`, images). Inline content and layout; popular packages via popular CDNs, but keep the layout inline so content renders offline. See [references/html-patterns.md](references/html-patterns.md).

Validate before delivering: `visualize validate <file.html>` (one file: local refs fail, popular CDNs ok) and `visualize lint <file.html>` (decorative AI-tells; structural color passes). On a **chart/comparison** page also `visualize chartcheck <file.html>` — bar baseline, log scale, notes left on the chart, source ([references/chart-integrity.md](references/chart-integrity.md)). Flags `--selfcheck`/`--update`.

### 3. Deliver — open it and give the URL

`visualize open <file.html>` shows it; `visualize share <file.html>` uploads to throway
and prints the URL; `visualize share --dir <dir>` publishes a browseable folder.

Always give the user the **URL** — it **expires after ~4 hours** and is **public**
(anyone with the link can read); say so for sensitive content. Keep the local file: it's
the durable copy. `--dir` uploads **recursively**; throway dirs are flat, so nested
files are flattened (`sub/f.txt` → `sub-f.txt`). Default stays one self-contained HTML.

## Design principles

- **Visual first** — diagrams and layout carry the meaning; prose is sparse. If a diagram
  needs a paragraph to be understood, redraw it.
- **Scannable** — generous whitespace, neutral ink on warm paper, clear hierarchy. Editorial, not corporate-dashboard.
- **Color is structure, not decoration** — category hues and `--ok/--warn/--bad` severity carry meaning; never pastel pills, saturated links, big colored circles (promptlib §0–2).
- **Honest about scope** — if the user named a subset, visualize exactly that.

## Install

Ships in the **skale-skills** pi package — `pi install git:github.com/devskale/skale-skills`.
For a global `visualize` command, run this skill's `./install.sh` (Linux/macOS) or
`install.bat` (Windows). Needs `curl` (for `share`); `python3` optional (grep fallbacks).

## References

- [references/routing.md](references/routing.md) — **hand off to d2/figure or build inline?**
- [references/code-forms.md](references/code-forms.md) — **smallest view first**: pseudocode, call tree, component tree, file tree, matched-shape diff, Mermaid
- [references/modules.md](references/modules.md) — the page-module catalog
- [references/patterns.md](references/patterns.md) — semantic patterns + complexity budgets
- [references/structures.md](references/structures.md) — intents → module stacks
- [references/report.md](references/report.md) — report mode
- [references/promptlib.md](references/promptlib.md) — design moves for *lovely* pages
- [references/output.md](references/output.md) — presets; [references/html-patterns.md](references/html-patterns.md) — scaffold + patterns; [references/chart-integrity.md](references/chart-integrity.md) — **charts**: what the page proves vs. what needs the data
- [references/inspirations.md](references/inspirations.md) — visual references to study