# Perf > Audit performance — bundle size, image weight, render-blocking resources, and Core Web Vitals via PageSpeed - Skill: `surfrrosa/perf` (Agent Skill) - Install (CLI): `npx skillmds@latest add surfrrosa/perf` - Raw SKILL.md: https://api.skillmd.com/api/skills/surfrrosa/perf/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - Author: Surfrrosa (https://skillmd.com/u/surfrrosa) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/surfrrosa/perf --- # Performance Audit Analyze a project for performance problems that kill load times and conversions. Two modes: source analysis (what you can catch from code) and live analysis (what Google PageSpeed Insights sees). ## Sample output A successful run produces something like: ``` ## Performance Audit — marketing-site Stack: Next.js 16 ### Images (3.4MB total) - public/hero.png — 1.8MB PNG, should be WebP (~250KB) - public/team-photo.jpg — 920KB, unresponsive (no srcset) - 6 images below the fold loading eagerly (missing loading="lazy") ### JavaScript (480KB bundled) - src/components/Analytics.tsx — loads PostHog synchronously in ; should be async or deferred - 3 client components could be server components (no hooks, no event handlers) ### Fonts - Google Fonts missing &display=swap — invisible text during font load ### Caching & Compression - public/_headers missing — no long cache on static assets ### Summary - Critical: 2 (hero image weight, synchronous analytics) - Warning: 3 - Top priority: convert hero.png to WebP (saves ~1.5MB on first load) ``` ## Arguments The user may specify: - No args: audit current working directory (source only) - A project name or path (e.g., `myapp`, `marketing-site`) - `--live`: also hit PageSpeed Insights API for Core Web Vitals on the live URL - `--fix`: auto-fix safe categories - `all --live`: audit all web projects against their live URLs Parse the argument string. Examples: - `/perf` -- source audit on current project - `/perf myapp --live` -- source + PageSpeed for myapp - `/perf all --live` -- PageSpeed for all sites (skip source, just compare live scores) - `/perf myapp --fix` -- source audit + auto-fix for myapp ## Project Registry | Alias | Path | Live URL | Stack | |-------|------|----------|-------| | `myapp` | (add your projects here) | (add your projects here) | (add your projects here) | ## Source Audit ### Step 0: Detect the project 1. Resolve path from alias or cwd 2. Detect stack: Next.js, Astro, Flask/Jinja, static HTML 3. Read `CLAUDE.md` and build config (`next.config.*`, `astro.config.*`, `vite.config.*`) for relevant settings ### Step 1: Image Weight Images are the #1 cause of slow pages for most sites. Check thoroughly. #### 1a. Image formats Search `public/`, `static/`, `src/assets/`, `src/images/`, and any other asset directories for image files. - **Flag unoptimized formats:** `.png` and `.jpg`/`.jpeg` files that should likely be `.webp` or `.avif`. Exceptions: - Favicons (`favicon.ico`, `favicon.png`) -- these need broad format support - OG/social images -- some platforms don't support WebP in meta tags yet. Check on a case-by-case basis. - SVGs are fine as-is - **Flag oversized files:** Any image over 200KB. Any image over 500KB is critical. - **Count total image weight:** Sum all image file sizes in the project. Compare to a budget: - Under 1MB total: good - 1-3MB: warning - Over 3MB: critical #### 1b. Image optimization pipeline Check whether the project has an image optimization strategy: | Stack | What to check | |-------|---------------| | Next.js | Is `next/image` or `` used? Check for raw `` tags in components. `next/image` auto-optimizes. | | Astro | Is `astro:assets` or `` from `astro:assets` used? Check for raw `` tags. | | Flask/Jinja | No built-in optimization. Check for a build step (sharp, imagemin, squoosh) or CDN with transforms. | | Static HTML | Check for raw `` tags pointing to unoptimized files. | **Flag:** Raw `` tags pointing to large files when the framework provides an optimized alternative. #### 1c. Responsive images - Check `` tags for `srcset` and `sizes` attributes (or framework equivalents that generate them). - Check for images with fixed `width`/`height` in pixels that are larger than needed on mobile. - Above-the-fold hero images should have `loading="eager"` or `fetchpriority="high"`. All other images should have `loading="lazy"`. **Flag:** Large images without responsive variants, no lazy loading on below-fold images, no priority hints on hero images. ### Step 2: JavaScript Weight #### 2a. Bundle analysis For projects with a build step: | Stack | How to check | |-------|--------------| | Next.js | Look for `next build` output in `.next/` or run the build and check the output summary. Check for `@next/bundle-analyzer` in dependencies. | | Astro | Astro ships zero JS by default. Check for `client:*` directives -- each one adds a JS island. Count them. | | Vite | Check `dist/assets/` for JS file sizes after build. | | Static HTML | Count and size all `