| name | visual-explainer |
| description | Trigger when explaining complex concepts, architectures, multi-step processes, system designs, or topic analyses that benefit from visual diagrams. Also triggered explicitly by the user saying "explain visually" or invoking `/visual-explainer`. |
Visual Explainer Skill
Generate standalone HTML pages with Mermaid.js diagrams and styled visual elements, then open them in the browser.
When to activate
Use this skill for:
- Flow or sequence explanations (e.g., "how does git rebase work?")
- Architecture overviews and system designs
- Comparisons and decision trees
- Multi-step processes or pipelines
- Any request containing "explain visually", "show me a diagram", or "visualize"
Skip this skill for:
- Quick answers, code fixes, one-liners
- When the user says "briefly" or "in short"
- Simple factual questions
Output location
Save HTML files to /tmp/visual-explainer/:
mkdir -p /tmp/visual-explainer
FILE="/tmp/visual-explainer/<descriptive-name>-$(date +%s).html"
Use a short, descriptive kebab-case name (e.g., git-rebase-flow, microservice-architecture).
Mermaid diagram type selection
Choose the diagram type based on what you're explaining:
| Diagram Type | Use When |
|---|
flowchart TD or flowchart LR | Processes, pipelines, decision flows |
sequenceDiagram | API flows, request/response interactions, multi-actor communication |
stateDiagram-v2 | State machines, lifecycle transitions |
classDiagram | Data models, entity relationships |
HTML template
Every generated page must be self-contained — no external dependencies except Mermaid CDN. Use this structure:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>TOPIC_TITLE</title>
<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<style>
* { margin: 0; padding: 0; box-sizing: border-box; }
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
background: #f0f2f5;
color: #1a1a2e;
line-height: 1.6;
padding: 2rem 1rem;
}
.container { max-width: 900px; margin: 0 auto; }
h1 {
font-size: 1.8rem;
margin-bottom: 0.5rem;
color: #1a1a2e;
}
.subtitle {
color: #666;
margin-bottom: 2rem;
font-size: 1.05rem;
}
.card {
background: #fff;
border-radius: 12px;
padding: 1.5rem 2rem;
margin-bottom: 1.5rem;
box-shadow: 0 2px 8px rgba(0,0,0,0.08);
}
.card h2 {
font-size: 1.25rem;
margin-bottom: 1rem;
padding-bottom: 0.5rem;
border-left: 4px solid #4361ee;
padding-left: 0.75rem;
}
.mermaid {
display: flex;
justify-content: center;
margin: 1.5rem 0;
}
.callout {
border-radius: 8px;
padding: 1rem 1.25rem;
margin: 1rem 0;
border-left: 4px solid;
}
.callout-info { background: #e8f0fe; border-color: #4361ee; }
.callout-warn { background: #fff8e1; border-color: #f59e0b; }
.callout-tip { background: #e6f9ed; border-color: #10b981; }
.callout-critical { background: #fde8e8; border-color: #ef4444; }
.callout strong { display: block; margin-bottom: 0.25rem; }
ul, ol { padding-left: 1.5rem; margin: 0.75rem 0; }
li { margin-bottom: 0.4rem; }
code {
background: #f0f2f5;
padding: 0.15rem 0.4rem;
border-radius: 4px;
font-size: 0.9em;
}
.footer {
text-align: center;
color: #999;
font-size: 0.85rem;
margin-top: 2rem;
}
</style>
</head>
<body>
<div class="container">
<h1>TOPIC_TITLE</h1>
<p class="subtitle">BRIEF_DESCRIPTION</p>
<div class="card">
<h2>Overview</h2>
<p>OVERVIEW_TEXT</p>
<div class="mermaid">
MERMAID_DIAGRAM_CODE
</div>
</div>
<div class="card">
<h2>SECTION_TITLE</h2>
<p>SECTION_CONTENT</p>
<div class="callout callout-info">
<strong>Note</strong>
CALLOUT_TEXT
</div>
</div>
<div class="footer">Generated by visual-explainer</div>
</div>
<script>mermaid.initialize({ startOnLoad: true, theme: 'default' });</script>
</body>
</html>
Content guidelines
- Start with a high-level overview diagram, then drill into details
- Use callout boxes to highlight key takeaways:
.callout-info (blue) — background context, definitions.callout-warn (amber) — common pitfalls, gotchas.callout-tip (green) — best practices, pro tips.callout-critical (red) — dangers, breaking changes
- Keep Mermaid diagrams focused — split complex flows into multiple smaller diagrams rather than one massive one
- Write prose explanations between diagrams to narrate the flow
- Use
<code> tags for inline code references
Open in browser
After writing the HTML file, open it:
xdg-open "$FILE" 2>/dev/null &
open "$FILE"
Detect the platform:
if command -v xdg-open &>/dev/null; then
xdg-open "$FILE" 2>/dev/null &
elif command -v open &>/dev/null; then
open "$FILE"
fi
Final output
After opening the browser, tell the user:
- What was generated and the file path
- A brief plain-text summary of the key points (2-3 sentences)
- That they can find the file at the given path if they want to revisit it
