Web assets optimization

Web Assets Optimization

Optimize the assets the app actually ships: images, video, animated media, fonts, and SVG. Prefer safe, measurable wins: smaller files, modern formats, responsive markup, stable layout, deliberate loading order, and framework-compatible delivery.

Leading words for this skill:

• pipeline — extend the project's existing asset tooling; do not replace a working optimizer.
• clean — write final asset paths only; leave no temp folders, unused variants, orphaned heavy sources, or ffmpeg two-pass logs.
• strategy — every asset gets a deliberate decision from the matrix in Step 3 (importance x placement x loading context); no blanket policies.
• LCP — treat LCP candidates (hero image, video poster, CSS background) as highest priority; never lazy-load them.

When not to use

• The user wants generated artwork from prompts → use an image-generation skill.
• The ask is a visual redesign with no asset-performance work.
• Assets are already transformed by a CMS/CDN pipeline, unless the task is markup or config around that CDN.
• Video editing/production work (cuts, color grading, subtitles) — this skill only compresses and delivers.
• Sources are proprietary, or destructive edits are requested without backups.

Hard rules

• Stay clean: optimized files land in kept public/assets paths; remove old unoptimized sources once unreferenced; delete unused variants, experimental output dirs, and ffmpeg -passlogfile logs before finishing.
• Optimize referenced assets first; unused archives only if the user asks (or delete them when clearly safe).
• Detect the framework before patching markup; prefer framework-native primitives already in use.
• Do not add a package manager or root tooling to documentation-only repositories; in target apps, prefer existing package managers and scripts.
• Never lazy-load an LCP candidate — including video posters and CSS background LCP images.
• Always reserve space: width/height (or CSS aspect-ratio) on every <img> AND <video>.
• Video: never ship AV1-only; always keep an MP4/H.264 fallback <source>; H.264 requires -pix_fmt yuv420p, even dimensions, and -movflags +faststart.
• Animated GIFs used in pages: replace with <video> or animated WebP/AVIF unless the context only accepts image formats (README/Markdown renderers, email, Open Graph).
• Fonts: ship WOFF2 only; font preloads always carry crossorigin, even same-origin.
• Keep SVG logos/icons as vectors; when running SVGO, keep the viewBox (removeViewBox: false).
• Preserve semantics: meaningful alt for content images, alt="" only when decorative; aria-label or nearby text for meaningful <video> (no alt exists).

Branches

Ask	Path
Audit only	Steps 1–3, then report (skip generation and markup).
Optimize + markup	Full workflow below.
Single asset type (e.g. "compress this video", "fix our fonts", "replace these GIFs")	Steps 1–3 scoped to that type, then the matching reference file and Steps 5–9 for those assets.
CDN/CMS already transforms	Step 1 + markup/config only; see frameworks.md CMS section.
Delivery/LCP tuning only (no re-encoding)	Steps 1–3 + Step 6 with delivery-strategy.md.

Workflow

Track with this checklist (one item per step below):

- [ ] 1. Detect framework and asset pipeline
- [ ] 2. Inventory referenced assets (images, video, GIFs, fonts, SVG)
- [ ] 3. Build the per-asset strategy matrix
- [ ] 4. Plan per-type transforms and commands
- [ ] 5. Generate optimized assets into final paths
- [ ] 6. Replace references with optimized markup and loading attributes
- [ ] 7. Delete old unoptimized assets and unused variants
- [ ] 8. Re-scan and verify references stay clean
- [ ] 9. Verify visuals/build and report

Scripts

Resolve this skill's directory (the folder that contains this SKILL.md), then run helpers relative to that root. Pass --root as the target app path.

python3 <skill-dir>/scripts/scan-assets.py --root <app-root> --format markdown
python3 <skill-dir>/scripts/scan-assets.py --root <app-root> --format json > asset-scan.json
python3 <skill-dir>/scripts/generate-sharp-plan.py asset-scan.json --widths 320,640,1024,1536
python3 <skill-dir>/scripts/generate-ffmpeg-plan.py asset-scan.json

Inside this repository only, <skill-dir> is skills/web/web-assets-optimization.

Step 1 — Detect framework and pipeline

Check package.json, framework configs, image/font component imports (next/image, next/font, astro:assets, @nuxt/image, @nuxt/fonts, @sveltejs/enhanced-img), and CDN/CMS loaders. If a working pipeline exists, extend it.

Done when: the framework (or plain HTML) plus any existing optimizers for images AND fonts are named, and the patch strategy is chosen (native component vs plain markup).

See frameworks.md.

Step 2 — Inventory referenced assets

Run scan-assets.py. Review per type: path, bytes, dimensions (video dims are not detected — note as unknown), references, and usage hints (logo, app-icon, favicon, animated, poster, preload, legacy-font-format).

Done when: every referenced local image/video/GIF/font/SVG under --root is listed; large unreferenced assets are noted; remote URLs are listed separately.

Step 3 — Build the strategy matrix

This is the intelligence step — do not skip it. For each asset that matters (raster > 200 KB, any video, any GIF > 100 KB, every shipped font file, SVG > 20 KB, plus every LCP candidate regardless of size), record one strategy row: asset | type | role | placement | action | loading policy.

• Role: LCP candidate / contentful / decorative / functional (icon, favicon).
• Placement: above fold / below fold / offscreen-conditional (modal, carousel, tab) / global (font, sprite).
• LCP candidates include: <img>, <video> poster, CSS background-image via url(), <image> in <svg>.

Loading policy per role x placement:

Role x placement	Loading policy
LCP candidate	eager, fetchpriority="high", never lazy; must be discoverable in initial HTML; preload only if late-discovered (CSS background, font)
Above-fold, non-LCP	eager, default priority, dimensions set
Below-fold image/iframe	loading="lazy", decoding="async", dimensions mandatory
Offscreen-conditional (modal, carousel, tab)	loading="lazy" (or defer the fetch until the trigger interaction for modal/tab content); fetchpriority="low" on prefetched carousel slides so they do not compete with critical resources
Below-fold autoplay video loop	preload="none" + poster, or IntersectionObserver src-swap; pause offscreen
Click-to-play video	preload="metadata" (or none) + poster
Long offscreen sections	content-visibility: auto + contain-intrinsic-size
Critical text font	WOFF2 subset, preload with crossorigin, font-display: swap/fallback + metric-adjusted fallback
Secondary/decorative font	font-display: optional, no preload
Animated GIF in page	replace per animated-media.md, reduced-motion fallback

Order of work: LCP candidate → oversized above-fold assets → video/GIF byte hogs → fonts → below-fold rasters → SEO/social images. Details and rationale: delivery-strategy.md.

Done when: every qualifying asset has a matrix row and the LCP candidate is identified (or its absence stated).

Step 4 — Plan per-type transforms

Dispatch per type; read the reference file before planning that type:

• Raster images → sharp-cli.md + generate-sharp-plan.py. Default format policy unless the project constrains otherwise: photos AVIF + WebP + JPEG fallback; UI screenshots WebP + PNG when lossless detail matters; transparent rasters WebP/AVIF with PNG fallback; logos/icons stay SVG; Open Graph/social images JPEG/PNG at platform dimensions.
• Video → video.md + generate-ffmpeg-plan.py (MP4 + WebM + poster).
• GIF/animated → animated-media.md + generate-ffmpeg-plan.py.
• Fonts → fonts.md (WOFF2 conversion, subsetting, display strategy).
• SVG → svg.md (SVGO plan, delivery method).

Done when: each matrix row has planned commands or a stated no-op reason.

Step 5 — Generate into final paths

Review the generated command plans, then run them. Target final kept paths (avoid --out-dir unless you will move winners into final paths and delete the temp dir before finishing). Produce only variants the app will reference; delete ffmpeg pass logs.

Done when: optimized files exist at final paths for every planned row and no temp output or log remains.

Step 6 — Replace references

Apply the matrix's loading policy while patching markup. Before editing image markup, load responsive-images.md and apply every Core rule; for video/GIF markup follow video.md and animated-media.md; for @font-face/preload edits follow fonts.md; for priorities/preload/caching follow delivery-strategy.md.

Also update manifests, favicons, Open Graph, CSS url(...), MDX/Markdown, and structured data when they point at old files. Prefer framework-native patterns when the pipeline uses them.

Done when: no runtime reference still points at an unoptimized original that has a replacement, and every touched element carries the loading attributes its matrix row prescribes (or exceptions are documented).

Step 7 — Delete old assets

Remove unreferenced heavy originals (rasters, videos, GIFs, legacy font formats), unused generated variants, and any temp output directory. Keep SVG sources and any source files the user asked to retain.

Done when: the tree is clean — only referenced optimized assets, intentional vectors, and documented kept sources remain.

Step 8 — Re-scan and verify cleanliness

Rerun scan-assets.py. Confirm optimized references are in place, no orphaned heavy assets remain, and no legacy font formats are still shipped.

Done when: the rescan matches the clean bar above.

Step 9 — Verify and report

Check desktop/mobile render, sensible srcset picks, video plays with correct source order and poster, autoplay loops are muted + playsinline, fonts render without layout jumps, no CLS from missing dimensions, LCP not lazy-loaded, and the build passes with the project's existing commands. Compare bytes before/after per type.

Done when: validation notes are recorded and the report below is filled.

Output format

## Web assets optimization summary

- Framework/pipeline detected: <framework and asset tooling>
- Assets scanned: <count> (<images/videos/GIFs/fonts/SVG counts>); bytes before → after: <totals>
- LCP candidate: <asset and treatment>
- Highest-priority fixes: <short list>

## Strategy matrix

| Asset | Type | Role | Placement | Action | Loading policy |
| --- | --- | --- | --- | --- | --- |
| ... | ... | ... | ... | ... | ... |

## Changes made

- <source asset> → <optimized replacements in final paths>
- <reference file> → <old path replaced with optimized markup>
- Deleted: <old assets, temp folders, unused variants, pass logs>

## Validation

- <commands or manual checks>
- Scanner rerun: <clean confirmation or documented exceptions>

## Notes / follow-ups

- <remote assets, CMS/CDN settings, caching headers, visual QA needs>

Reference files

• delivery-strategy.md — LCP, fetchpriority, lazy loading, preload/preconnect, content-visibility, CLS, caching, measurement.
• responsive-images.md — img, picture, srcset, sizes, LCP images, accessibility, SEO.
• video.md — codecs, ffmpeg recipes, posters, <video> markup, lazy patterns, streaming decision.
• animated-media.md — GIF replacement with video or animated WebP/AVIF, reduced motion.
• fonts.md — WOFF2, subsetting, font-display, preload, fallback metrics, variable fonts.
• svg.md — SVGO, delivery trade-offs, currentColor.
• sharp-cli.md — Sharp CLI commands, quality table, naming, conversion policy.
• frameworks.md — Next.js, React/Vite, Astro, SvelteKit, Nuxt asset/font/video handling, CDN constraints.