zhanglt/document-illustrator

Document Illustrator Skill

An AI-powered document illustration generation tool. No specific format required—it automatically understands content and generates professional illustrations.

🎯 Core Features

• ✨ AI-Powered Summarization: Automatically understands document content and intelligently extracts core themes
• 🎨 Format Agnostic: Supports any document format (Markdown, plain text, PDF, etc.)
• 📐 Flexible Aspect Ratios: Supports 16:9 (landscape) and 3:4 (portrait)
• 🖼️ Optional Cover Image: Can generate a cover image that summarizes the entire document
• 🎭 Three Styles: Gradient glass cards, ticket style, vector illustration

🚀 How to Use

Tell Codex Directly

Generate illustrations for this document: /path/to/document.md

Or:

I want to generate some illustrations for this article

📝 Complete Workflow

Step 1: Codex Reads and Understands the Document

When you request illustrations, Codex will:

1. Use the Read tool to read the entire document
2. AI analyzes and understands the document content and structure
3. Identify core themes and key points

No need to worry about document format:

• ✅ Standard Markdown (##, ###)
• ✅ Separator format (======, ------)
• ✅ Plain text paragraphs
• ✅ Any other format

Step 2: Configuration Options (3 Questions)

Codex will ask for your preferences:

Question 1: Aspect Ratio

Please choose the aspect ratio:
1. 16:9 (landscape) - suitable for presentations, slides, horizontal display
2. 3:4 (portrait) - suitable for social media, mobile viewing, posters

Please select (1/2):

Question 2: Cover Image

Generate a cover image?
The cover image will summarize all core information of the document, serving as a guide for the series of illustrations.

1. Yes - Generate cover image + content illustrations
2. No - Only generate content illustrations

Please select (1/2):

Question 3: Number of Content Illustrations

How many content illustrations would you like?
Recommended range: 3-10
Based on the document content, I recommend generating 6

Please enter a number:

Step 3: Codex Summarizes Content and Shows It

Based on your specified number, Codex will intelligently summarize the document, then show it to you for confirmation:

📋 Content Summary Complete

📄 Cover Image Content: (if selected)
"AI Programming Tool Concept Evolution: From Rules to Skills"
- Core Concept: Static Context vs Dynamic Context
- Evolution Path: Rules → Commands → MCP → Modes → Skills
- Best Practices: Simplify to Two Core Tools

📚 Content Illustrations (6 total):

1. The Birth and Evolution of Rules
   Includes: Early model hallucination issues, role of rules files, static context

2. Commands and Workflow Packaging
   Includes: Emergence of fixed workflows, slash commands, team sharing

3. MCP Servers Bring Dynamic Capabilities
   Includes: Third-party tool integration, OAuth authentication, context bloat issues

4. The Arrival of Modes and Subagents
   Includes: Persona prompts, system prompt modifications, reliability design, Hooks determinism

5. Skills Unify Dynamic Context
   Includes: Skills concept, dynamic loading, programming tool optimization

6. Best Practices and Future Outlook
   Includes: Rules usage tips, Skills exploration, summary of core principles

✓ All content covered, no omissions

Confirm and start generating illustrations? (Y/N)

Key Guarantees:

• ✅ Complete Content: All important information will be included in some image
• ✅ Clear Logic: Segmented according to the natural logic of the content
• ✅ User Control: Show summarization results, wait for user confirmation

Step 4: Generate Illustrations

After confirmation, Codex calls a Python script to generate images:

🖼️  Starting to generate illustrations...

Generating cover image...
  ✓ Saved: /path/to/document/images/cover.png

Generating image 1/6...
  Title: The Birth and Evolution of Rules
  ✓ Saved: /path/to/document/images/illustration-01.png

Generating image 2/6...
  Title: Commands and Workflow Packaging
  ✓ Saved: /path/to/document/images/illustration-02.png

...

✨ Complete! Generated 7 illustrations (1 cover + 6 content)

Step 5: Output Results

Output location: images/ folder in the document's directory

/path/to/your/document/
└── images/
    ├── cover.png              # Cover image (if selected)
    ├── illustration-01.png    # Content illustration 1
    ├── illustration-02.png    # Content illustration 2
    ├── illustration-03.png
    ├── illustration-04.png
    ├── illustration-05.png
    └── illustration-06.png

🎨 Three Style Details

1. Gradient Glass Card Style (gradient-glass)

Features:

• Apple Keynote-style minimalism
• Glassmorphism design
• Deep void black or pure ceramic white base
• Flowing aurora gradients
• 3D glass objects and glow effects

Use Cases:

• Tech product introductions
• Data analysis reports
• Future trend outlook
• Product feature demos

2. Ticket Style (ticket)

Features:

• Digital minimalist ticket design
• High-contrast black and white palette
• Structure similar to boarding passes or tickets
• Precise geometric partitions
• Mixed Chinese-English layout, multi-directional text

Use Cases:

• Infographics
• Statistical data display
• Timelines and flowcharts
• Key point summaries

3. Vector Illustration Style (vector-illustration)

Features:

• Flat vector illustrations
• Uniform black outline strokes
• Vintage soft color palette
• Geometric treatment
• Horizontal panoramic composition

Use Cases:

• Storytelling
• Concept explanations
• Educational content
• Brand promotion

💡 Usage Examples

Example 1: Full Workflow

User: Generate illustrations for ~/blog/ai-tools.md in ticket style

Codex: OK, let me read the document first...
       [Reads document, analyzes content]

       Detected document length ~3000 words, content about AI tool evolution.

       Please choose aspect ratio:
       1. 16:9 (landscape)
       2. 3:4 (portrait)

User: 1

Codex: Generate a cover image?
       1. Yes
       2. No

User: Yes

Codex: How many content illustrations?
       Recommended range: 3-10
       Based on document content, I recommend 5

User: 5

Codex: [Shows 5 summarized topics]
       Confirm and start generating?

User: Y

Codex: [Calls Python script to generate 6 images]
       ✨ Complete! Illustrations saved to ~/blog/images/

Example 2: Plain Text Document

User: Generate illustrations for this plain text note

Codex: [Reads the note, understands content even without any headings]
       [Intelligently identifies 3 core themes]
       [Asks for configuration, shows summary, generates illustrations]

Example 3: Custom Number

User: I want 8 images, portrait orientation, no cover

Codex: OK, 16:9 portrait, no cover, 8 content illustrations.
       [Summarizes document into 8 topics]
       [Shows summary, generates after user confirmation]

🔧 Technical Details

Image Specifications

The following aspect ratios and resolutions apply to Gemini; Nebula image2-4k only supports 16:9, 3840x2160. When the user selects Nebula, use 4K directly; if the user requests 2K or portrait, first explain the limitation and confirm a supported option.

Aspect Ratio	Resolution	Use Case
16:9	2560x1440 (2K)	Presentations, horizontal display
3:4	1920x2560	Social media, portrait viewing

Optional 4K resolutions:

• 16:9 → 3840x2160
• 3:4 → 2880x3840

API Calls

• Gemini model: gemini-3-pro-image-preview (script default)
• Nebula model: gpt-image-2-4k, uses image2-4k group tokens
• Cost: Each image = 1 API call
• Speed: Depends on backend load; Nebula 4K request timeout is 1800 seconds

Backend Selection and Nebula Calls

nanobanana Group

When the user specifies nanobanana, both scripts pass --provider nanobanana. The unified .env uses a dedicated NEBULA_NANOBANANA_API_KEY (nanobanana group token), not the image2-4k key. NEBULA_NANOBANANA_MODEL defaults to gemini-3.1-flash-image, can be set to other models supported by the token; ILLUSTRATOR_IMAGE_PROVIDER=nanobanana can be set as default. Both single and batch generation support 16:9, 3:4; can request 1K, 2K, 4K, default 2K, specific supported values and actual pixels are determined by the selected model, not constrained by image2-4k's 4K landscape limit.

The unified .env uses ILLUSTRATOR_SINGLE_RATIO to set the default ratio for single images, ILLUSTRATOR_BATCH_RATIO for batch generation default ratio, and ILLUSTRATOR_RESOLUTION for default request resolution. Both entry points support --ratio, --resolution to override configuration. If not configured or empty, ratio is 16:9, resolution uses the backend default (2K for Gemini/nanobanana, 4K for image2-4k). These settings apply to all backends; if they conflict with backend limits, an error is raised before the request, requiring configuration adjustment or explicit override.

python -X utf8 scripts/generate_single_image.py --provider nanobanana --title "Topic" --content "Illustration content" --style-file styles/ticket.md --ratio 3:4 --resolution 2K --output output/banana.png
python -X utf8 scripts/generate_illustrations.py article.md --provider nanobanana --style ticket --level h2 --resolution 2K

Calls Gemini native POST /v1beta/models/{model}:generateContent, decodes and validates the image from inlineData, does not persist the full Base64 response. No Google SDK required. Current integration only supports text-to-image; does not automatically resend paid tasks on timeout. See README.md and official API documentation.

Original image2-4k Group

Both scripts support --provider gemini|nebula. If not specified, reads ILLUSTRATOR_IMAGE_PROVIDER, uses Gemini if unconfigured. When user explicitly specifies Nebula, pass --provider nebula; do not switch to other services. Configure NEBULA_API_KEY in the unified path ~/.agents/skills/document-illustrator/.env, or use an environment variable with the same name; the token must belong to the image2-4k group. Nebula does not require Gemini key or Google SDK, but still needs Pillow and python-dotenv.

python -X utf8 scripts/generate_single_image.py --provider nebula --title "Topic" --content "Confirmed illustration content" --style-file styles/ticket.md --output output/image-01.png --resolution 4K
python -X utf8 scripts/generate_illustrations.py article.md --provider nebula --style ticket --level h2 --resolution 4K

The script calls POST https://img-api.apinebula.ai/v1/images/generations, always uses gpt-image-2-4k, 3840x2160, quality=high, response_format=url. Prefers reading URL, falls back to Base64; validates actual pixels before saving, converts server JPEG to local extension format. Saves the API response as <image filename>.response.json; if download fails, reuses temporary links from it to retry. Task status may be unknown after POST timeout; does not automatically resend. First check server status to avoid duplicate billing. On HTTP 403 or connection not established, tries http://127.0.0.1:81 proxy. Currently only supports text-to-image; reference image editing not implemented.

Full configuration guide and offline test commands are in README.md; API parameters follow official documentation.

Environment Requirements

Required:

pip install google-genai pillow python-dotenv

API Keys:

• Codex, Claude, and all other agents read ~/.agents/skills/document-illustrator/.env
• Windows equivalent: %USERPROFILE%\.agents\skills\document-illustrator\.env
• Only this file is loaded; its values override environment variables with the same name. If the file does not exist, only existing environment variables are used; no other locations are searched.
• Gemini uses GEMINI_API_KEY, Nebula uses NEBULA_API_KEY
• nanobanana group uses NEBULA_NANOBANANA_API_KEY; model configuration is described in the group section above

📊 Content Summarization Principles

When Claude summarizes content, it follows these principles:

1. Completeness First

• ✅ All important information is included
• ✅ No key concepts are missed
• ✅ Core points of the original text are preserved

2. Clear Logic

• Segmented according to the natural logic of the content
• Related content grouped together
• Maintain narrative coherence

3. Balanced Distribution

• Each image contains a similar amount of information
• Avoid any image being too crowded or empty
• Adjust based on content importance

4. User Control

• Show summarization results for user confirmation
• Users can request adjustments
• Generation begins only after confirmation

🐛 Troubleshooting

Issue 1: API Key Error

Error Message:

Error: Invalid API key

Solution:

1. Check GEMINI_API_KEY or NEBULA_API_KEY in .env for the corresponding backend; for Nebula also verify the token group
2. Ensure the API key is valid and not expired
3. Obtain a new key: https://makersuite.google.com/app/apikey

Issue 2: Unideal Content Summarization

Problem: The summarized topics do not meet expectations

Solution:

1. During the summary presentation stage, tell Codex your expectations
2. Codex will re-summarize and adjust
3. Confirm satisfaction before starting generation

Issue 3: Image Generation Failure

Possible Causes:

• Network connection issues
• API quota exhausted
• Content too long, exceeding limits

Solution:

1. Check network connection
2. Check API quota
3. Try increasing the number of images (to spread out content)

💰 Cost Estimation

Number of Images	API Calls	Estimated Cost
No cover + 3 images	3 calls	Low
Cover + 5 images	6 calls	Medium
Cover + 10 images	11 calls	Higher

Recommendations:

• Short document (<1000 words): 3-5 images
• Medium document (1000-3000 words): 5-7 images
• Long document (>3000 words): 8-10 images

📚 Best Practices

1. Choose the Right Number of Images

Too Few:

• Each image contains too much information
• Hard to understand and remember

Too Many:

• Content becomes scattered
• Increases cost and generation time

Recommended:

• Choose based on document length
• Each image covers 1-2 core points

2. Choose Aspect Ratio Based on Use

16:9 suitable for:

• PPT presentations
• Website banners
• Video thumbnails
• Blog illustrations (desktop)

3:4 suitable for:

• Social media (Instagram, Xiaohongshu)
• Mobile articles
• Poster design
• Portrait videos

3. Using Cover Images

Scenarios where a cover image is recommended:

• Series of articles (as a unified guide)
• Social sharing (as a preview image)
• Document home page (summary)

Scenarios where it can be skipped:

• For internal use only
• Enough images already
• To reduce costs

4. Style Selection Suggestions

Technical documents → Gradient glass card style Data reports → Ticket style Tutorial stories → Vector illustration style Product introductions → Gradient glass card style

🔄 How It Works

Traditional Method (Deprecated)

[Code] Read document → Identify headings ## ### → Mechanical splitting
       ↓
      Relies on specific format
      Easily misses content
      Not intelligent

New Method (Current Implementation)

[Claude] Read document → AI understands content → Intelligent summarization
         ↓
      Format agnostic
      Complete content
      User controllable

Key Differences:

• ❌ Old: Relies on code parsing, only handles standard formats
• ✅ New: AI understands content, handles any format

🎯 Comparison with Other Tools

Feature	Document Illustrator	Traditional PPT Tools	AI Image Generators
Understands document content	✅ AI intelligently understands	❌ Requires manual input	❌ Requires manual input
Format dependency	✅ Format agnostic	❌ Depends on specific format	✅ No dependency
Content completeness	✅ Automatic validation	⚠️ Manual guarantee	❌ Cannot guarantee
Batch generation	✅ Generates multiple at once	❌ One by one	⚠️ Requires multiple inputs
Style consistency	✅ Automatically maintained	⚠️ Manual adjustment	⚠️ Requires repeated prompts

📞 Getting Help

If you have questions or suggestions:

1. Ask directly in Codex
2. Check the Skill directory: ~/.agents/skills/document-illustrator

---

Let AI help you understand and summarize content, generating professional illustrations! ✨