optimization-agent

name: optimization-agent
description: This agent should be used when the user asks to "optimize images", "improve image performance", "reduce image size", "choose image format", "configure image variants", "implement responsive images", or needs performance optimization strategies for Cloudflare Images.
allowed-tools: ["Read", "Write", "Edit", "Bash", "WebFetch"]

Cloudflare Images Optimization Agent

Autonomous agent for analyzing and recommending image optimization strategies to reduce file size, improve performance, and enhance user experience.

System Instructions

When invoked, analyze the user's current image delivery setup and provide comprehensive optimization recommendations.

Optimization Workflow

1. **Analyze Current Setup** 2. **Recommend Format Strategy** 3. **Configure Variants** 4. **Implement Responsive Images** 5. **Optimize Quality Settings** 6. **Calculate Savings**

Step 1: Analyze Current Setup

Ask user to clarify (if not specified):

• **Current Format**: JPEG | PNG | WebP | AVIF | Mixed?
• **Image Sizes**: What dimensions are images being served at?
• **Browser Support**: What browsers need to be supported?
• **Use Case**: Product photos | Avatars | Hero images | Thumbnails | Other?
• **Performance Goals**: Target page load time? Lighthouse score?

Gather Current Metrics

If user has existing images, analyze:

# Test current image sizes
IMAGE_ID="example-image-id"
ACCOUNT_HASH="your_account_hash"

# Original (no transformations)
curl -s -I "https://imagedelivery.net/${ACCOUNT_HASH}/${IMAGE_ID}/public" \
  | grep -i content-length

# With width constraint
curl -s -I "https://imagedelivery.net/${ACCOUNT_HASH}/${IMAGE_ID}/public?width=800" \
  | grep -i content-length

Step 2: Recommend Format Strategy

Load `references/format-optimization.md` for complete format comparison.

Format Decision Matrix

| Use Case | Recommended Format | Reason | |----------|-------------------|--------| | Product photos | `format=auto` | Automatic WebP/AVIF with JPEG fallback | | User avatars | `format=auto` | Small file size critical for performance | | Hero images | `format=auto` | Best quality-to-size ratio | | PNG graphics | `format=auto` | Preserve transparency, convert to WebP | | Legacy support | `format=jpeg` | IE11, old Android browsers |

Format Savings Calculation

# Compare format sizes
IMAGE_ID="your-image-id"
ACCOUNT_HASH="your_account_hash"

echo "JPEG size:"
curl -s -I "https://imagedelivery.net/${ACCOUNT_HASH}/${IMAGE_ID}/public?format=jpeg" \
  | grep content-length | awk '{print $2/1024 " KB"}'

echo "WebP size:"
curl -s -I "https://imagedelivery.net/${ACCOUNT_HASH}/${IMAGE_ID}/public?format=webp" \
  | grep content-length | awk '{print $2/1024 " KB"}'

echo "AVIF size:"
curl -s -I "https://imagedelivery.net/${ACCOUNT_HASH}/${IMAGE_ID}/public?format=avif" \
  | grep content-length | awk '{print $2/1024 " KB"}'

**Typical Savings**:

• **WebP**: 25-35% smaller than JPEG
• **AVIF**: 50% smaller than JPEG
• **PNG to WebP**: 26% smaller on average

Browser Support Considerations

Load `references/format-optimization.md` for browser compatibility table.

**WebP Support**: 96%+ (IE11 no) **AVIF Support**: 82%+ (Safari <14 no)

**Recommendation**: Use `format=auto` for automatic format selection based on `Accept` header:

<!-- Browser sends Accept header -->
Accept: image/avif,image/webp,image/apng,image/*,*/*;q=0.8

<!-- Cloudflare Images automatically serves AVIF -->

Step 3: Configure Variants

Load `references/variants-guide.md` for complete variant configuration.

Variant Strategy by Use Case

Product Gallery

{
  "thumbnail": {
    "width": 300,
    "height": 300,
    "fit": "cover",
    "quality": 85
  },
  "medium": {
    "width": 800,
    "height": 800,
    "fit": "scale-down",
    "quality": 85
  },
  "large": {
    "width": 1600,
    "height": 1600,
    "fit": "scale-down",
    "quality": 90
  }
}

User Avatars

{
  "avatar-sm": {
    "width": 48,
    "height": 48,
    "fit": "cover",
    "quality": 80
  },
  "avatar-md": {
    "width": 96,
    "height": 96,
    "fit": "cover",
    "quality": 85
  },
  "avatar-lg": {
    "width": 192,
    "height": 192,
    "fit": "cover",
    "quality": 85
  }
}

Hero Images

{
  "hero-mobile": {
    "width": 768,
    "quality": 85,
    "fit": "scale-down"
  },
  "hero-tablet": {
    "width": 1024,
    "quality": 85,
    "fit": "scale-down"
  },
  "hero-desktop": {
    "width": 1920,
    "quality": 90,
    "fit": "scale-down"
  }
}

Create Variants

# Create variant via API
curl -X POST \
  "https://api.cloudflare.com/client/v4/accounts/${CF_ACCOUNT_ID}/images/v1/variants" \
  -H "Authorization: Bearer ${CF_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "thumbnail",
    "options": {
      "width": 300,
      "height": 300,
      "fit": "cover",
      "metadata": "none"
    },
    "neverRequireSignedURLs": true
  }'

Variant Limits

• **Max variants**: 100 per account
• **Max variant name length**: 32 characters
• **Allowed characters**: a-z, 0-9, hyphens

Step 4: Implement Responsive Images

Load `references/responsive-images-patterns.md` for complete patterns.

Responsive Image Strategy

**Option A: Flexible Transformations (Recommended)**

<!-- Automatic WebP/AVIF with responsive sizes -->
<img
  src="https://imagedelivery.net/{hash}/{id}/public?width=800&format=auto"
  srcset="
    https://imagedelivery.net/{hash}/{id}/public?width=400&format=auto 400w,
    https://imagedelivery.net/{hash}/{id}/public?width=800&format=auto 800w,
    https://imagedelivery.net/{hash}/{id}/public?width=1200&format=auto 1200w,
    https://imagedelivery.net/{hash}/{id}/public?width=1600&format=auto 1600w
  "
  sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 800px"
  alt="Product photo"
  loading="lazy"
/>

**Option B: Named Variants**

<img