Brilliant Visualizer

An AI agent skill that analyzes article content and automatically generates matching illustrations — diagrams, architecture charts, AI images, stock photos, and infographics.

Why

Writing a good article is half the job. The other half is finding or creating the right visuals for each section. This skill does the second half: it reads your article, identifies where illustrations would help, picks the best generation method for each, and produces them.

It works as a standalone skill or as a pipeline stage between great-writer (writing) and typeset (formatting). Compatible with any AI agent that supports skills — Claude Code, Codex, Gemini CLI, and others.

Quick Start

1. Copy the skill to your agent's skills directory:

# Claude Code
cp -r brilliant-visualizer ~/.claude/skills/

# Codex / other agents
cp -r brilliant-visualizer ~/.agents/skills/

1. Use it:

visualize path/to/article.md

1. Review the illustration plan, confirm, and let it generate.

How It Works

Two steps: Analyze → Generate.

Step 1 — Analyze. The skill scans your article and produces an illustration plan:

| # | Location | Type | Engine | Description | Priority | |---|----------|------|--------|-------------|----------| | 1 | After title | Cover | ai-image | Tech-style concept art | Required | | 2 | After §2 | Architecture | mermaid | Microservice topology | Required | | 3 | After §5 | Comparison | html-render | Performance metrics | Suggested |

You can edit, remove, or add entries before proceeding.

Step 2 — Generate. For each confirmed entry, the skill loads the right engine, generates the visual, and inserts it into your Markdown.

Engines

| Engine | What it does | Tool needed | |--------|-------------|-------------| | mermaid | Flowcharts, sequence diagrams, ER diagrams, state charts, gantt, mindmaps, pie charts | @mermaid-js/mermaid-cli (optional — inline code works without it) | | architecture | System architecture, network topology, component diagrams | d2 (preferred) or graphviz | | ai-image | Concept art, cover images, abstract illustrations | OpenAI API / local Flux2 / nanobanana | | stock-photo | Real-world scenes, people, environments | Unsplash API / Pexels API / web search | | html-render | Data comparisons, stat cards, bar charts, timelines | Any headless browser (Puppeteer, Playwright, etc.) |

Engines are loaded on demand. If you only need Mermaid diagrams, the skill never reads the AI image module.

Output

Diagrams (Mermaid) are inserted as inline code blocks by default:

```mermaid
flowchart TD
    A[Start] --> B{Check}
    B -->|Yes| C[Do X]
    B -->|No| D[Do Y]
```

Images (AI-generated, stock photos, HTML renders) are saved to ./images/ and referenced in Markdown:

![Cover image](images/cover-ai-20260328-001.png)

Stock photos include source attribution as HTML comments.

Configuration

All settings use environment variables:

# AI image backend priority (comma-separated)
VISUALIZE_AI_BACKEND=flux2,gpt-image-1,dall-e-3,nanobanana

# Local Flux2 endpoint
VISUALIZE_FLUX2_URL=http://192.168.x.x:port/api/generate

# OpenAI (for DALL-E 3 and gpt-image-1)
OPENAI_API_KEY=sk-xxx

# nanobanana
NANOBANANA_API_KEY=xxx

# Stock photo APIs (optional — falls back to web search)
UNSPLASH_ACCESS_KEY=xxx
PEXELS_API_KEY=xxx

# Image output directory (default: ./images/)
VISUALIZE_OUTPUT_DIR=./images

# Mermaid output: "inline" (default) or "render" (PNG)
VISUALIZE_MERMAID_MODE=inline

No API keys? The skill still works — Mermaid and HTML rendering need no keys, and stock photo search falls back to web search.

Integration

With great-writer: After drafting, great-writer can invoke visualize to add illustrations before the review phase.

Research → Draft → [Visualize] → Review → Humanize → Finalize

With typeset: The output Markdown (with Mermaid blocks and image references) is ready for typeset to render into platform-specific HTML.

File Structure

brilliant-visualizer/
  SKILL.md              — Main entry: workflow + routing logic
  engines/
    mermaid.md          — 7 Mermaid diagram types with templates
    architecture.md     — D2, Graphviz, Mermaid fallback
    ai-image.md         — Multi-backend routing + prompt engineering
    stock-photo.md      — Unsplash/Pexels API + web search fallback
    html-render.md      — HTML templates + screenshot via headless browser

Tool Installation

Install only what you need:

# Mermaid CLI (for rendering to PNG/SVG)
npm install -g @mermaid-js/mermaid-cli

# D2 (for architecture diagrams)
brew install d2

# Graphviz (alternative to D2)
brew install graphviz

Mermaid inline mode and HTML rendering work without installing anything.

License

MIT