Agent skill

perf-web-optimization

Optimize web performance: bundle size, images, caching, lazy loading, and overall page speed. Use when site is slow, reducing bundle size, fixing layout shifts, improving Time to Interactive, or optimizing for Lighthouse scores. Triggers on: web performance, bundle size, page speed, slow site, lazy loading. Do NOT use for Core Web Vitals-specific fixes (use core-web-vitals), running Lighthouse audits (use perf-lighthouse), or Astro-specific optimization (use perf-astro).

Stars 2,081
Forks 241

Install this agent skill to your Project

npx add-skill https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(performance)/perf-web-optimization

SKILL.md

Web Performance Optimization

Systematic approach: Measure → Identify → Prioritize → Implement → Verify.

Target Metrics

Metric Good Needs Work Poor
LCP < 2.5s 2.5-4s > 4s
INP < 200ms 200-500ms > 500ms
CLS < 0.1 0.1-0.25 > 0.25
TTFB < 800ms 800ms-1.8s > 1.8s

Quick Wins

1. Images (usually biggest impact on LCP)

html
<!-- Hero/LCP image: eager + high priority -->
<img src="/hero.webp" alt="Hero" width="1200" height="600" loading="eager" fetchpriority="high" decoding="async" />

<!-- Below fold: lazy load -->
<img src="/product.webp" alt="Product" width="400" height="300" loading="lazy" decoding="async" />

Always set width and height to prevent CLS.

2. Fonts (common LCP/CLS culprit)

html
<!-- Preconnect to font origin -->
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />

<!-- Non-blocking font load -->
<link
  rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Inter&display=swap"
  media="print"
  onload="this.media='all'"
/>

3. Third-party Scripts (common INP killer)

html
<!-- Defer to user interaction -->
<script>
  function loadThirdParty() {
    // Load analytics, chat widgets, etc.
  }
  ;['scroll', 'click', 'touchstart'].forEach((e) => addEventListener(e, loadThirdParty, { once: true, passive: true }))
  setTimeout(loadThirdParty, 5000)
</script>

4. Critical CSS

Inline critical CSS in <head>, defer the rest:

html
<style>
  /* critical styles */
</style>
<link rel="preload" href="/styles.css" as="style" onload="this.rel='stylesheet'" />

Bundle Analysis

bash
# Webpack
npx webpack-bundle-analyzer dist/stats.json

# Vite
npx vite-bundle-visualizer

# Check package size before installing
npx bundlephobia <package-name>

Common heavy packages to replace:

  • moment (67KB) → date-fns (12KB) or dayjs (2KB)
  • lodash (72KB) → cherry-pick imports or native methods

Code Splitting Patterns

javascript
// React lazy
const Chart = lazy(() => import('./Chart'))

// Next.js dynamic
const Admin = dynamic(() => import('./Admin'), { ssr: false })

// Vite/Rollup manual chunks
build: {
  rollupOptions: {
    output: {
      manualChunks: {
        vendor: ['react', 'react-dom']
      }
    }
  }
}

Caching Headers

# Static assets (immutable hash in filename)
Cache-Control: public, max-age=31536000, immutable

# HTML (revalidate)
Cache-Control: no-cache

# API responses
Cache-Control: private, max-age=0, must-revalidate

Measurement

For running audits, reading reports, and setting budgets, use the perf-lighthouse skill.

Checklist

Images

  • Modern formats (WebP/AVIF)
  • Responsive srcset
  • width/height attributes
  • loading="lazy" below fold
  • fetchpriority="high" on LCP image

JavaScript

  • Bundle < 200KB gzipped
  • Code splitting by route
  • Third-party scripts deferred
  • No unused dependencies

CSS

  • Critical CSS inlined
  • Non-critical CSS deferred
  • No unused CSS

Fonts

  • font-display: swap
  • Preconnect to font origin
  • Subset if possible

Detailed Examples

For in-depth optimization patterns, see:

  • references/core-web-vitals.md - Fixing LCP, CLS, INP issues
  • references/bundle-optimization.md - Reducing JS bundle size
  • references/image-optimization.md - Image formats, responsive images, sharp scripts

Expand your agent's capabilities with these related and highly-rated skills.

tech-leads-club/agent-skills

seo

Optimize for search engine visibility and ranking. Use when asked to "improve SEO", "optimize for search", "fix meta tags", "add structured data", "sitemap optimization", or "search engine optimization". Do NOT use for accessibility (use web-accessibility), performance (use core-web-vitals), or comprehensive site audits covering multiple areas (use web-quality-audit).

2,081 241
Explore
tech-leads-club/agent-skills

web-quality-audit

Comprehensive web quality audit covering performance, accessibility, SEO, and best practices in a single review. Use when asked to "audit my site", "review web quality", "run lighthouse audit", "check page quality", or "optimize my website" across multiple areas at once. Orchestrates specialized skills for depth. Do NOT use for single-area audits — prefer core-web-vitals, web-accessibility, seo, or web-best-practices for focused work.

2,081 241
Explore
tech-leads-club/agent-skills

accessibility

Audit and improve web accessibility following WCAG 2.1 guidelines. Use when asked to "improve accessibility", "a11y audit", "WCAG compliance", "screen reader support", "keyboard navigation", or "make accessible". Do NOT use for SEO (use seo), performance (use core-web-vitals), or comprehensive site audits covering multiple areas (use web-quality-audit).

2,081 241
Explore
tech-leads-club/agent-skills

react-best-practices

React and Next.js performance optimization guidelines from Vercel Engineering. Use when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements. Do NOT use for component API architecture or composition patterns (use react-composition-patterns instead).

2,081 241
Explore
tech-leads-club/agent-skills

best-practices

Apply modern web development best practices for security, compatibility, and code quality. Use when asked to "apply best practices", "security audit", "modernize code", "code quality review", or "check for vulnerabilities". Do NOT use for accessibility (use web-accessibility), SEO (use seo), performance (use core-web-vitals), or comprehensive multi-area audits (use web-quality-audit).

2,081 241
Explore
tech-leads-club/agent-skills

perf-lighthouse

Run Lighthouse audits locally via CLI or Node API, parse and interpret reports, and set performance budgets. Use when measuring site performance, understanding Lighthouse scores, setting up budgets, or integrating audits into CI. Triggers on: lighthouse, run lighthouse, lighthouse score, performance audit, performance budget. Do NOT use for fixing specific performance issues (use perf-web-optimization or core-web-vitals) or Astro-specific optimization (use perf-astro).

2,081 241
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results