Perf Audit

Performance Audit

Run Lighthouse against the project and fix performance issues.

Process

Step 1: Find the URL

• Check if dev server is running (try common ports: 3000, 5173, 4321, 8080)
• Check package.json scripts for dev/start commands
• Ask user for URL if not auto-detected
• If no server running, suggest starting one first

Step 2: Run Lighthouse

node ${CLAUDE_PLUGIN_ROOT}/tools/lighthouse-runner.mjs 

Parse JSON output for scores and opportunities.

Step 3: Report Scores & Core Web Vitals

Present all four Lighthouse scores:

• Performance (target 90+)
• Accessibility (target 90+)
• Best Practices (target 90+)
• SEO (target 100)

Report Core Web Vitals with targets:

• LCP (Largest Contentful Paint): target `: preload it, use WebP, add fetchpriority="high"
• If it's text: check web font loading, add font-display: swap
• If it's a background image: preload via ``

CLS too high? Check diagnostics for layout shift sources:

• Images without width/height → add dimensions (scanner already checks this)
• Dynamic content injected above fold → reserve space with CSS
• Web fonts causing FOUT → add font-display: optional or swap

Unused resources? Check wasted_resources:

• unused_js_kb > 100KB → code splitting or tree shaking needed
• unused_css_kb > 50KB → purge unused CSS (PurgeCSS, Tailwind purge)

Third-party scripts slow? Check third_party_impact:

• Analytics blocking >100ms → defer/async load
• Ad scripts blocking >200ms → lazy load below fold
• Chat widgets → load on user interaction, not page load

Step 5: Apply Fixes

For each opportunity, apply fixes using Edit tool:

Performance fixes (high impact first):

• Render-blocking resources → add defer or async to non-critical scripts
• Unused JavaScript → recommend code splitting, dynamic imports, tree shaking
• Unused CSS → recommend PurgeCSS or Tailwind purge config
• LCP image not preloaded → add ``
• Images not lazy-loaded → add loading="lazy" to below-fold images
• Images without dimensions → add width and height attributes
• No preconnect → add `` for external origins
• Font display → add font-display: swap to @font-face declarations
• Third-party scripts → defer non-essential scripts, lazy load on interaction

Accessibility fixes:

• Missing alt text (also caught by SEO scanner)
• Missing form labels → add `` elements
• Low contrast → adjust colors
• Missing landmark regions → add `, , `

Step 6: Graceful Degradation

• No Chrome: report "Chrome needed for Lighthouse. Install Chrome or Chromium."
• Lighthouse timeout: return partial results with warning
• No dev server: suggest starting one, or test against production URL

Key Principle

Fix, don't just audit. Identify the specific elements causing problems. Apply every automated fix possible. For build-tool changes (code splitting, tree shaking), provide exact config recommendations.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Houseofmvps
• Source: Houseofmvps/ultraship
• License: MIT
• Homepage: https://www.npmjs.com/package/ultraship

Install and usage instructions live in the source repository linked above.