Visual Explainer

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:

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:

Input Format Handling:

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:

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"
        },
        {
          "label": "Adjust settings",
          "description": "Change aspect ratio or iteration count before generating"
        }
      ]
    }
  ]
}

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:

Component costs:

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

Performance

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

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