# Visualize > Decide the best visual form and medium for what is in the conversation right now, then render it. Use when asked to visualize, diagram, chart, draw, sketch, or render something, or which visual form fits it best. Infers the target from the conversation, picks a form (a mermaid diagram, a markdown table, a hand-authored SVG/CSS chart, ASCII/Unicode art, code-shape sketches, 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). - Skill: `melodic-software/visualize` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add melodic-software/visualize` - Raw SKILL.md: https://api.skillmd.com/api/skills/melodic-software/visualize/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: melodic-software (https://skillmd.com/u/melodic-software) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/melodic-software/visualize --- # 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. ## 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`](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`](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. 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. ## 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`, `/.claude/rendered-views.md`, and `/.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 `/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 ` on Windows, `open ` on macOS, `xdg-open ` 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`](context/decision-matrix.md). 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.