tinify.ai - Prep Your Images for the World

Image format and optimization best practices for web projects

When working with images in web projects:
- Prefer WebP for photographs and complex images (60-80% smaller than JPEG)
- Use SVG for icons, logos, and simple graphics (infinitely scalable)
- Use PNG only when transparency is needed and WebP isn't supported
- AVIF offers best compression but check browser support requirements
- Always set explicit width and height on <img> tags to prevent CLS
- Use loading="lazy" for below-fold images, loading="eager" for hero/LCP images
- Compress all images before deployment — unoptimized images are the #1 web performance issue
- Use the tinify-ai MCP server's optimize_image tool for compression, resizing, and format conversion

MCP server: tinify-ai

{
  "command": "npx",
  "args": [
    "-y",
    "@tinify-ai/mcp-server"
  ]
}

Use when the user wants to add alt text, audit image SEO, improve image accessibility, or generate image metadata. Scans code for images missing alt attributes and generates SEO-optimized alt text, keywords, and filenames.

# Image SEO

Audit and fix image SEO issues in a project. Scans source code for `<img>` tags missing alt text, generates AI-powered alt text and keywords using the tinify-ai MCP server, and applies fixes to the codebase.

## Pre-flight

1. Call the `status` tool to check available credits (each image costs 4 credits: 3 base + 1 for SEO tag generation)
2. Warn if credits are insufficient for the estimated number of images

## Scan

Find all images in source code that need SEO attention:

1. Use Grep to find `<img` tags across the project:
   - HTML: `*.html`
   - React/Next.js: `*.tsx`, `*.jsx`
   - Vue: `*.vue`
   - Svelte: `*.svelte`
   - Astro: `*.astro`

2. From those matches, identify images with issues:
   - Missing `alt` attribute entirely
   - Empty `alt=""` on non-decorative images
   - Generic alt text like `alt="image"`, `alt="photo"`, `alt="untitled"`
   - Non-descriptive filenames like `IMG_4532.jpg`, `Screenshot 2024-01-15.png`

3. Present the findings to the user before making changes:
   - "Found X images missing alt text in Y files. Proceed?"

## Generate Metadata

For each image needing alt text, call `optimize_image` with SEO enabled:

```
optimize_image({
  input: "/absolute/path/to/the/image.jpg",
  output_seo_tag_gen: true
})
```

The tool returns:
- `seo_alt_text` — Descriptive alt text for the image
- `seo_keywords` — Array of relevant keywords
- `seo_filename` — SEO-friendly filename slug (without extension)

## Apply Fixes

1. Use Edit to insert the generated `seo_alt_text` into the source code:
   - `<img src="hero.jpg">` → `<img src="hero.jpg" alt="Sunset over California beach with golden waves">`
   - `<img src="hero.jpg" alt="">` → `<img src="hero.jpg" alt="Sunset over California beach with golden waves">`

2. If the filename is non-descriptive (e.g., `IMG_4532.jpg`), suggest renaming:
   - Show: `IMG_4532.jpg` → `sunset-california-beach.jpg` (from `seo_filename`)
   - Only suggest — do not auto-rename without user approval (renaming may break other references)

## Error Handling

- If `optimize_image` fails with insufficient credits: stop, report progress, suggest `upgrade`
- If an image file cannot be found at the path referenced in code: skip and note in report

## Report

Present a summary of changes:

| File | Image | Alt Text Added | Filename Suggestion |
|------|-------|----------------|---------------------|
| `src/pages/index.tsx` | `hero.jpg` | "Sunset over California beach..." | — |
| `src/pages/about.tsx` | `IMG_4532.jpg` | "Team meeting in modern office" | `team-meeting-office.jpg` |

## Scope

This skill handles image alt text and metadata only. It does NOT handle:
- Page title tags or meta descriptions
- Structured data / JSON-LD
- Sitemap generation
- Other non-image SEO concerns

Use when the user wants to optimize, compress, or prepare images for production. Handles batch optimization of project images with smart format selection and size reduction.

# Optimize Images

Batch-optimize images in a project using the tinify-ai MCP server. This skill teaches you how to audit, optimize, and report on image assets.

## Pre-flight

1. Call the `status` tool to check available credits
2. If credits are low (fewer than the number of images to process), warn the user:
   - If unregistered/guest: suggest `login` to get more credits
   - If registered: suggest `upgrade` for a higher tier
3. Confirm with the user before proceeding with large batches (>20 images)

## Audit

1. Use Glob to find all images in the project:
   - Patterns: `**/*.{jpg,jpeg,png,webp,gif,avif,svg,ico,heic,heif,tiff,bmp}`
   - Exclude: `node_modules/`, `.git/`, `dist/`, `build/`, `.next/`, `vendor/`
2. Use Bash to check file sizes: `find <dir> -type f \( -name "*.jpg" -o -name "*.png" -o -name "*.webp" -o -name "*.gif" -o -name "*.avif" \) -exec ls -la {} \;`
3. Identify optimization candidates — images over 200KB for web projects, or as specified by the user

## Decision Tree

For each image, decide the action:

| Image type | Size | Action |
|------------|------|--------|
| Photo (JPG/PNG) | >200KB | Compress with `optimize_image` |
| PNG photo (no transparency needed) | Any | Convert to WebP: `output_format: "webp"` |
| Already optimized WebP/AVIF | <50KB | Skip |
| SVG | Any | Skip (vector, already optimal) |
| ICO/favicon | Any | Skip (tiny files) |
| GIF (animated) | Any | Compress, but warn about credit cost per frame |

If the user specifies a target format, use that for all images instead.

## Processing

Process images one at a time using `optimize_image`:

```
optimize_image({
  input: "/absolute/path/to/image.jpg",
  output_format: "webp",        // or "original" to keep format
  output_seo_tag_gen: false      // skip SEO tags to save 1 credit per call (3 credits instead of 4)
})
```

- Preserve directory structure — output alongside the original
- Track before/after sizes for the report
- If a GIF has multiple frames, the tool will return a cost warning. Set `confirm_gif_cost: true` to proceed.

## Error Handling

- If `optimize_image` returns a 429 (insufficient credits): **stop immediately**
- Report how many images were processed vs total
- Suggest `upgrade` to get more credits
- Do NOT retry failed optimizations without user confirmation

## Report

After processing, present a summary table:

| File | Original | Optimized | Savings |
|------|----------|-----------|---------|
| hero.jpg | 1.2 MB | 340 KB | 72% |
| banner.png | 890 KB | 210 KB | 76% |
| **Total** | **2.1 MB** | **550 KB** | **74%** |

Use when the user wants to improve image loading performance, fix Core Web Vitals issues (LCP, CLS), audit image lazy loading, or optimize images for page speed. Analyzes and fixes image-related performance issues.

# Web Performance Images

Audit and fix image-related performance issues that affect Core Web Vitals (LCP, CLS, INP). Combines code analysis with the tinify-ai MCP server for image optimization.

## Pre-flight

1. Call the `status` tool to check available credits
2. Detect the framework in use:
   - Next.js: check for `next.config` and `next/image` imports
   - Plain HTML: `.html` files with standard `<img>` tags
   - React: `.tsx`/`.jsx` with `<img>` tags
   - Other: Vue, Svelte, Astro — adapt recommendations accordingly

## LCP Audit (Largest Contentful Paint)

Identify hero and above-fold images:

1. Look for the first large image in the page layout — typically in hero sections, headers, or landing sections
2. Check each hero image for:
   - **File size** — should be under 200KB. If over, compress with `optimize_image`
   - **Preload tag** — should have `<link rel="preload" as="image" href="...">` in the `<head>`
   - **Loading attribute** — should be `loading="eager"` (NOT `loading="lazy"`)
   - **Format** — prefer WebP or AVIF over JPEG/PNG for smaller file size
3. For Next.js: check that hero images use `priority` prop on `<Image>` component

## CLS Audit (Cumulative Layout Shift)

Find all `<img>` tags missing explicit dimensions:

1. Use Grep to find `<img` tags without `width` and `height` attributes
2. For each image missing dimensions:
   - Read the actual image file to determine its dimensions (use Bash: `identify -format "%wx%h" image.jpg` if ImageMagick is available, or call `optimize_image` which returns dimensions)
   - Add `width` and `height` attributes to the tag
3. For Next.js: ensure `<Image>` components have `width`/`height` or use `fill` with a sized container

## Lazy Loading Audit

1. Find all `<img>` tags and classify as above-fold or below-fold:
   - Above-fold: hero images, header logos, first visible content images
   - Below-fold: everything else (gallery items, footer images, content below the fold)
2. Fix loading attributes:
   - Above-fold images: `loading="eager"` (or remove `loading` attribute — eager is default)
   - Below-fold images: `loading="lazy"`
3. For Next.js: above-fold images should have `priority={true}`, others should NOT

## Size Audit

Find oversized images:

1. Use Glob + Bash to find images over 200KB:
   ```
   find . -type f \( -name "*.jpg" -o -name "*.png" -o -name "*.webp" \) -size +200k
   ```
2. For each oversized image, compress with `optimize_image`:
   ```
   optimize_image({ input: "/path/to/large-image.jpg" })
   ```
3. If an image's intrinsic dimensions are much larger than its display size, resize:
   ```
   optimize_image({
     input: "/path/to/image.jpg",
     output_width_px: 1200
   })
   ```

## Responsive Images (Best Effort)

If the project serves images at multiple sizes, suggest `srcset` patterns:

**Plain HTML:**
```html
<img
  src="image-800w.webp"
  srcset="image-400w.webp 400w, image-800w.webp 800w, image-1200w.webp 1200w"
  sizes="(max-width: 600px) 400px, (max-width: 900px) 800px, 1200px"
  alt="Description"
  width="1200" height="800"
  loading="lazy"
>
```

**Next.js:** Suggest using `<Image>` component with `sizes` prop — it handles srcset automatically.

This section is advisory — only suggest if the user asks or if images are clearly served at single large sizes across all viewports.

## Error Handling

- If `optimize_image` fails with insufficient credits: stop, report progress, suggest `upgrade`
- If ImageMagick/`identify` is not available for dimension detection: fall back to calling `optimize_image` to get dimensions from the output

## Report

Present a structured audit report:

### Performance Issues Found

| Issue | File | Image | Fix |
|-------|------|-------|-----|
| Missing dimensions | `index.html:15` | `hero.jpg` | Added `width="1200" height="800"` |
| No lazy loading | `gallery.html:42` | `photo-3.jpg` | Added `loading="lazy"` |
| Oversized (1.2MB) | `about.html:8` | `team.png` | Compressed to 280KB (77% smaller) |
| Hero not preloaded | `index.html` | `hero.jpg` | Added `<link rel="preload">` |

### Summary
- Total issues: X
- Fixed automatically: Y
- Requires manual action: Z