# Astro Assets

> Use when optimizing images or other assets in Astro — <Image />, <Picture />, getImage(), Fonts API, or OG image generation.

- Skill: `fusengine/astro-assets` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add fusengine/astro-assets`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fusengine/astro-assets/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: fusengine (https://skillmd.com/u/fusengine)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/fusengine/astro-assets

---


<objective>
Handles image and asset optimization in Astro 7 via the `astro:assets` module: `<Image />` and `<Picture />` components (automatic WebP/AVIF conversion, responsive `srcset`/`sizes`, required `alt`), `getImage()` for server-side generation (API routes, CSS backgrounds), remote image handling with `inferSize`, and `@astrojs/sharp` as the default processing service.

Also covers the built-in Fonts API (stable since Astro 6.0) for zero-layout-shift font loading, dynamic OG image generation with Satori at build time, and CDN integration (Cloudinary, Imgix). Does not cover general SEO meta tags (astro-seo) or deployment-specific image CDN config beyond the adapter itself (astro-deployment).
</objective>

# Astro Assets

Production-ready image optimization and asset management with `astro:assets` in Astro 7.

## Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:

1. **fuse-ai-pilot:explore-codebase** - Analyze existing image usage and asset patterns
2. **fuse-ai-pilot:research-expert** - Verify astro:assets API via Context7/Exa
3. **mcp__context7__query-docs** - Check Astro 6 Fonts API and image component docs

After implementation, run **fuse-ai-pilot:sniper** for validation.

---

## Overview

### When to Use

- Displaying optimized images with automatic WebP/AVIF conversion
- Building responsive images with multiple breakpoints
- Loading remote images from external CDNs
- Configuring custom fonts without layout shift
- Generating OG images dynamically with Satori
- Integrating Cloudinary or Imgix as image CDN

### Key Modules

| Module | Exports |
|--------|---------|
| `astro:assets` | `<Image />`, `<Picture />`, `getImage()` |
| `@astrojs/sharp` | Default image processing service |
| Fonts API (stable, Astro 6.0+) | Built-in `fonts` config |

---

## Core Concepts

### Image Component

`<Image />` automatically optimizes local and remote images. Always provide `alt`. Use `priority` for above-the-fold images. Defaults to WebP output.

### Picture Component

`<Picture />` generates `<source>` elements for multiple formats. Use `formats={['avif', 'webp']}` for best compression with fallback.

### getImage()

For server-side image generation (API routes, CSS background images). Returns `{ src, attributes }` object.

### Fonts API (stable, Astro 6.0+)

Built-in font optimization via the top-level `fonts` config in `astro.config.mjs` (stable since Astro 6.0 — no experimental flag). Zero layout shift, automatic preloading, supports Google Fonts and local fonts.

---

## Reference Guide

### Concepts

| Topic | Reference | When to Consult |
|-------|-----------|-----------------|
| **Image Component** | [image-component.md](references/image-component.md) | Local/remote image display |
| **Responsive Images** | [picture-responsive.md](references/picture-responsive.md) | Multi-format, srcset, sizes |
| **Remote Images** | [remote-images.md](references/remote-images.md) | External URLs, inferSize |
| **Fonts API** | [fonts-api.md](references/fonts-api.md) | Zero-CLS font loading |
| **OG with Satori** | [og-satori.md](references/og-satori.md) | Dynamic OG image generation |
| **CDN Integration** | [cdn-integration.md](references/cdn-integration.md) | Cloudinary, Imgix setup |

### Templates

| Template | When to Use |
|----------|-------------|
| [image-setup.md](references/templates/image-setup.md) | Full image optimization setup |
| [og-image-route.md](references/templates/og-image-route.md) | Dynamic OG image API route |

---

## Best Practices

1. **Always provide `alt`** - Required for accessibility and SEO
2. **Use `priority` for LCP** - Above-the-fold images load eagerly
3. **`inferSize` for remote** - Avoids layout shift without known dimensions
4. **Fonts API over @font-face** - Built-in optimization, no manual preload
5. **Satori at build time** - Run OG generation during SSG, not SSR