feat: add banana image generation extension (seo-image-gen)

Integrate claude-banana AI image generation as a Claude SEO extension,
following the established DataForSEO extension pattern. Enables SEO-specific
image generation (OG previews, hero banners, product photos, infographics)
via Gemini nanobanana-mcp.

New extension at extensions/banana/ with:
- SEO-focused adapter SKILL.md mapping use cases to optimized defaults
- Audit agent for OG/social image analysis during /seo audit
- 7 Python scripts (stdlib only) for generation, editing, cost tracking
- 7 reference files including SEO-specific presets
- install.sh / uninstall.sh following DataForSEO pattern
- Full documentation (README, setup guide)

Updated: seo/SKILL.md routing, plugin.json v1.5.0, COMMANDS.md, ARCHITECTURE.md

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: AgriciDaniel

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-seo",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Comprehensive SEO analysis skill for Claude Code. Covers technical SEO, content quality (E-E-A-T), schema markup, image optimization, sitemap architecture, AI search optimization (GEO), and strategic planning across all industries.",
   "author": "AgriciDaniel",
   "license": "MIT",
@@ -19,7 +19,9 @@
     "skills/seo-plan/SKILL.md",
     "skills/seo-programmatic/SKILL.md",
     "skills/seo-competitor-pages/SKILL.md",
-    "skills/seo-hreflang/SKILL.md"
+    "skills/seo-hreflang/SKILL.md",
+    "extensions/dataforseo/skills/seo-dataforseo/SKILL.md",
+    "extensions/banana/skills/seo-image-gen/SKILL.md"
   ],
   "agents": [
     "agents/seo-technical.md",
@@ -28,6 +30,8 @@
     "agents/seo-sitemap.md",
     "agents/seo-performance.md",
     "agents/seo-visual.md",
-    "agents/seo-geo.md"
+    "agents/seo-geo.md",
+    "extensions/dataforseo/agents/seo-dataforseo.md",
+    "extensions/banana/agents/seo-image-gen.md"
   ]
 }

CLAUDE.md

@@ -13,7 +13,7 @@ schema markup, image optimization, sitemap architecture, and AI search optimizat
 ```
 claude-seo/
   CLAUDE.md                          # Project instructions (this file)
-  .claude-plugin/plugin.json         # Plugin manifest (v1.3.2)
+  .claude-plugin/plugin.json         # Plugin manifest v1.5.0
   seo/                               # Main orchestrator skill
     SKILL.md                         # Entry point, routing table, core rules
     references/                      # On-demand knowledge files
@@ -41,6 +41,9 @@ claude-seo/
     seo-performance.md             # Core Web Vitals, page speed
     seo-visual.md                  # Screenshots, mobile rendering
     seo-geo.md                     # AI crawler access, GEO, citability
+  extensions/                          # Optional add-on capabilities
+    dataforseo/                    # Live SEO data via DataForSEO MCP
+    banana/                        # AI image generation via Gemini MCP
   docs/                              # Extended documentation
     ARCHITECTURE.md                # System design overview
     COMMANDS.md                    # Full command reference
@@ -65,6 +68,7 @@ claude-seo/
 | `/seo programmatic` | Programmatic SEO analysis and planning |
 | `/seo competitor-pages` | Competitor comparison page generation |
 | `/seo hreflang <url>` | International SEO / hreflang audit |
+| `/seo image-gen [use-case] <desc>` | AI image generation for SEO assets (extension) |
 
 ## Development Rules
 
@@ -81,4 +85,4 @@ claude-seo/
 1. **Progressive Disclosure**: Metadata always loaded, instructions on activation, resources on demand
 2. **Industry Detection**: Auto-detect SaaS, e-commerce, local, publisher, agency
 3. **Parallel Execution**: Full audits spawn 7 subagents simultaneously
-4. **Extension System**: DataForSEO MCP integration for live data
+4. **Extension System**: DataForSEO MCP for live data, Banana MCP for AI image generation

docs/ARCHITECTURE.md

@@ -198,27 +198,56 @@ Extensions are opt-in add-ons that integrate external data sources via MCP serve
 
 ```
 extensions/
-└── dataforseo/               # DataForSEO MCP integration
+├── dataforseo/               # DataForSEO MCP integration
+│   ├── README.md                  # Extension documentation
+│   ├── install.sh                 # Unix installer
+│   ├── install.ps1                # Windows installer
+│   ├── uninstall.sh               # Unix uninstaller
+│   ├── uninstall.ps1              # Windows uninstaller
+│   ├── field-config.json          # API response field filtering
+│   ├── skills/
+│   │   └── seo-dataforseo/
+│   │       └── SKILL.md           # Sub-skill (22 commands)
+│   ├── agents/
+│   │   └── seo-dataforseo.md      # Subagent
+│   └── docs/
+│       └── DATAFORSEO-SETUP.md    # Account setup guide
+│
+└── banana/                   # Banana Image Generation (Gemini AI)
     ├── README.md                  # Extension documentation
     ├── install.sh                 # Unix installer
-    ├── install.ps1                # Windows installer
     ├── uninstall.sh               # Unix uninstaller
-    ├── uninstall.ps1              # Windows uninstaller
-    ├── field-config.json          # API response field filtering
     ├── skills/
-    │   └── seo-dataforseo/
-    │       └── SKILL.md           # Sub-skill (22 commands)
+    │   └── seo-image-gen/
+    │       └── SKILL.md           # Sub-skill (6 commands)
     ├── agents/
-    │   └── seo-dataforseo.md      # Subagent
+    │   └── seo-image-gen.md       # Image audit subagent
+    ├── scripts/                   # Python scripts (stdlib only)
+    │   ├── generate.py            # Direct API fallback
+    │   ├── edit.py                # Image editing fallback
+    │   ├── batch.py               # CSV batch workflow
+    │   ├── cost_tracker.py        # Usage and cost tracking
+    │   ├── presets.py             # Brand preset management
+    │   ├── setup_mcp.py           # MCP configuration
+    │   └── validate_setup.py      # Installation verification
+    ├── references/                # On-demand knowledge
+    │   ├── prompt-engineering.md  # 6-component Reasoning Brief
+    │   ├── gemini-models.md       # Model specs and pricing
+    │   ├── mcp-tools.md           # MCP tool reference
+    │   ├── post-processing.md     # ImageMagick recipes
+    │   ├── cost-tracking.md       # Cost tracking guide
+    │   ├── presets.md             # Preset schema
+    │   └── seo-image-presets.md   # SEO-specific presets
     └── docs/
-        └── DATAFORSEO-SETUP.md    # Account setup guide
+        └── BANANA-SETUP.md        # API key and MCP setup
 ```
 
 ### Available Extensions
 
 | Extension | Package | What it Adds |
 |-----------|---------|-------------|
 | **DataForSEO** | `dataforseo-mcp-server` | 22 commands: live SERP, keywords, backlinks, on-page analysis, content analysis, business listings, AI visibility, LLM mentions |
+| **Banana Image Gen** | `@ycse/nanobanana-mcp` | 6 commands: OG image, hero image, product photo, infographic, custom, and batch generation via Gemini AI |
 
 ### Extension Convention
 

docs/COMMANDS.md

@@ -314,6 +314,37 @@ Live SEO data via DataForSEO MCP server (extension). 22 commands across 9 API mo
 
 ---
 
+### `/seo image-gen [use-case] <description>`
+
+AI image generation for SEO assets (extension). Powered by Gemini via nanobanana-mcp.
+
+**Prerequisites:** Banana extension installed (`./extensions/banana/install.sh`)
+
+**Use Cases:**
+```
+/seo image-gen og <description>          # OG/social preview image (16:9, 1K)
+/seo image-gen hero <description>        # Blog hero image (16:9, 2K)
+/seo image-gen product <description>     # Product photography (4:3, 2K)
+/seo image-gen infographic <description> # Infographic visual (2:3, 4K)
+/seo image-gen custom <description>      # Custom with full Creative Director pipeline
+/seo image-gen batch <description> [N]   # Generate N variations (default: 3)
+```
+
+**Example:**
+```
+/seo image-gen og "Professional SaaS analytics dashboard with clean UI"
+/seo image-gen hero "Dramatic sunset over modern city skyline"
+/seo image-gen product "Wireless noise-canceling headphones on marble surface"
+```
+
+**What it does:**
+1. Maps SEO use case to optimized domain mode, aspect ratio, and resolution
+2. Constructs 6-component Reasoning Brief (Creative Director pipeline)
+3. Generates image via Gemini API
+4. Provides SEO checklist (alt text, file naming, WebP, schema markup)
+
+---
+
 ## Quick Reference
 
 | Command | Use Case |
@@ -324,6 +355,7 @@ Live SEO data via DataForSEO MCP server (extension). 22 commands across 9 API mo
 | `/seo geo <url>` | AI search optimization |
 | `/seo hreflang [url]` | Hreflang/i18n SEO audit |
 | `/seo images <url>` | Image optimization |
+| `/seo image-gen [use-case] <desc>` | AI image generation (extension) |
 | `/seo page <url>` | Single page analysis |
 | `/seo plan <type>` | Strategic planning |
 | `/seo programmatic [url\|plan]` | Programmatic SEO analysis |

extensions/banana/README.md

@@ -0,0 +1,92 @@
+# Banana Image Generation Extension for Claude SEO
+
+Generate production-ready SEO images using AI — OG/social previews, blog heroes,
+product photography, infographics, and more. Powered by Google Gemini via the
+banana Creative Director pipeline.
+
+## Prerequisites
+
+- **Claude SEO** installed (`~/.claude/skills/seo/`)
+- **Node.js 18+** with npx
+- **Google AI API key** (free at [aistudio.google.com/apikey](https://aistudio.google.com/apikey))
+- **ImageMagick** (optional, for post-processing)
+
+## Installation
+
+```bash
+./extensions/banana/install.sh
+```
+
+The installer will:
+1. Verify Claude SEO is installed
+2. Prompt for your Google AI API key (if nanobanana-mcp not already configured)
+3. Install the `seo-image-gen` skill and agent
+4. Configure the MCP server in `~/.claude/settings.json`
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `/seo image-gen og <description>` | OG/social preview image (1200x630 feel) |
+| `/seo image-gen hero <description>` | Blog hero image (widescreen, dramatic) |
+| `/seo image-gen product <description>` | Product photography (clean, white BG) |
+| `/seo image-gen infographic <description>` | Infographic visual (vertical, data-heavy) |
+| `/seo image-gen custom <description>` | Custom with full Creative Director pipeline |
+| `/seo image-gen batch <description> [N]` | Generate N variations (default: 3) |
+
+## Use Case Defaults
+
+| Use Case | Aspect Ratio | Resolution | Domain Mode | Cost |
+|----------|-------------|------------|-------------|------|
+| OG/Social Preview | 16:9 | 1K | Product/UI | ~$0.04 |
+| Blog Hero | 16:9 | 2K | Cinema/Editorial | ~$0.08 |
+| Product Photo | 4:3 | 2K | Product | ~$0.08 |
+| Infographic | 2:3 | 4K | Infographic | ~$0.16 |
+| Social Square | 1:1 | 1K | UI/Web | ~$0.04 |
+| Favicon/Icon | 1:1 | 512 | Logo | ~$0.02 |
+
+## How It Works
+
+Claude acts as a **Creative Director** — it never passes raw text to the API.
+Instead, it analyzes your intent, selects the optimal domain mode, and constructs
+an optimized prompt using a proven 6-component Reasoning Brief system:
+
+1. **Subject** (30%) — Physical specificity and micro-details
+2. **Style** (25%) — Camera specs, film stock, brand references
+3. **Context** (15%) — Location, time, weather, supporting elements
+4. **Action** (10%) — Pose, gesture, movement, state
+5. **Composition** (10%) — Shot type, framing, focal length
+6. **Lighting** (10%) — Direction, quality, color temperature
+
+## Post-Generation SEO Checklist
+
+After every generation, Claude provides:
+- Alt text suggestion (keyword-rich, descriptive)
+- SEO-friendly file naming convention
+- WebP conversion command
+- ImageObject schema snippet
+- OG meta tag markup (for social previews)
+
+## Audit Integration
+
+During `/seo audit`, the extension optionally spawns an image analysis agent that:
+- Audits existing OG/social images across the site
+- Identifies missing or low-quality images
+- Creates a prioritized generation plan with prompt suggestions
+- Estimates total cost for the generation plan
+
+The agent never auto-generates images — it produces a plan for your review.
+
+## Uninstallation
+
+```bash
+./extensions/banana/uninstall.sh
+```
+
+This removes the skill and agent. If you also use the standalone banana skill,
+the MCP server config is preserved.
+
+## Troubleshooting
+
+See [docs/BANANA-SETUP.md](docs/BANANA-SETUP.md) for detailed setup instructions
+and common issues.

extensions/banana/agents/seo-image-gen.md

@@ -0,0 +1,59 @@
+---
+name: seo-image-gen
+description: SEO image analyst. Audits existing OG/social preview images, identifies missing or low-quality images, and creates an image generation plan with prompts for key pages. Does NOT auto-generate images.
+tools: Read, Bash, Glob, Grep
+---
+
+You are an SEO image analyst. When delegated tasks during an SEO audit:
+
+1. Check that nanobanana-mcp tools are available before including generation recommendations
+2. Analyze the site's existing image strategy for SEO impact
+3. Output a structured generation plan — never auto-generate (cost control)
+
+## Analysis Scope
+
+For each audited page, evaluate:
+- **OG image presence** — Does `og:image` meta tag exist? Is it valid?
+- **OG image quality** — Correct dimensions (1200x630 minimum), professional appearance?
+- **Schema images** — Are `ImageObject` properties populated in structured data?
+- **Alt text quality** — Descriptive, keyword-rich, not stuffed?
+- **Image format** — Using modern formats (WebP, AVIF) vs legacy (PNG, JPEG)?
+- **Image file size** — Under 200KB for hero, under 100KB for thumbnails?
+
+## Output Format
+
+Match existing claude-seo patterns:
+
+### Image Audit Summary
+
+| Metric | Value | Status |
+|--------|-------|--------|
+| Pages with OG images | X/Y | Pass/Fail |
+| OG images correct size | X/Y | Pass/Fail |
+| Schema ImageObject usage | X/Y | Pass/Fail |
+| WebP/AVIF adoption | X% | Pass/Fail |
+| Average image file size | XKB | Pass/Fail |
+
+### Image Generation Plan
+
+For each page missing or having low-quality images:
+
+| Page | Issue | Suggested Use Case | Prompt Idea | Priority |
+|------|-------|-------------------|-------------|----------|
+| /homepage | Missing OG image | og | Professional SaaS dashboard overview | Critical |
+| /blog/post-1 | Low-res hero | hero | [contextual suggestion] | High |
+
+Priority levels: Critical > High > Medium > Low
+
+### Recommendations
+
+- Prioritize pages by traffic volume (highest traffic = fix first)
+- Note estimated cost for full generation plan
+- Suggest batch generation for efficiency
+- Recommend WebP conversion pipeline for all generated assets
+
+## Error Handling
+
+- If nanobanana-mcp is not available, still audit existing images but note that generation requires the banana extension
+- Report errors clearly with actionable next steps
+- Note data source as "Image Audit (static analysis)" to distinguish from live checks