visual-explainer

name	visual-explainer
description	Transform text or documents into AI-generated infographic pages that explain concepts visually, using Gemini Pro 3 for generation and Claude Vision for quality evaluation. Generation is paid and billed per image, so it runs only when invoked explicitly.
effort	high
allowed-tools	Read, Write, Bash(python:*), Bash(pip:*), WebSearch, WebFetch, AskUserQuestion
disable-model-invocation	true

Visual Concept Explainer

You are orchestrating a visual concept explanation workflow that transforms text or documents into AI-generated infographic pages. The tool uses Gemini Pro 3 (via google-genai SDK) for 4K image generation and Claude Sonnet Vision for quality evaluation with iterative refinement.

Infographic Mode (Recommended)

The --infographic flag enables information-dense infographic generation optimized for 11x17 inch printing at 4K resolution. This mode:

• Adaptive page count (1-6 pages) based on document complexity, word count, and content types
• Zone-based layouts with explicit text placement, typography specifications, and content zones
• 8 page types: Hero Summary, Problem Landscape, Framework Overview, Framework Deep-Dive, Comparison Matrix, Dimensions/Variations, Reference/Action, Data/Evidence
• Information density: Each page can hold 800-2000 words of readable text plus diagrams, tables, and charts

Page Type Selection

The system automatically selects appropriate page types based on content:

Content Pattern	Page Type	Purpose
Executive summary needed	Hero Summary	One-page overview with key stats
Challenges, pain points	Problem Landscape	Issues visualization with severity
Multi-step processes	Framework Overview	Visual framework with connections
Deep component analysis	Framework Deep-Dive	Detailed component exploration
Multiple options to compare	Comparison Matrix	Side-by-side analysis table
Variations, types, categories	Dimensions/Variations	Category breakdown visualization
Statistics, research data	Data/Evidence	Charts and data visualization
Action items, checklists	Reference/Action	Actionable takeaways and guides

Technical Notes

Image Generation:

• Uses google-genai SDK with model from $VISUAL_EXPLAINER_GEMINI_MODEL env var, falling back to gemini-3-pro-image-preview (verify with provider if errors occur)
• Configuration: response_modalities=["IMAGE"] with ImageConfig for aspect ratio/size
• 4K images are approximately 6-7.5MB each (JPEG format)

Image Evaluation:

• Claude Vision API has 5MB limit for base64-encoded images
• Tool automatically resizes images >3.5MB before evaluation (accounts for base64 overhead)
• Uses PIL/Pillow for high-quality LANCZOS resampling

Platform Compatibility:

• Windows: Folder names are sanitized to remove invalid characters (:, *, ?, ", <, >, |)
• All platforms: Full Unicode support in Rich terminal UI

Tested Results (4 documents, 17 images):

• Formats tested: URL (Substack), Markdown, DOCX
• Average scores: 0.76-0.88 (all passing with default threshold 0.85)
• Generation time: 5-10 minutes per document (~2 min/image including analysis)
• Only 1 retry needed across 17 images (image scored 0.72 → refined to 0.82)
• Default pass threshold: 0.85 provides good quality without excessive refinement; override via --pass-threshold

Input Validation

Required Arguments:

• Input content (one of the following):
  • Raw text (pasted directly)
  • Document path (.md, .txt, .docx, .pdf)
  • URL (to fetch and extract content)

Optional Arguments:

Parameter	Default	Options	Description
--infographic	false	flag	Recommended. Generate information-dense infographic pages (11x17 format)
--max-iterations	5	1-10	Max refinement attempts per image
--aspect-ratio	16:9	16:9, 1:1, 4:3, 9:16, 3:4	Image aspect ratio
--resolution	high	low, medium, high	Image quality (high=4K/3200x1800)
--style	professional-clean	professional-clean, professional-sketch, or path	Visual style
--output-dir	./output	path	Output directory
--pass-threshold	0.85	0.0-1.0	Score required to pass evaluation
--concurrency	3	1-10	Max concurrent image generations
--no-cache	false	flag	Force fresh concept analysis
--resume	null	path	Resume from checkpoint file
--dry-run	false	flag	Show plan without generating
--setup-keys	false	flag	Force re-check of API key availability (use /unlock to load keys)
--json	false	flag	Output results as JSON (for programmatic use). Returns structured metadata including image paths, scores, concept mappings, and generation statistics. Useful for downstream automation or integration with other tools.

Input Format Handling:

Format	Handling
.md, .txt	Direct text extraction
.docx	Requires python-docx - extracts paragraphs preserving headings
.pdf	Requires PyPDF2 - extracts text content
URL	Requires beautifulsoup4 - fetches and extracts main content
Web content	Best practice: Save as markdown first for reproducibility and future reference

DOCX Conversion Tip: For best results with DOCX files, pre-convert to markdown:

from docx import Document
doc = Document('document.docx')
with open('document.md', 'w') as f:
    for para in doc.paragraphs:
        style = para.style.name if para.style else ''
        if style.startswith('Heading'):
            level = int(style[-1]) if style[-1].isdigit() else 1
            f.write('#' * level + ' ' + para.text + '\n\n')
        else:
            f.write(para.text + '\n\n')

Environment Requirements (Secrets Policy): API keys must be loaded into the environment before use. The primary method is the /unlock skill, which loads secrets from Bitwarden Secrets Manager via the bws CLI (see CLAUDE.md Secrets Management Policy):

• GOOGLE_API_KEY - For Gemini Pro 3 image generation
• ANTHROPIC_API_KEY - For Claude concept analysis and image evaluation

Optional Model Configuration (non-sensitive, safe for .env):

• VISUAL_EXPLAINER_GEMINI_MODEL - Override Gemini image model (default: gemini-3-pro-image-preview — verify with provider if errors occur)
• VISUAL_EXPLAINER_CLAUDE_MODEL - Override the Claude model for all four Claude consumers — concept analysis, prompt generation, image evaluation, and prompt refinement (default: claude-sonnet-5)
• VISUAL_EXPLAINER_CLAUDE_LOOP_MODEL - Optional override for the two in-loop consumers only — image evaluation and prompt refinement, which run once per generation attempt rather than once per run (default: unset, meaning fall back to VISUAL_EXPLAINER_CLAUDE_MODEL)

If keys are not in the environment, suggest running /unlock before proceeding. Secrets policy compliance:

• Do NOT write API keys to .env files or any configuration files
• Do NOT guide users through creating .env files with API key values
• Do NOT hardcode API keys in commands or scripts
• Always direct users to /unlock or the Bitwarden Secrets Manager workflow

Tool vs Claude Responsibilities

Understanding what the Python tool handles vs what you (Claude) must do:

Component	Responsibility	What It Does
visual-explainer (Python tool)	Core pipeline	Concept analysis, prompt generation, Gemini API calls, evaluation, refinement loop, output organization
You (Claude)	Input collection	Gather input text/path/URL from user
You (Claude)	Interactive confirmation	Style selection, image count confirmation
You (Claude)	Progress display	Show generation progress to user
You (Claude)	Results presentation	Display completion summary

Workflow

Phase 1: Setup and Dependency Check

The tool is bundled at ../tools/visual-explainer/ relative to this skill file.

Step 1: Set Up Tool Path

# Determine the plugin directory
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-/path/to/plugins/personal-plugin}"
TOOL_SRC="$PLUGIN_DIR/tools/visual-explainer/src"

Step 2: Check Dependencies

The tool automatically checks dependencies when run. You can also do a dry-run to verify setup:

PYTHONPATH="$TOOL_SRC" python -m visual_explainer --dry-run --input "test content"

Required packages:

• Core: google-genai, anthropic, httpx, python-dotenv, pydantic, aiofiles, rich, pillow
• Optional (format-specific): python-docx (DOCX), PyPDF2 (PDF), beautifulsoup4 (URLs)

If packages are missing, install them:

pip install google-genai anthropic httpx python-dotenv pydantic aiofiles rich pillow
pip install python-docx PyPDF2 beautifulsoup4  # Optional, for specific formats

Phase 2: API Key Setup (if needed)

If API keys are missing:

API Key Setup Required
======================

This tool requires two API keys:
- GOOGLE_API_KEY - for Gemini Pro 3 image generation
- ANTHROPIC_API_KEY - for Claude concept analysis and image evaluation

Missing keys detected:
  - GOOGLE_API_KEY - not found
  - ANTHROPIC_API_KEY - not found

To load API keys from Bitwarden, run: /unlock
This loads secrets from Bitwarden Secrets Manager into the current environment.

See CLAUDE.md Secrets Management Policy for details on storing and retrieving secrets.

If keys are still missing after /unlock, ask the user to verify the secrets are stored in their Bitwarden vault. Do NOT offer to write keys to .env files or guide users through creating .env files with API keys.

Phase 3: Input Collection

If no input was provided in arguments, prompt:

I'll help you create visual explanations for your content.

Please provide your input in one of these formats:
1. Paste text directly
2. Provide a file path (e.g., ./docs/concept.md)
3. Provide a URL to fetch content from

Phase 4: Content Analysis

After receiving input, run concept analysis:

PYTHONPATH="$TOOL_SRC" python -m visual_explainer analyze \
  --input "<input_text_or_path>" \
  --output-json

Display the analysis summary. Sample output: see plugins/personal-plugin/skills/visual-explainer/references/output-samples.md ("Phase 4: Content Analysis Summary").

Phase 5: Style Selection (Interactive)

Ask with AskUserQuestion:

{
  "questions": [
    {
      "question": "Which visual style should the images use?",
      "header": "Style",
      "multiSelect": false,
      "options": [
        {
          "label": "Professional Clean (Recommended)",
          "description": "Clean, corporate-ready with warm accents. Best for business, presentations, reports"
        },
        {
          "label": "Professional Sketch",
          "description": "Hand-drawn sketch aesthetic. Best for creative, educational, informal material"
        },
        {
          "label": "Custom style JSON",
          "description": "You supply a path to your own style JSON; the skill asks for it next"
        }
      ]
    
  

The old 4. Skip (use Professional Clean default) slot is the native Skip control — treat a skipped question as Professional Clean. If the user picks Custom style JSON, ask for the path in the following turn; a path typed straight into the Other box is accepted as the custom style too.

Phase 6: Image Count Confirmation

Image Generation Plan
=====================
Based on analysis, I recommend 3 images:

Image 1: "The Classical Foundation"
  - Covers: Classical Physics Background
  - Intent: Establish baseline understanding

Image 2: "Quantum Superposition"
  - Covers: Superposition, probability states
  - Intent: Introduce quantum concepts

Image 3: "Entanglement Synthesis"
  - Covers: Entanglement, applications, future
  - Intent: Tie concepts together

Display the plan above as text, then confirm with AskUserQuestion:

{
  "questions": [
    {
      "question": "Proceed with this image generation plan?",
      "header": "Image plan",
      "multiSelect": false,
      "options": [
        {
          "label": "Proceed with 3 images (Recommended)",
          "description": "Generate exactly the plan shown above"
        },
        {
          "label": "Use fewer images",
          "description": "Condense the concepts into a smaller set and re-present the plan"
        },
        {
          "label": "Use more images",
          "description": "Expand detail into additional images and re-present the plan"
        },
        {
           
           
        
      
    
  

Phase 7: Generation Execution

Execute the full generation pipeline:

PYTHONPATH="$TOOL_SRC" python -m visual_explainer generate \
  --input "<input_text_or_path>" \
  --style "<selected_style>" \
  --max-iterations <n> \
  --aspect-ratio "<ratio>" \
  --resolution "<level>" \
  --output-dir "<output_path>" \
  --pass-threshold <threshold> \
  --concurrency <n>

Progress Display Format: see plugins/personal-plugin/skills/visual-explainer/references/output-samples.md ("Phase 7: Progress Display Format") for a sample of this display.

Phase 8: Completion Summary

Sample output: see plugins/personal-plugin/skills/visual-explainer/references/output-samples.md ("Phase 8: Completion Summary").

Resume from Checkpoint

If generation was interrupted, resume with:

PYTHONPATH="$TOOL_SRC" python -m visual_explainer generate \
  --resume "./output/visual-explainer-[topic]-[timestamp]/checkpoint.json"

The checkpoint contains:

• Generation state
• Completed images
• Current progress
• Configuration used

Cost Estimation

Estimated costs per session:

Scenario	Images	Avg Attempts	Est. Total
Simple doc, 1 image	1	2	~$0.28
Medium doc, 3 images	3	2.3	~$0.95
Complex doc, 5 images	5	3	~$2.10

Component costs:

• Gemini image generation: ~$0.10 per image
• Claude concept analysis: ~$0.02 per document
• Claude image evaluation: ~$0.03 per evaluation

Performance

Scenario	Images	Expected Duration	Estimated API Cost
Simple document, 1 image	1	2-4 minutes	~$0.28
Medium document, 3 images	3	5-10 minutes	~$0.95
Complex document, 5 images	5	12-20 minutes	~$2.10
Infographic mode, 3 pages	3	8-15 minutes	~$1.20
Infographic mode, 6 pages	6	15-30 minutes	~$2.80

Duration scales linearly with image count. Each image takes approximately 2 minutes including Gemini generation, Claude evaluation, and potential refinement. Refinement retries (when score < pass threshold) add ~1.5 minutes per retry.

API cost breakdown per image: Gemini Pro 3 generation ~$0.10, Claude concept analysis ~$0.02/document (one-time), Claude image evaluation ~$0.03/evaluation. Costs increase with refinement retries. At default settings (max 5 iterations, 0.85 threshold), typical cost is $0.15-0.25 per final image. Use --dry-run to preview the generation plan without incurring any API costs.

Error Handling

Error	Response
Missing API key	Suggest running /unlock to load keys from Bitwarden
Rate limit (429)	Exponential backoff, respect Retry-After header
Safety filter	Log, skip to next attempt with modified prompt
Timeout	Retry with increased timeout (up to 5 min)
All attempts exhausted	Select best attempt, report scores
Network error	Retry up to 3 times with backoff

Examples

Infographic mode (recommended for complex documents):

/visual-explainer --input docs/architecture-overview.md --infographic

Infographic with dry-run preview:

/visual-explainer --input whitepaper.md --infographic --dry-run

Basic usage (interactive):

/visual-explainer

With document path:

/visual-explainer --input docs/architecture-overview.md

Custom settings:

/visual-explainer --input concept.txt --style professional-sketch --max-iterations 3 --aspect-ratio 1:1

High quality infographic:

/visual-explainer --input whitepaper.md --infographic --resolution high --max-iterations 7 --pass-threshold 0.90

Dry run (plan only):

/visual-explainer --input document.md --dry-run

Resume interrupted generation:

/visual-explainer --resume ./output/visual-explainer-topic-20260118/checkpoint.json

Execution Summary

Follow these steps in order:

1. Setup - Parse arguments, set up tool path
2. Dependency Check - Verify packages and API keys
3. API Key Setup - If missing, guide user through setup wizard
4. Input Collection - Get text/path/URL from user (if not provided)
5. Content Analysis - Extract concepts, determine image count
6. Style Selection - Let user choose or use default
7. Image Count Confirmation - Confirm plan with user
8. Generation Execution - Run full pipeline with progress display
9. Completion Summary - Display results and output locations