Visual Explainer

Overview

Create a self-contained HTML visual explainer or requested slide deck from verified source material.

This skill ships inside the Visual Explainer plugin and can be installed through the Claude Code marketplace or directly in Codex from its skill path.

Parent Surface

Prerequisites

secrets.

not read ~/.zshrc or other shell startup files directly.

missing.

• Local HTML generation needs no extra setup.
• Publish mode is opt-in and requires environment variables, not hardcoded secrets.
• The publish helper reads secrets from the current runtime environment. It does not read ~/.zshrc or other shell startup files directly.
• Store only env-var names in ~/.config/visual-explainer/global.json.
• Create ~/.agent/diagrams/ and ~/.config/visual-explainer/ if they are missing.
• When publish mode is requested, read:
• references/netlify-publishing.md
• references/config-layout.md
• references/error-handling.md

Core Rules

answer contains a table. Respect explicit Markdown or other format requests.

verification.

artifact; do not ask for an audience already covered by the default.

or committed JSON.

NETLIFY_VISUAL_EXPLAINER_TOKEN, never the token itself.

filename.

~/Downloads/.

written and return the deploy URL as well.

--publish.

the current process before running the publish helper.

the current tool session or retry from a shell session that actually inherited those exports.

error.

• Use HTML for the requested visual artifact, not merely because a normal answer contains a table. Respect explicit Markdown or other format requests.
• Prefer real diagrams, structured cards, or semantic tables over dense text.
• Read the actual source material first.
• Validate the current state before making claims.
• Separate what is confirmed, what is inferred, and what still needs verification.
• Derive topic, goal, and source material from the request and local context.
• Use the mixed-audience default unless the request indicates otherwise.
• Ask one concise follow-up only if missing facts materially change the artifact; do not ask for an audience already covered by the default.
• Default: plain language, smart-but-busy audience, low jargon.
• Do not sound like an engineering memo unless the user asks for that.
• Avoid file paths, code references, and test commands in stakeholder mode.
• Use direct current-state wording only when the evidence supports it.
• Never store literal Netlify tokens in repo files, prompt files, receipts, or committed JSON.
• Resolve real secret values from environment variables at runtime only.
• Config files may store env-var names such as NETLIFY_VISUAL_EXPLAINER_TOKEN, never the token itself.
• Always write the final HTML to ~/.agent/diagrams/ with a descriptive filename.
• Attempt to open the local HTML in the browser.
• Tell the user the local file path.
• If useful or explicitly requested, also write a Markdown summary to ~/Downloads/.
• If publish mode is explicitly requested, publish the local HTML after it is written and return the deploy URL as well.
• Publish only when the user explicitly asks to publish or the wrapper passes --publish.
• Use a fresh Netlify preview site for every publish. Do not reuse sites.
• Verify the required NETLIFY_VISUAL_EXPLAINER_* variables are available in the current process before running the publish helper.
• If the user just added or changed shell exports, tell them to restart the current tool session or retry from a shell session that actually inherited those exports.
• If publishing fails, preserve the local HTML and report the actionable error.

Intake Protocol

Follow this order:

structural decisions.

• topic
• audience
• goal
• source material
• non-technical vs technical
• include Markdown summary
• include reply draft
• slide deck instead of scrollable page
• publish the explainer
• open the deployed URL after publish

Verification Model

Before writing HTML, build a compact fact sheet for yourself:

Use that split in the page whenever it helps the reader trust the document.

If the request depends on unstable external facts and browsing is available, verify them before presenting them as current.

• confirmed facts
• reasonable inferences
• items still needing external verification

Resources

Declared allowed tools:

Installation

Switch between Claude Code and Codex, then copy the install command for the runtime you use.

claude plugin marketplace add DiversioTeam/agent-skills-marketplace
claude plugin install visual-explainer@diversiotech

CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
python3 "$CODEX_HOME/skills/.system/skill-installer/scripts/install-skill-from-github.py" \
  --repo DiversioTeam/agent-skills-marketplace \
  --path plugins/visual-explainer/skills/visual-explainer

Invocation:

/visual-explainer:explain

name: visual-explainer