Image Optimization

Use this skill when optimizing images for web delivery, social media, or storage. MCP bridge tools are the primary interface; the media worker Sharp API is the fallback for batch and advanced operations.

MCP Tool Discovery

The mcp-ai-wpoos plugin may register tools under agent-specific prefixes. Always check your tool list for the correct names. These tools are typically available as bare names across all agent contexts:

Optimization Task	Tool Name	Notes
Resize images	resize_image	Bare name — usually registered everywhere
Remove backgrounds	remove_background	Bare name
Generate alt text	generate_image_alt_text_validated	Bare name
Generate captions	generate_image_caption_validated	Bare name
Analyze image content	analyze_image	Bare name
OCR text extraction	extract_image_text	Bare name
Cross-site media check	remote_wp_connection	Discover spoke sites before optimizing for them
Bulk resize images	bulk_resize_media	Resize multiple images in one operation
Bulk compress images	bulk_compress_media	Compress multiple images to target sizes
Find unused media	find_unused_media	Detect orphaned attachments consuming storage

Use these tools directly. The media worker (http://localhost:3100/api/image/optimize) is the fallback for WebP/AVIF format conversion and batch operations not yet covered by MCP tools.

WP-CLI Commands

Key mcp-ai WP-CLI commands for image optimization workflows. Run via terminal:

Command	Use for
wp mcp-ai bulk	Batch-process images — resize, compress, format convert
wp mcp-ai cache clear	Clear media caches after bulk optimization
wp mcp-ai health	Verify image processing tools are registered
wp mcp-ai log	Check optimization success/failure logs

When to use this skill

Trigger when ANY of the following is true:

• Images are being uploaded to or served from WordPress.
• Page speed / Core Web Vitals scores need improvement (especially LCP).
• Converting between image formats (PNG → WebP, JPEG → AVIF).
• Generating responsive image variants (srcset).
• Bulk-processing existing media libraries.
• Preparing images for social media platforms with specific dimension requirements.
• Removing backgrounds from product photos or portraits.

Resizing images via MCP (Primary)

Use resize_image to resize any image in your Media Library or from a URL:

Parameters:
  attachment_id  — WordPress attachment ID of the image (or use url/file_id)
  url            — URL to an external image
  width          — Target width in pixels (1–10000)
  height         — Target height in pixels (1–10000)
  maintain_ratio — Keep aspect ratio (default: true)
  crop           — Crop to exact dimensions (default: false)
  output_format  — "default" (same as source) or "svg" (vectorize)
  file_name      — Optional base name for the saved attachment

Examples:

• Resize hero image to 1200px wide: width: 1200, maintain_ratio: true
• Square Instagram crop: width: 1080, height: 1080, crop: true
• Thumbnail: width: 300, maintain_ratio: true

Background removal via MCP (Primary)

Use remove_background to make image backgrounds transparent:

Parameters:
  attachment_id — WordPress attachment ID
  url           — URL alternative
  method        — "auto" (tries free first), "free" (rembg), "paid" (remove.bg API)
  file_name     — Optional base name

Best for: product photos, portraits, logos that need transparent backgrounds for overlays.

AI-powered metadata via MCP

Alt text generation

Use generate_image_alt_text_validated to create accessible alt text:

Parameters:
  attachment_id — WordPress attachment ID
  url           — URL alternative
  context       — Optional context about the image's usage

Caption generation

Use generate_image_caption_validated for detailed image captions:

Parameters:
  attachment_id — WordPress attachment ID
  url           — URL alternative
  context       — Optional context for more relevant captions

Image analysis

Use analyze_image for comprehensive AI vision analysis: object detection, color extraction, composition analysis, and OCR.

Format selection guide

Format	Best For	Compression	Browser Support
WebP	General web images, photos, thumbnails	~30% smaller than JPEG	97%+ (all modern)
AVIF	High-quality photos, hero images	~50% smaller than JPEG	93%+ (Chrome, Firefox, Safari 16+)
JPEG	Photos (fallback)	Lossy, good at 80%	100%
PNG	Logos, icons, transparency	Lossless	100%
SVG	Vector logos, icons, illustrations	Tiny (text-based)	100%

Rule of thumb: WebP for everything, AVIF for hero/LCP images, fallback JPEG for email clients.

Note: WebP/AVIF format conversion currently requires the media worker fallback (/api/image/optimize). MCP resize_image preserves the source format.

Social media image dimensions

Platform	Feed Post	Story/Reel	Profile
Instagram	1080×1080 (1:1) / 1080×1350 (4:5)	1080×1920 (9:16)	320×320
Facebook	1200×630 (1.91:1)	1080×1920	180×180
Twitter/X	1200×675 (16:9)	—	400×400
LinkedIn	1200×627 (1.91:1)	—	400×400
Pinterest	1000×1500 (2:3)	—	165×165

Use resize_image with these dimensions to prepare platform-specific variants from a single source image.

Media worker fallback (advanced)

For WebP/AVIF conversion, batch processing, or custom quality settings, use the media worker:

Format conversion

const form = new FormData();
form.append('file', imageBlob, 'hero.jpg');
form.append('format', 'webp');
form.append('width', '1200');
form.append('quality', '80');

const response = await fetch('http://localhost:3100/api/image/optimize', {
  method: 'POST',
  body: form,
});

const { b64, optimized_size, savings_percent } = await response.json();

Batch processing

const form = new FormData();
images.forEach((img, i) => form.append('files', img));
form.append('format', 'webp');
form.append('width', '800');

const response = await fetch('http://localhost:3100/api/image/batch', {
  method: 'POST',
  body: form,
});

WordPress integration

Responsive srcset with WebP (using media worker)

function design_responsive_image( $attachment_id, $sizes = [ 400, 800, 1200 ] ) {
    $src = wp_get_attachment_url( $attachment_id );
    $srcset = [];

    foreach ( $sizes as $width ) {
        $srcset[] = "$src?w={$width}&format=webp {$width}w";
    }

    return sprintf(
        '<img src="%s" srcset="%s" sizes="(max-width: 800px) 100vw, 800px" loading="lazy" decoding="async" />',
        "$src?w=800&format=webp",
        implode( ', ', $srcset )
    );
}

Performance targets

Metric	Target
LCP image size	< 100 KB (WebP/AVIF)
Hero image dimensions	Max 2400px wide (2x retina = 1200px display)
Thumbnail	150–300px, < 20 KB
Social sharing (og:image)	1200×630, < 200 KB
Total page image weight	< 1 MB for above-fold

Critical rules

• MCP first — use resize_image and remove_background for individual image operations.
• WebP first, JPEG fallback — use <picture> element for format switching; convert via media worker.
• Never serve full-resolution originals — resize to display dimensions × 2 (retina).
• Strip EXIF data — removes GPS, camera info; reduces file size and privacy risk.
• Lazy-load below fold — loading="lazy" on all images except LCP candidate.
• Explicit width/height — prevents layout shift (CLS); WordPress outputs these by default since 5.5.
• Always add alt text — use generate_image_alt_text_validated for AI-generated descriptions.

Common mistakes

<!-- WRONG — 4000px original served as 400px thumbnail -->
<img src="photo.jpg" width="400" />

<!-- RIGHT — responsive with WebP and srcset -->
<picture>
  <source srcset="photo-400.webp 400w, photo-800.webp 800w" type="image/webp" />
  <img src="photo-400.jpg" srcset="photo-400.jpg 400w, photo-800.jpg 800w"
       sizes="(max-width: 600px) 400px, 800px"
       width="800" height="600" loading="lazy" decoding="async"
       alt="AI-generated description of the image" />
</picture>

What This Skill Does NOT Cover

• Image generation — use design-image-generation for AI creation of new images via Gemini, DALL·E, or other providers.
• Video processing — use design-video-creation for video transcoding, frame extraction, and format conversion.
• Social media publishing — use design-social-publishing to post optimized images to Instagram, Facebook, Twitter/X, or LinkedIn.
• Media workflow automation — use design-media-workflow for end-to-end pipelines that chain generation, optimization, and publishing.
• Brand asset management — use design-brand-kit for logo placement, brand color application, and visual identity consistency.
• Image analysis and OCR — use analyze_image or extract_image_text for content analysis rather than optimization.

Cross-references

• Run design-image-generation before optimization — check your tool list for the Gemini image tool.
• Run design-social-publishing to attach optimized images to social posts.
• Run design-media-workflow for end-to-end pipeline automation including cross-site optimization.
• Run mcp-ai-wpoos-plugin for remote_wp_connection — verify spoke sites before optimizing media for them.
• Use bulk_resize_media to resize multiple images in a single batch operation.
• Use bulk_compress_media to compress multiple images with format selection (WebP/AVIF).
• Use find_unused_media to identify orphaned attachments for cleanup or optimization.

References

• Sharp documentation: https://sharp.pixelplumbing.com/
• WebP browser support: https://caniuse.com/webp
• AVIF browser support: https://caniuse.com/avif
• WordPress responsive images: https://developer.wordpress.org/apis/responsive-images/