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. Read the chat history first: the thing just discussed, pasted, or changed is usually the target, and a shape already shown earlier in the conversation is usually what a follow-up question is about.

Step 2: Pick the form

Match the shape of the content to a form. The full catalog lives in 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, box layout, a directory tree as structure	ASCII / Unicode art
Logic described in prose, or an algorithm before it is written	pseudocode (a code-shape sketch)
A call path through named functions: orchestration, control flow, a backend-shaped problem	a call tree (a code-shape sketch)
A UI's component tree, with the state hooks and module boundaries that matter	a component tree with file paths (a code-shape sketch)
Where things live, or the scope of a refactor	a shallow file tree, one line of responsibility per entry (a code-shape sketch)
The shape of code before any of it exists	types and signatures (a code-shape sketch)
What changes, when the surrounding shape is already in the conversation	a diff-shaped delta over any of the shapes above (a code-shape sketch)
Mostly new code, or a copyable target shape, when no sketch is smaller than the code	the whole block, the fallback among the code-shape sketches
A composite, interactive, or large multi-part view; an infographic; a short slide deck	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

Code-shape sketches are fenced text: they render in any GFM surface and need no page. Tie-break against the mermaid row: when the content is code (named functions, files, components, types), prefer a code-shape row; when it is a process, sequence, or state in the domain, prefer a mermaid family. Pseudocode never paraphrases pasted code when a structural form answers the question. Pick the smallest view that makes the key point clear, place it beside the short text it supports, keep only the calls, files, props, states, and boundaries the question needs, and use one form, sometimes several, rarely all. One example per form lives in context/code-shapes.md; its paths and identifiers are placeholders.

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.

Code-shape sketches take this same ladder (under auto they stay in the terminal, per rung 4; file, artifact, and the configured preference are honored for them as for any form), with one exception: a pull-request diff, fetched content, or another repository's files are never rendered to HTML until the rendered-views escape helper ships. That exception overrides rung 1 and the preference; when a page was asked for, say in one line why it was not produced.

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. The common case is pasted code with little conversational context: when two or more code-shape forms fit it about equally, ask one question listing those two to four forms, the recommended one first, and render nothing until the answer. When one form clearly dominates (a comparison is a table, a series is a chart, a where-does-this-live question is a file tree), render it without asking.

The pasted-code case honors ${user_config.thin_context_prompt}. Claude Code text-substitutes the configured value into this line; if it still shows the literal ${user_config.thin_context_prompt} token or is empty, the option is unset and auto applies. auto is the behavior above; always offers the ranked menu on any bare code paste; never renders the recommended form without asking. Any other value is reported and treated as auto.

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 honored and simply removes that axis from any question, with one carve-out: Step 3's terminal-only exception for a pull-request diff, fetched content, or another repository's files overrides a requested file or artifact medium. Never interrogate form by form; one question, then render.

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. Do not restate them here. When the subject is a product UI, match that product's own colors, type, spacing, and components rather than the plugin chrome; use real labels and data; support desktop and mobile.
• 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 render a pull-request diff, fetched content, or another repository's files to HTML until the rendered-views escape helper ships. Those stay terminal fences.
• Does not publish an Artifact when that surface is absent or when the preference is file. It degrades to a local file or terminal.