visualization

visualization

A Claude Code plugin for on-demand visualization. One skill, one job: at any point in a conversation, decide what is most worth showing visually and how to show it, then render it. It is a form-and-medium router, not a craft teacher.

Skill	What it does
/visualization:visualize	Infer the target from the conversation, pick a form (mermaid diagram, table, chart, ASCII/Unicode, code-shape sketch, or a rich page) and a medium (terminal, local HTML file, or published Artifact), and render it, asking only on genuine ambiguity

What it decides

Two decisions, then the output:

• Form, matched to the shape of the content:

  Content shape	Form
  Flow, hierarchy, sequence, state, or relationships	A mermaid diagram
  Attribute comparison	A markdown table
  Quantities	A chart
  A small structural sketch	ASCII or Unicode
  Logic, a call path, a component or file tree, types, or a delta over code	A code-shape sketch (pseudocode, call tree, component tree, shallow file tree, types and signatures, diff), a fenced text form that stays in the terminal by default
  A composite or interactive view, an infographic, or a short slide deck	A rich rendered page
  A visual layout the user would rather tweak by hand	A rich rendered page, with /design (the bundled design skill's hand-editable canvas, which the person runs) offered alongside it

• Medium. One of three ascending tiers, inline terminal → local HTML file → published Artifact, chosen by the form's weight, a configurable preference, and which surfaces are actually available.

The full grounded catalog lives in the skill's context/decision-matrix.md. It covers every mermaid family, the zero-dependency chart paths, and the rendering-surface facts.

Router, not craft

This skill decides the form and medium; it does not own the craft of a good chart or the fundamentals of a good page. When a chart is the right form and a chart-craft/dataviz capability is installed, it routes the craft there; when a rich page is the right medium, the page's contract and design are owned by the Artifact tool's own contract and an artifact-design capability. Each is invoked through its capability when present and degrades to a documented fallback when absent. This skill never restates their guidance.

It is also not a comprehension aid: restating dense text in plainer words is a different concern. This skill is form-driven (render content as a visual), not comprehension-driven.

/visualization:visualize                          # infer the target, auto-decide form and medium
/visualization:visualize this as a sequence       # honor a named form
/visualization:visualize file                     # render richer forms as a local HTML file, never published
/visualization:visualize artifact                 # prefer a published Artifact when that surface is available

Surfaces and availability

A published Artifact is heavily gated (plan, sign-in, provider, version, and context constraints); when it is unavailable the skill writes a self-contained local HTML file instead, and if no page surface is available it degrades visibly to the terminal. A ```mermaid fence in the terminal is shown as source, not a rendered diagram. These facts and their sources are documented in the catalog.

Configuration

• medium (userConfig, string, default auto). Preferred delivery medium when the skill auto-selects: auto (decide by content and available surfaces), terminal (always inline), file (rich forms as a local HTML file, never published off the machine), or artifact (prefer a published Artifact when available, else a local file, else terminal). An unrecognized value is reported and treated as auto. There is no native enum type for userConfig, so the allowed values are validated in-skill.
• thin_context_prompt (userConfig, string, default auto). What the skill does when code is pasted with little conversational context and no form named: auto (ask one ranked question only when two or more code-shape forms fit about equally; render when one form dominates), always (offer the ranked menu on any bare code paste), or never (render the recommended form without asking). An unrecognized value is reported and treated as auto; validated in-skill.

Configure with /plugin configure visualization@<marketplace>, or headless with claude plugin install visualization@<marketplace> -s <scope> --config medium=<value>. Against an already-installed plugin that prints already installed and still writes the value. Never uninstall to reconfigure: that drops the whole stored pluginConfigs entry and resets every option to its manifest default. The verified-version record lives in the plugin-reconfiguration convention. No persistent state; no external prerequisites; no network calls of its own.

Options reference

Generated from this plugin's .claude-plugin/plugin.json. Every option Claude Code will prompt for when the plugin is enabled, with the environment variable each hook reads it from.

Option	Type	Default	Environment variable	Description
medium	string	"auto"	CLAUDE_PLUGIN_OPTION_MEDIUM	Preferred delivery medium when the skill auto-selects. One of: 'auto' (decide by content and available surfaces), 'terminal' (always render inline, degrading richer forms to their best terminal approximation), 'file' (render richer forms as a self-contained local HTML file, never published off the machine), 'artifact' (prefer a published Artifact when that surface is available, else fall back to a local HTML file, else terminal). An unrecognized value is reported and treated as 'auto'.
thin_context_prompt	string	"auto"	CLAUDE_PLUGIN_OPTION_THIN_CONTEXT_PROMPT	What the skill does when code is pasted with little conversational context and no form named. One of: 'auto' (ask one ranked question only when two or more code-shape forms fit about equally; render when one form dominates), 'always' (offer the ranked menu on any bare code paste), 'never' (render the recommended form without asking). An unrecognized value is reported and treated as 'auto'.

How to set these

Three supported routes, in the order most people want them:

1. Interactively. Claude Code prompts for declared options when you enable the plugin. To change them later: /plugin configure visualization@<marketplace>.

2. Headless. Repeat --config for each option. Replace <marketplace> with the marketplace you installed this plugin from:

   claude plugin install visualization@<marketplace> -s <scope> --config medium=<value>

   The same command reconfigures a plugin that is already installed: it prints already installed and still writes the value. The short-circuit message is about the install, not the config write. Do not claude plugin uninstall to reconfigure: uninstalling drops this plugin's whole stored pluginConfigs entry, resetting every option in the table above to its default. -s defaults to user, so pass the scope claude plugin list reports for this plugin. The verified-version record lives in the plugin-reconfiguration convention.

   The value is stored immediately; the session you are in does not change. Hooks are handed their CLAUDE_PLUGIN_OPTION_* when the session starts, so start a fresh Claude Code session before expecting new behavior. A check run in the old session still reports the old value, and that is not a failed write.

3. By hand, in settings. Add the value under pluginConfigs in your user settings (~/.claude/settings.json):

   {
     "pluginConfigs": {
       "visualization@<marketplace>": {
         "options": {
           "medium": <value>
         }
       }
     }
   }

   Plugin option values are read from user, --settings, and managed settings only, not from a project's .claude/settings.json. To vary behavior per repository, enable or disable the plugin in that project's enabledPlugins instead of setting an option there.

Do not set the CLAUDE_PLUGIN_OPTION_* variables yourself. They are how Claude Code hands a configured value to a hook process; the value comes from the routes above.

Upstream documentation

• User configuration: the userConfig schema and the CLAUDE_PLUGIN_OPTION_<KEY> export
• Plugin install options: the --config flag's reference entry
• Plugins and skills settings: enabledPlugins, extraKnownMarketplaces, pluginConfigs
• Settings files and who they affect: user vs project vs local precedence
• Manage installed plugins: enabling, disabling, /plugin list

Install

/plugin marketplace add melodic-software/claude-code-plugins
/plugin install visualization@<marketplace>

Possible future change

• Third-party visualization server. No credible egress-free, self-hostable visualization server exists to depend on today. Re-evaluate if one lands with a maintained security posture (a self-hosted AntV deployment is the current candidate). Until then the skill relies only on native rendering surfaces and the presence-gated craft capabilities.