visual-explainer

What this skill does

# 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.

## Proactive Triggers

Suggest this skill when:
1. User has a document, report, or concept they want visualized as infographic pages
2. After generating a report or analysis that would benefit from a visual summary
3. User mentions creating infographics, visual explanations, or concept diagrams
4. User asks to make a document more visually appealing or presentation-ready
5. User wants to transform a whitepaper, guide, or technical document into visual content

## 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 `$GOOGLE_IMAGE_MODEL` env var, falling back to `gemini-3-pro-image-preview` (default as of 2026-03-31 — 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 threshold 0.75)
- 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)
- Recommended pass threshold: 0.75-0.85 for good quality without excessive refinement

## 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:
```python
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):**
- `GOOGLE_IMAGE_MODEL` - Override Gemini image model (default: `gemini-3-pro-image-preview`, as of 2026-03-31 — verify with provider if errors occur)

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**

```bash
# 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