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).
Best use case
perf-web-optimization is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
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).
Teams using perf-web-optimization should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/perf-web-optimization/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How perf-web-optimization Compares
| Feature / Agent | perf-web-optimization | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
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).
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# 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](references/core-web-vitals.md) - Fixing LCP, CLS, INP issues
- [references/bundle-optimization.md](references/bundle-optimization.md) - Reducing JS bundle size
- [references/image-optimization.md](references/image-optimization.md) - Image formats, responsive images, sharp scriptsRelated Skills
angular-performance
Angular performance: NgOptimizedImage, @defer, lazy loading, SSR. Trigger: When optimizing Angular app performance, images, or lazy loading.
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).
perf-astro
Astro-specific performance optimizations for 95+ Lighthouse scores. Covers critical CSS inlining, compression, font loading, and LCP optimization. Use when optimizing Astro site performance, improving Astro Lighthouse scores, or configuring astro-critters. Do NOT use for non-Astro sites (use perf-web-optimization or core-web-vitals) or running Lighthouse audits (use perf-lighthouse).
high-perf-browser
Optimize web performance through network protocols, resource loading, and browser rendering internals. Use when the user mentions "page load speed", "Core Web Vitals", "HTTP/2", "resource hints", "network latency", or "render blocking". Covers TCP/TLS optimization, caching strategies, WebSocket/SSE, and protocol selection. For UI visual performance, see refactoring-ui. For font loading, see web-typography.
perf-theory-tester
Use when running controlled perf experiments to validate hypotheses.
perf-profiler
Use when profiling CPU/memory hot paths, generating flame graphs, or capturing JFR/perf evidence.
perf-investigation-logger
Use when appending structured perf investigation notes and evidence.
perf-code-paths
Use when mapping code paths, entrypoints, and likely hot files before profiling.
perf-analyzer
Use when synthesizing perf findings into evidence-backed recommendations and decisions.
perf-theory-gatherer
Use when generating performance hypotheses backed by git history and code evidence.
cost-optimization
Optimize cloud costs through resource rightsizing, tagging strategies, reserved instances, and spending analysis. Use when reducing cloud expenses, analyzing infrastructure costs, or implementing c...
spark-optimization
Optimize Apache Spark jobs with partitioning, caching, shuffle optimization, and memory tuning. Use when improving Spark performance, debugging slow jobs, or scaling data processing pipelines.