Visualize

---
description: "Decide the best visual FORM and MEDIUM for what is in the conversation right now, then render it. Use when: 'visualize', 'visualize this', 'show me a diagram of this', 'diagram this', 'render this as', 'draw this', 'sketch this', 'make a picture of this', 'what is the best way to show this', 'turn this into a visual'. Infers the target from the conversation, picks a form (a mermaid diagram, a markdown table, a hand-authored SVG/CSS chart, ASCII/Unicode art, a rich rendered page, or, where the bundled design skill is available, a hand-editable design canvas) and a medium (inline terminal, a local HTML file, or a published Artifact), renders good defaults, and asks ONLY when the target is genuinely ambiguous and no form was named. It ROUTES chart craft and artifact-design fundamentals to those capabilities when installed. It does not teach them. Not for polishing a specific chart's colors/axes (a chart-craft/dataviz capability owns that) or restating dense text in plainer words (a comprehension/digest concern)."
argument-hint: "[terminal|file|artifact]. Omit to auto-decide; name a form in the request itself"
user-invocable: true
disable-model-invocation: false
metadata:
  workflow-stage: anytime
  summary: Pick the best visual form for what is in the conversation and render it
---

# Visualize

## Purpose

On demand, at any point in a conversation, decide **what** is most worth showing
visually and **how** to show it, then render it. This skill is a **form + medium
router**: it makes two decisions, the form and the medium, and produces the
output. It is not a craft teacher. The craft of a good chart, and the fundamentals
of a good rich page, are owned by other capabilities; this skill routes to them
and never restates them.

## When this fires, and when it does not

- **Fires** when the user asks to see something visually: "visualize this",
  "diagram this", "chart this", "render this as …", "show me …", or a bare
  `/visualization:visualize`.
- **Not chart craft.** Making a specific chart read well, including palette, marks,
  axes, legend, and dark-mode contrast, is a chart-craft/dataviz capability's job. This
  skill decides *that a chart is the right form* and routes the craft out.
- **Not comprehension digest.** Restating a wall of dense text in plainer words,
  or restructuring it for understanding, is a different concern. This skill is
  form-driven (render the content as a visual), not comprehension-driven.

## What you produce

Two decisions, then the rendered output:

1. **Form**. The kind of visual the content wants (Step 2).
2. **Medium**. Where it is delivered (Step 3).

## Step 1: Infer the target

Read where the conversation stands and identify the single thing most worth
showing: a process just described, a set of options compared, a trend in some
numbers, a structure being designed. Usually one target dominates. If two or more
are equally plausible and the user named no form, that is genuine ambiguity.
Carry it to Step 4. Otherwise proceed with the dominant target.

## Step 2: Pick the form

Match the *shape* of the content to a form. The full catalog lives in
[`context/decision-matrix.md`](context/decision-matrix.md): every mermaid
diagram family and when each fits, the zero-dependency chart primitives, and the
rendering-surface facts these rest on. The summary:

| Content shape | Form |
|---|---|
| Flow, process, hierarchy, sequence, state, relationships, timeline | a **mermaid diagram** (pick the family per the catalog) |
| Attributes or options compared across items | a **markdown table** |
| Quantities: trend, distribution, proportion, ranking | a **chart**. Route the craft to a chart-craft/dataviz capability |
| Small structural sketch, directory tree, box layout | **ASCII / Unicode art** |
| A composite, interactive, or large multi-part view | a **rich rendered page** |
| A visual layout the user would rather tweak by hand: a UI mockup, screen flow, poster, banner, one-pager | a **design canvas**. Route to a design-canvas capability (the bundled `design` skill), when available |

When the form is a chart and a chart-craft/dataviz capability is installed, invoke
it for the craft (form heuristic, palette, mark specs); when it is not installed,
fall back to a simple, honest default (a labelled bar/line as inline SVG on a
page, or a Unicode bar/sparkline in the terminal) and say the craft capability was
unavailable. Never restate its craft here.

When the form is a hand-tweakable visual layout, route to the design-canvas
capability. That is the bundled `design` skill, when it appears in this session's
skill list. The canvas exists only on the published-Artifact tier, so the offer is
also gated on Step 3's medium selection: when an explicit `terminal`/`file`
argument or the configured preference pins delivery on-machine ("never
published"), do not offer the canvas. The rich rendered page or local file
carries the layout instead. Where the medium permits publishing, offer it as an
explicit alternative, never a silent default: the canvas is a
published, versioned, persistent Artifact (default-private, shareable with
teammates at the user's choice; hand-editable where saving is enabled for the
account, view-plus-PNG/PDF-export otherwise), where this skill's other page paths
are throwaway or plain-static. When the skill is **absent from the list**, the
rich rendered page covers the same ground. Do not mention `/design` (that user
has no such command). When it is **listed but the invocation is refused**, suggest
the user run `/design` themselves. The canvas surface facts and their
verified-on/recheck record live in the catalog spoke. Do not restate them here.

## Step 3: Pick the medium

There are three delivery tiers, in ascending richness: **inline terminal → local
HTML file → published Artifact**. Selection layers, first hit wins:

1. **Explicit argument**. A `terminal` / `file` / `artifact` argument forces the tier.
2. **Configured preference**. `${user_config.medium}`. Claude Code text-substitutes
   the configured value into this line; if it still shows the literal
   `${user_config.medium}` token or is empty, the option is unset and the next
   rung resolves. Recognized values are `auto`, `terminal`, `file`, and
   `artifact`; any other value is reported and treated as unset.
3. **Cascade preference**. The `rendered-views` cascade surface, read only when
   rungs 1-2 are unset: anchor at the repo root (`${CLAUDE_PROJECT_DIR}` when
   set, else `git rev-parse --show-toplevel`), then read whichever of
   `~/.claude/rendered-views.md`, `<root>/.claude/rendered-views.md`, and
   `<root>/.claude/rendered-views.local.md` exist, in that order. The last
   layer that states a `medium:` value wins (per-key override), with the same
   recognized values as rung 2. Verify layer state before honoring a value,
   per the cascade contract's per-layer verdicts: a team layer that is not
   tracked is a hard stop (teammates would never receive it), an overlay that
   is staged or not gitignored is a failure to report (a personal deviation
   could reach history), and the user-global layer takes no git verdict at
   all. Name the winning layer when reporting the
   choice; on a malformed layer, say so and resolve as if that layer were
   absent. All layers absent simply falls through (per
   `docs/conventions/rendered-views/README.md` in the marketplace repository).
4. **Auto**. Decide by the form and its weight: terminal for small, static,
   text-representable output (tables, ASCII, short code, a `mermaid` source fence);
   a rich page for a composite, interactive, large, or truly graphical result
   (rendered diagrams, real charts, dashboards).

**Surface gate: the rich page is a capability that can be absent.** A published
Artifact is heavily gated (plan, sign-in, provider, and version constraints; off
in SDK / CI / MCP contexts). See the catalog. So when a page is warranted:
publish an Artifact only if that surface is available; otherwise write a
self-contained local HTML file and open it; if neither page surface is available,
degrade **visibly** to the best terminal form with a one-line notice. Never assume
the Artifact surface exists. The `file` preference deliberately stays on the
machine (never published); `artifact` prefers publishing but degrades the same way.

**Page chrome.** When authoring a rich page, take the palette, type stacks,
radii, and accessibility floor (link/focus contrast tokens, color-scheme and
reduced-motion behavior) from this plugin's bundled chrome reference,
`${CLAUDE_PLUGIN_ROOT}/reference/html-chrome.html`, rather than inventing a
look per page.

**Local-file placement.** Write the local HTML file via the platform's temp
primitive, never into the consumer's repository tree. On Unix/Linux/Git Bash,
create a private run directory and echo it in the same call,
`d=$(mktemp -d "${TMPDIR:-/tmp}/visualize-XXXXXX"); echo "$d"`, then write the
page to `<echoed dir>/visualize.html`. Echo it because shell state does not
survive between Bash calls: the directory name is random, so an unechoed path is
unrecoverable in the call that writes the file. Carry the temp root in the positional template, the one form GNU and BSD `mktemp` accept identically, since `-p`/`--tmpdir`/`-t` differ between the dialects and a bare relative template silently creates the file in the **current directory**, the consumer's repository. Keep the `XXXXXX` placeholders **trailing**. BSD `mktemp` (macOS) substitutes only trailing Xs, so an extension after them is not portable (per `docs/conventions/topic-docs/README.md` "The ephemeral tier" in the marketplace repository).
That is why the page takes a fixed name inside the generated directory rather
than a `visualize-XXXXXX.html` template, which macOS cannot create at all. On Windows,
a user-scoped temp under
`%LOCALAPPDATA%\Temp`. One file per run. The path is handed back to the user, so
do not delete it. It must still be readable when they open it. Open it for the
user (`start <path>` on Windows, `open <path>` on macOS, `xdg-open <path>` on
Linux) and report the absolute path.

A **mermaid diagram** is the sharp case: it renders natively only on a published
Artifact. A local HTML file renders it only if the page **embeds** a mermaid
renderer inline. Keep the file self-contained; never load a renderer from the
network, which breaks offline use and, for `file` or otherwise sensitive output,
would expose the page to a third party. A plain file with a bare `mermaid` block
does not render. So if no mermaid-capable surface is reachable and no trusted
renderer can be embedded, deliver the mermaid **source** fence in the terminal and
say it is unrendered. Never open a page that shows source instead of the promised
picture.

Honor a preference without overproducing: `artifact` still renders a trivial
three-row table inline, and `terminal` degrades a rich form to its best terminal
approximation with a visible note rather than dropping detail silently.

## Step 4: Ask only on genuine ambiguity

Two things can be ambiguous independently: **what** to show (the target) and
**which form**. Ask the user **one** question, with a RECOMMENDED default listed
first, when either is genuinely ambiguous:

- **Target ambiguity**. Several equally plausible things to show. Ask which, *even
  if a form was named*: naming "diagram this" fixes the *how*, not the *what*.
- **Form ambiguity**. The target is clear, no form was named, and two forms fit it
  about equally. Ask which form.

When neither is ambiguous, meaning a dominant target and a clear best form, proceed with
the matrix's pick: good defaults, no nagging. A specified form or medium is always
honored and simply removes that axis from any question.

## Step 5: Render

- **Terminal** renders GitHub-flavored markdown: tables, fenced code, blockquotes,
  ASCII/Unicode. A ` ```mermaid ` block in the terminal is shown as **source, not a
  rendered diagram**, so emit it as portable source the user can render elsewhere,
  and prefer a page when the *rendered* diagram is the point.
- **A rich page** follows the Artifact tool's own contract and, when an
  artifact-design capability is installed, its guidance. The page-contract facts
  live once in [`context/decision-matrix.md`](context/decision-matrix.md). Do not
  restate them here.
- Report what you produced and, for a page, its path or link.

## Gotchas

- **Terminal mermaid is source, not a picture.** If the user wants to *see* the
  rendered diagram and no page surface is available, say so. Do not imply the
  fence renders inline.
- **Do not overproduce a page.** A three-row comparison is a table; forcing it into
  an Artifact is worse, not richer. Match richness to the content.
- **The Artifact surface is often unavailable.** Gate on it; never let a missing
  surface become a silent failure. Degrade visibly to a local file or terminal.
- **Craft is not this skill's job.** If you find yourself writing palette or axis
  guidance, stop and route to the chart-craft capability instead.
- **A newer mermaid family may not render** in the bundled artifact renderer
  (the 13 stable families are safe; the newest set is unverified. See the
  catalog). Prefer a stable family, or verify before relying on a new one.

## Boundary

An **interactive parameter explorer whose output returns as a prompt** (controls
beside a live preview with a copy-out prompt, the "playground" shape) is not a form
this skill renders. When the first-party `playground` plugin is installed, route the
request to its `playground` skill, or to the `playgrounds` wrapper's `/playgrounds:use`
when that wrapper is installed, which also owns the install uplift and cloud delivery
guidance. When neither is installed, say the capability exists as an installable
plugin and continue with this skill's closest static form (a rich page without the
round-trip controls), never a hand-built imitation of the explorer.

## What this skill does NOT do

- **Does not teach chart craft**. Palette, axes, marks route to a chart-craft/dataviz capability.
- **Does not teach artifact-design fundamentals**. Those route to an artifact-design capability and the Artifact tool's contract.
- **Does not restate rendering-surface facts**. They live once in the catalog spoke.
- **Does not digest or re-explain dense text**. That is a comprehension concern, not a form concern.
- **Does not publish an Artifact when that surface is absent or when the preference is `file`**. It degrades to a local file or terminal.