visualize v1.4.0B

Immutable. This exact content never changes and is served at /api/v1/blob/1dde83ee775cbb79.

---
name: visualize
version: "1.4.0"
description: "Render any set of things as ONE self-contained HTML document and give the user a URL — and generate polished HTML reports. Understands what you want (a codebase, modules, data, a plan, a comparison, an architecture, a set of items, or a structured report with findings), figures out the right structure, and builds a single portable HTML file — then opens it locally and optionally shares it to a short-lived URL via the throway store. Triggers on: visualize, make me a page, render this as HTML, show this as a diagram/page, turn this into a report, generate a report, give me a link to this, put it on a page."
---

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

Turns a request into **one portable HTML document** that renders in any browser, then
gives the user a URL. Two modes:

- **Visualize** — display a set of things (cards, tree, system map, simple diagrams).
- **Report** — generate a structured document (executive summary, sections with findings,
  recommendations). See [references/report.md](references/report.md).

The whole point is **one file**: styles, scripts, diagrams, data live inside a single
`.html` — inline, or loaded from a popular CDN (Mermaid, Tailwind, …). No local sibling
files, nothing to build, nothing to host; sharing is just the one file.

> **Related skills.** `d2` (auto-laid-out technical diagrams) and `figure` (hand-drawn
> presentation figures) are **manual-only** — invoke via `/skill:d2` / `/skill:figure`.
> `visualize` is the auto-invocable **page layer**: a page of many things, one
> self-contained HTML, shared to a URL.

## When to recommend d2 / figure (not build inline)

`visualize` builds its own simple diagrams inline (SVG arrows, optional Mermaid) — good
for a small graph embedded in a page. But some challenges are **better served by `d2`
(auto-laid-out technical diagrams) or `figure` (hand-drawn presentation figures)**. Both
are manual-only (`/skill:d2` / `/skill:figure`), so `visualize` **recommends and stops** —
don't build a weak inline version. Decide **live per request**, re-reading the `d2`/`figure`
descriptions (in the system-prompt catalog) each time:

- **→ `d2`** — complex technical graphs: sequence / ER / class diagrams; dependency or
  call graphs with many nodes and edges (elk auto-layout handles the density, inline SVG
  tangles); diagrams that must be self-verifiable (d2 renders ASCII) or are the
  deliverable (committed `.svg`/`.png`/`.pdf`), not just one element in a throwaway page.
- **→ `figure`** — hand-drawn presentation figures: sketchy Excalidraw-style explainers,
  polished figures for a slide / report / deck.
- **→ inline** — the diagram is simple (a few nodes), *one element among many*, and the
  user wants a quick shareable page. Don't bounce trivial graphs to d2/figure.

**Pattern-aware tripwire** (see [references/patterns.md](references/patterns.md)): a
pattern that is *at heart a dense technical graph* — fan-in queue, trust boundary, long
write-back loop — belongs in `d2` when the graph is the point, not one panel among many.
A pattern whose value is the *editorial sketch* — stage framework as a deck figure,
provenance trail — belongs in `figure`. If the real content exceeds the pattern's
complexity budget, that's the signal to hand it off.

**How to recommend:** end the page with one line, e.g. *"This graph is complex — for a
proper auto-laid-out diagram, run `/skill:d2`; for a hand-drawn figure, `/skill:figure`."*
Don't over-recommend.

## The shape of the job

The agent does three things, in order:

1. **Understand** — work out *what* the user wants and *which mode + structure* fits
   (visualize vs report; see [references/structures.md](references/structures.md) and
   [references/report.md](references/report.md)).
2. **Build** — write one self-contained HTML file to a temp dir (see Build below).
3. **Deliver** — `visualize open <file>` to show it, and `visualize share <file>` to get a
   URL. Give the user the URL.

## Workflow

### 1. Understand — decide the mode from the prompt, then the structure

The **mode** is decided by *what the user asked for* — report vs. visualization. Ask:

- **What is the subject?** A codebase? Modules? Data? A plan? A comparison? A set of items?
- **What is the point?** To explore, to decide, to present, to compare, to explain, to report?
- **What is the scope?** Everything, or a specific subset they named?

**Mode = report** when the deliverable is a *document* — findings, analysis, a narrative
with sections and recommendations. Prompt signals: "write me a report on X", "evaluate
Y", "summarise the audit", "assess these options", "findings + recommendations".
→ Follow [references/report.md](references/report.md).

**Mode = visualize** when the deliverable is a *display* of a set of things — a tree, a
system map, cards, a comparison. Prompt signals: "show me the repo", "compare these",
"map the platform", "visualize the data".
→ Pick a structure from [references/structures.md](references/structures.md).

A report can *embed* a visualization (a chart/map inside a section), but the mode is set
by the deliverable: a document → report; a display → visualize. Don't blur them.

**Then run the d2 / figure routing check** (*When to recommend d2 / figure* above):
complex technical diagram → recommend `/skill:d2` and stop; hand-drawn presentation
figure → recommend `/skill:figure`; otherwise build it here.

**First decide whether a semantic pattern owns the challenge.** When behaviour, state,
enforcement, or risk is load-bearing (work queues up, a boundary is crossed, a loop feeds
back, two things diverge), name the pattern first — see
[references/patterns.md](references/patterns.md) for the pattern catalogue, each with a
complexity budget and a static fallback. Pattern first, then structure.

Then pick the structure that fits (see [references/structures.md](references/structures.md)):
`overview-grid`, `cards`, `before-after`, `list`, `timeline`, `flow`, `comparison`,
`hierarchy`. Don't over-engineer — one strong structure beats a kitchen sink.

Then, when **building the page**, read [references/promptlib.md](references/promptlib.md) —
the prompt library of design moves that make a visualization *lovely* (colour-coded
grouping, editorial typography, card grids, provenance footer). It's the difference
between a fine page and one the user says is great.

### 2. Build — compose one self-contained HTML page

**Set the output target first** (see [references/output.md](references/output.md)): is this a
browser `page`, a `slide`, a `doc`/README, a `social` card, or `print`? `page` is the
default; the target changes canvas, density, and copy. Then:

**MANDATORY: read a default template first.** Before writing any HTML, `read` at least
one template from `templates/` (`cards.html`, `report.html`, `system-map.html`,
`repo-tree.html`, `mermaid.html`)
that matches the structure you chose. Start from its CSS + scaffold — do **not** hand-write
HTML/CSS from scratch. This is what keeps every page on the house style: neutral
editorial base, color only as structure (no decorative AI-generated accents). The
templates are the proven starting point; compose from them, never reinvent.

Then **compose from page modules**, don't rebuild from nothing. Read
[references/modules.md](references/modules.md) — the catalog of reusable modules
(`header`, `legend`, `card-grid`, `tree`, `flow`, `table`, `section`, `exec-summary`,
`recommendations`, `mermaid`, `footer`). Pick the modules that fit the request, stack them
inside the shared `<main>` base, and fill the placeholders. A report and a visualization
are both just different module compositions.

Write the HTML to the OS temp dir so nothing lands in the repo:

- Resolve from `$TMPDIR`, falling back to `/tmp` (or `%TEMP%` on Windows).
- Filename: `<slug>-<timestamp>.html`, e.g. `architecture-1699999999.html`.
- **One file** — no local sibling files (`style.css`, `app.js`, `img.png` next to the
  HTML). Inline content and layout with `<style>`/`<script>`; see
  [references/html-patterns.md](references/html-patterns.md) for the scaffold and patterns.
- **CDN is fine for popular packages** — Mermaid, Tailwind, chart/formula renderers via
  jsdelivr, unpkg, cdnjs, esm.sh. Tradeoff: diagrams/styling need network when the file
  is opened offline. Keep the page *layout* in inline CSS so content always renders;
  use CDNs for heavy machinery, not for your content.

Validate before delivering:

```bash
visualize validate <file.html>   # one file: local refs fail, popular CDNs ok
visualize lint <file.html>       # style taste-gate: flag AI-generated tells
visualize --selfcheck            # version, install dir, last update
visualize --update               # pull the latest skill via git
```

`validate` checks the page is **one file**: dependency references (`script`/`link`/
`img`/`iframe`, CSS `@import`/`url()`, JS imports) must be inline or point at a popular
public CDN (jsdelivr, unpkg, cdnjs, esm.sh, tailwind, Google Fonts, plot.ly). Plain
`<a href>` links are navigation, not dependencies — they don't count. Local file
references and unknown hosts exit non-zero. `lint` is the **style
taste-gate** — it flags the *decorative* AI-slop tells from promptlib §0 (saturated
accent on links/buttons, pastel pill capsules, large colored numbered circles ~20px+)
and exits non-zero if any are found. **Structural color passes** — category dots,
section accents, semantic `.ok`/`.warn`/`.bad` severity. Run both before sharing; fix
the decorative tells rather than sharing a page that screams "generated".

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

```bash
visualize open  <file.html>    # show it in the browser
visualize share <file.html>    # upload to throway → prints the URL
```

Always give the user the **URL**. Note the throway URL **expires after ~4 hours** and is
**public** (anyone with the link can read it) — say so when sharing something sensitive.
Keep the local file too: it's the durable copy.

> **Dir capability (throway).** Beyond single files, `visualize share --dir <dir>` publishes
> a whole directory as a **mutable, browseable throway folder** — HTML listing for
> browsers, JSON for agents, zip download; expires ~4h after the last add (max 24h). Use it
> when you want a *browseable folder of items*; the default stays one self-contained HTML.
> (Throway also supports multi-file bundles via raw multipart POST — read `/api` first; no
> launcher command, and verify MIME sniffing / relative-URL resolution when you depend on
> them.)

## Design principles

- **One contained HTML** — the user's explicit want. Everything inline; the file is the
  deliverable.
- **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.** The base stays neutral editorial (ink on warm
  paper, links as ink with a hairline underline). Color earns its place by *carrying
  meaning*: category hues on small elements (dots, swatches, kickers, 2px rules),
  `--ok/--warn/--bad` when severity IS the data (findings, priorities), one category
  hue on section numbers/kickers. Never decorative: pastel pill capsules, saturated
  accent links, large colored numbered circles. See promptlib.md §0–2.
- **Honest about scope** — if the user named a subset, visualize exactly that; don't pad
  with everything else.

## Install

Ships in the **skale-skills** pi package — install the repo once:

```bash
pi install git:github.com/devskale/skale-skills
```

To also get a global `visualize` shell command, run from this skill's directory:

```bash
./install.sh        # → creates ~/.local/bin/visualize (Linux/macOS)
install.bat         # Windows, same directory
```

Requires `curl` (for `share`). `python3` powers `lint`/`validate` and URL parsing but is
optional (grep fallbacks).

## References

- [references/modules.md](references/modules.md) — **the page-module catalog**: the
  reusable building blocks (header, legend, card-grid, tree, flow, table, section,
  exec-summary, recommendations, mermaid, footer) and how to compose a page from them
- [references/patterns.md](references/patterns.md) — **semantic patterns**: what the page
  *does* (fan-in queue, trust boundary, loop, divergence, …), each with a complexity
  budget + static fallback. Decide the pattern before the structure.
- [references/structures.md](references/structures.md) — high-level intents → which
  module stack fits
- [references/report.md](references/report.md) — **report mode**: a specific module
  composition (exec-summary + sections + recommendations)
- [references/promptlib.md](references/promptlib.md) — the prompt library of design moves
  for building *lovely* pages (colour grouping, editorial type, card grids, provenance)
- [references/output.md](references/output.md) — **where the page lands**: page / slide /
  doc / social / print presets, density, and getting a PNG for non-page targets
- [references/html-patterns.md](references/html-patterns.md) — the HTML scaffold, inline
  CSS patterns, and diagram techniques
- [references/inspirations.md](references/inspirations.md) — visual references worth
  studying / borrowing from (add as you find them)