visual-explainer

Generate dark-themed visual HTML explanation reports with diagrams from JSON specs.

Updated Apr 14, 2026
One-click install
npx skills add https://github.com/amitkarpe/agent-skills --skill visual-explainer-amitkarpe
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: visual-explainer
Source: https://github.com/amitkarpe/agent-skills/tree/main/skills/visual-explainer
Command: npx skills add https://github.com/amitkarpe/agent-skills --skill visual-explainer-amitkarpe

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) and assets (resource) components.

What problem does it solve? Explaining architectures, workflows, and deployment plans through text alone is slow and error-prone; this Skill produces self-contained, dark-themed visual HTML reports with diagrams, cards, and evidence tables that make technical ideas understandable at a glance. ## Core Features & Use Cases - Deterministic JSON-spec rendering: Write a small report.spec.json using an approved component catalog (Hero, FlowDiagram, ArchitectureMap, DecisionGuide, RiskRadar, EvidenceTable, Checklist), then validate and render it to offline HTML with Python scripts. - Midnight Visual dark design: Enforced dark-only theme with readability gates, no external CDN assets, no white backgrounds, and built-in secret/account-ID masking for AWS content. - Publishing pipeline: Validate HTML for offline safety and credential leaks, then publish to a local LAN surface with URL verification and 30-day archival lifecycle. - Use Case: When asked to "explain visually" how an AMI promotion flow works across DEV and PROD accounts, generate a spec with lanes, nodes, risks, and a decision guide, render it, and publish a shareable local URL. ## Quick Start Ask the AI to create a visual explainer report of your architecture or workflow as a JSON spec, then render and publish it with the included scripts.

Frequently Asked Questions about visual-explainer

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a visual architecture diagram report as HTML?▼

Write a report.spec.json using components like ArchitectureMap, FlowDiagram, and Hero from the component catalog, then run validate_spec.py and render_html_from_spec.py to produce a self-contained dark-themed HTML page. Publish it with publish_html.py for a local LAN URL.

What is the JSON spec workflow for generating HTML reports?▼

Create report.spec.json with a root Page element and child components, validate it with validate_spec.py against component-catalog.json, render with render_html_from_spec.py, then check the output with validate_html.py. Handwritten HTML is only a fallback when the catalog cannot express the page.

Can the generated HTML reports use CDN assets or Mermaid diagrams?▼

No, reports must be fully self-contained and offline. External URLs, CDN Mermaid, remote fonts, and external images are blocked by the HTML validator; use inline SVG or CSS diagrams, with Mermaid only if vendored locally.

When should I use visual-explainer instead of a simpler HTML report?▼

Use it when the user needs understanding through diagrams, concept-to-resource mapping, or AWS relationship visuals. For fast operational summaries or plain table-based reports, use the lighter web-html-page skill; for durable multi-page learning dashboards, use deep-work.

How are AWS account IDs and secrets handled in reports?▼

The validators block credential-like strings, AWS access key patterns, and 12-digit account IDs by default. Unavailable resource identifiers must be marked as "unknown / needs refresh" rather than invented, and account IDs require an explicit allow flag.