SKILL DOCUMENTATION

Visual Explainer

Generate self-contained, presentation-ready HTML explainers for plans, diffs, docs, architecture, audits, and stakeholder updates.

Overview

Generate self-contained, presentation-ready HTML explainers for plans, diffs, docs, architecture, audits, and stakeholder updates.

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

Parent docs: Visual Explainer

Related wrapper commands from the parent plugin:

/visual-explainer:explain

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

HTML page instead.

verification.

only the missing items.

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.

  • If you are about to produce a table with 4+ rows or 3+ columns, generate an HTML page instead.
  • 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.
  • Required inputs are:
  • topic
  • audience
  • goal
  • source material
  • Infer them from the request and local context when safe.
  • If anything required is still missing, ask one concise follow-up covering only the missing items.
  • 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:

BashReadWriteGrepGlob

References

  • config-layout.md
  • css-patterns.md
  • error-handling.md
  • libraries.md
  • netlify-publishing.md
  • provenance.md
  • responsive-nav.md
  • slide-patterns.md
  • stakeholder-explainer.md

Scripts

  • publish_netlify_preview.py

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

Invocation:

/visual-explainer:explain