Visual explainer

Skill justinramos101/agent-skill-kit/skills/visual-explainer

Battle-tested Agent Skills for coding agents — source-grounded, failure-driven heuristics that audit and design real surfaces. Install with npx skills.

Install

npx -y skills add justinramos101/agent-skill-kit --skill visual-explainer

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Explain a complex idea by generating a visual HTML page instead of a wall of text — software architecture, data or control flow, before/after refactors, system and state-machine design, multi-step plans, tradeoff comparisons. Reach for it whenever an explanation is structural, comparative, multi-part, or spatial and a diagram beats paragraphs; also fires on explicit asks — 'explain this in HTML', 'show me a diagram', 'visualize this', 'draw the architecture'. Writes the page to a scratch path outside the repo and opens it in your browser. Do NOT use to design a product's real UI, screens, or components, or to build data charts and dashboards as the shipped deliverable — that is end-user UX and data-viz work; this is a throwaway visual explainer of an idea, not a product surface.

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

4.0 KB, as published. Nobody here has run it

Visual Explainer

Core principle: when an explanation is structural, comparative, multi-part, or spatial, render it as an HTML page instead of paragraphs — and reach for it on your own, not only when asked.

When it fires

Apply one test: would a diagram beat prose here? Yes for architecture, data or control flow, before/after refactors, system and state-machine design, multi-step plans, tradeoff comparisons. No for short, simple, or factual answers — those stay prose. An explicit ask ("explain this in HTML", "show me a diagram") always fires. Don't gate on permission: when it applies, produce the page as part of answering. The chat reply still stands; the page supplements it.

Invariants

Accurate over pretty. The diagram must mirror the real code or plan — real names, real direction — not an idealized cartoon. A wrong-but-polished diagram is worse than prose. If the structure is uncertain, inspect first.
Disposable, not a deliverable. Don't over-invest, maintain, or commit it unless the user asks to keep it.
Readable everywhere. High-contrast (WCAG) and responsive; legible in light and dark; cap line length; wide diagrams scroll in their own container.
One page, done. Generate, present, stop.

Workflow

Pick the form from what you want to show, not a box-and-arrow reflex: flow → flowchart, hierarchy → tree, states → state diagram, change → before/after side-by-side, comparison → table, quantities → the fitting chart. Not everything is a diagram — a set of peers is cards, not boxes and arrows. references/comprehension.md has the idea-type → form cheat-sheet.
Draw it with Mermaid (via CDN) — auto-layout beats hand-drawn SVG for far less effort; Tailwind (via CDN) is fine for styling. Theme the library to your page's tokens (font, colors, radius) so it blends in rather than looking raw. Hand-author SVG/CSS only for an editorial diagram Mermaid can't shape.
Deliver. Write the file to the OS temp/scratch dir ($TMPDIR / %TEMP%), never the working tree, and print the absolute path. Opening it in a browser (open / xdg-open / start) is best-effort — skip it in a headless or remote session. CDN libraries need a connected browser, not an offline or embedded-sandbox viewer.

Make it comprehensible

What decides whether the page lands (references/comprehension.md for effect sizes and the full set):

Labels on the element. Put each label and annotation on the diagram part it describes — never a separate legend or paragraph the reader must cross-reference. The single biggest win.
Signal the structure. Open with a one-glance overview; give clear headings; highlight the key path. Cue the essentials, don't gild everything.
Prune. Cut decoration and any prose that just re-narrates the diagram. One self-explanatory visual beats a visual plus redundant text.
Segment, then disclose progressively. Break into scannable sections; keep the main path clean for a newcomer and collapse derivations, edge cases, and deep detail behind "advanced" toggles, closed by default. That is how one page serves newcomer and expert.