Skill

web-performance

Audit and optimize Core Web Vitals (LCP, INP, CLS), bundle size, loading strategy, and rendering pipeline. Use when user asks to "optimize performance", "improve Core Web Vitals", "reduce bundle size", or "fix slow page load".

From sovereign-architect

Install

Run in your terminal

npx claudepluginhub javimontano/mao-sovereign-architect

Tool Access

This skill is limited to using the following tools:

ReadWriteEditGlobGrepBashAgent

Supporting Assets

View in Repository

agents/bundle-analyzer-agent.md

agents/loading-strategy-agent.md

agents/web-performance-agent.md

evals/evals.json

examples/sample-output.md

prompts/use-case-prompts.md

references/body-of-knowledge.md

references/knowledge-graph.mmd

references/state-of-the-art.md

Skill Content

Web Performance

Systematically measure, diagnose, and optimize web application performance across loading, interactivity, and visual stability dimensions.

Guiding Principle

"Optimize what you measure, measure what matters to users. Core Web Vitals are user-experience metrics first, technical metrics second."

Procedure

Step 1 — Baseline Measurement [HECHO]

Run Chrome Lighthouse (mobile preset, 4x CPU throttle, Slow 4G network) on production URL.
Record CWV scores: LCP, INP, CLS — note actual values, not just Pass/Fail.

Run web-vitals JS library in production with real user monitoring (RUM):

import { onLCP, onINP, onCLS } from 'web-vitals';
onLCP(console.log); onINP(console.log); onCLS(console.log);

Check PageSpeed Insights for field data (CrUX — real users, 28-day rolling).
Profile bundle: npx webpack-bundle-analyzer dist/stats.json or Vite's --analyze.
Tag all measurements as [HECHO] with timestamp and test conditions.

CWV Thresholds (Good / Needs Improvement / Poor):

Metric	Good	Needs Improvement	Poor
LCP (Largest Contentful Paint)	≤ 2.5s	2.5–4.0s	> 4.0s
INP (Interaction to Next Paint)	≤ 200ms	200–500ms	> 500ms
CLS (Cumulative Layout Shift)	≤ 0.1	0.1–0.25	> 0.25
TTFB (Time to First Byte)	≤ 800ms	800–1800ms	> 1800ms
FCP (First Contentful Paint)	≤ 1.8s	1.8–3.0s	> 3.0s

Step 2 — LCP Optimization

Identify the LCP element: Lighthouse "LCP element" row shows which DOM node.
Eliminate render-blocking resources above the LCP element:
- Move non-critical CSS to <link rel="preload" as="style">
- Remove render-blocking scripts from <head>

Preload the LCP resource:

<link rel="preload" as="image" href="/hero.webp" fetchpriority="high">

Remove loading="lazy" from LCP image — it delays discovery.
Optimize LCP image: compress to WebP/AVIF, serve correct size via srcset.
Reduce TTFB: upgrade hosting, add CDN, enable HTTP/3, implement server-side caching.
Inline critical CSS for above-fold content (< 14 KB gzipped).

Step 3 — INP Reduction

Profile interactions: Chrome DevTools Performance panel → Record → Click/type → look for long tasks.
Break up long tasks: any task > 50ms blocks the main thread. Use scheduler.yield() or setTimeout(0).
Defer non-critical JS: <script defer> or <script type="module">.
Reduce JavaScript parse/compile time: smaller bundles = faster parse.
Virtualize long lists: use @tanstack/react-virtual or similar — never render 1000+ DOM nodes.
Debounce/throttle input handlers: scroll, resize, mousemove events should never fire sync heavy work.
Move heavy work to Web Workers: new Worker('/worker.js') for CPU-intensive operations.

// Break up long task with scheduler.yield()
async function processLargeDataset(items) {
  for (let i = 0; i < items.length; i++) {
    processItem(items[i]);
    if (i % 50 === 0) await scheduler.yield(); // yield every 50 items
  }
}

Step 4 — CLS Prevention

Set explicit dimensions on images and video:

<img src="photo.jpg" width="800" height="600" alt="...">

Reserve space for dynamic content (ads, embeds, lazy-loaded content):
```
.ad-slot { min-height: 250px; }
```
Avoid inserting content above existing content except on user interaction.
Use transform for animations instead of top/left/width/height — transforms don't trigger layout.
Web fonts: use font-display: optional or size-adjust to prevent layout shift from font swap.
Measure CLS by element: Lighthouse shows contributing elements with their score contribution.

Step 5 — Bundle Analysis and Code Splitting

Generate bundle stats: vite build --analyze or webpack --profile --json > stats.json.
Identify chunks > 100 KB (uncompressed). Investigate each.

Implement route-based code splitting:

// React Router / Next.js
const Dashboard = lazy(() => import('./pages/Dashboard'));

Tree-shake unused exports — ensure all imports use named exports, not import *.
Replace heavy dependencies with lighter alternatives:
- moment.js → date-fns (modular, tree-shakeable)
- lodash → native ES2025 or lodash-es
- axios → fetch + ky for interceptors
Implement modulepreload for next-likely routes.

Step 6 — Loading Strategy

Critical path: HTML → Critical CSS (inline) → Render. Nothing else before first paint.
Resource hints:
- <link rel="preconnect"> for third-party origins (fonts, APIs, CDN)
- <link rel="dns-prefetch"> for domains you'll need later
- <link rel="preload"> for critical resources needed in < 3 seconds
- <link rel="prefetch"> for resources needed on next navigation
Script loading strategy:
- type="module" — deferred, modern browsers only
- defer — deferred, good for legacy support
- async — for analytics, ads (not render-critical)
Service Worker caching strategy: Cache-first for static assets, Network-first for API.

Step 7 — Verification

Re-run Lighthouse — compare before/after scores.
Check CWV with PageSpeed Insights (field data takes 28 days to update).
Run performance budget check in CI: fail build if bundle exceeds threshold.
Add web-vitals reporting to production monitoring dashboard.

Decision Framework

What to Optimize First

LCP > 4s	Fix TTFB, preload LCP image, eliminate render-blocking resources
INP > 500ms	Profile long tasks, defer JS, virtualize lists
CLS > 0.25	Add dimensions to images, reserve space for dynamic content
Bundle > 500KB	Code splitting, tree shaking, dependency audit
TTFB > 1800ms	CDN, server caching, Edge rendering, database query optimization

Caching Strategy by Resource Type

Resource	Cache Strategy	Max-Age
HTML	No-cache (revalidate)	0
CSS/JS with hash	Cache-first	1 year
Images	Cache-first	30 days
API responses	Stale-while-revalidate	Per endpoint
Fonts	Cache-first	1 year

Anti-Patterns

loading="lazy" on LCP image — Delays discovery by the browser's preload scanner. LCP images must be eager.
Inlining all CSS to avoid render-blocking — Bloats HTML, kills CDN caching. Only inline critical CSS (above-fold).
preload everything — Creates bandwidth contention. Preload only 1-3 critical resources per page.
Synchronous localStorage access in render path — Blocks the main thread. Move to async storage (IndexedDB) or cache in memory.
requestAnimationFrame for non-visual work — rAF fires at 60fps = every 16ms. Use setTimeout or Workers for non-visual tasks.
Optimizing lab score, ignoring field data — Lighthouse is synthetic. CrUX field data represents real users. Both matter.
Ignoring third-party script impact — Tag managers, chat widgets, and ads regularly contribute 1-2s to LCP. Audit and lazy-load.

Output Artifacts

performance-audit-{date}.md — Baseline measurement report
performance-budget.json — Bundle size and CWV thresholds for CI
src/workers/heavy-task.worker.ts — Web Worker for CPU-intensive work
ADR-PERF-001.md — Performance architecture decisions

Similar Skills

agent-harness-construction

Designs and optimizes AI agent action spaces, tool definitions, observation formats, error recovery, and context for higher task completion rates.

everything-claude-code

138.0k

agent-payment-x402

Enables AI agents to execute x402 payments with per-task budgets, spending controls, and non-custodial wallets via MCP tools. Use when agents pay for APIs, services, or other agents.

everything-claude-code

138.0k

agent-eval

Compares coding agents like Claude Code and Aider on custom YAML-defined codebase tasks using git worktrees, measuring pass rate, cost, time, and consistency.

everything-claude-code

138.0k

Stats

Stars0

Forks0

Last CommitMar 28, 2026

Actions

View Source View Plugin View on GitHub View README

Web Performance

Systematically measure, diagnose, and optimize web application performance across loading, interactivity, and visual stability dimensions.

Guiding Principle

"Optimize what you measure, measure what matters to users. Core Web Vitals are user-experience metrics first, technical metrics second."

Procedure

Step 1 — Baseline Measurement [HECHO]

Run Chrome Lighthouse (mobile preset, 4x CPU throttle, Slow 4G network) on production URL.
Record CWV scores: LCP, INP, CLS — note actual values, not just Pass/Fail.

Run web-vitals JS library in production with real user monitoring (RUM):

import { onLCP, onINP, onCLS } from 'web-vitals';
onLCP(console.log); onINP(console.log); onCLS(console.log);

Check PageSpeed Insights for field data (CrUX — real users, 28-day rolling).
Profile bundle: npx webpack-bundle-analyzer dist/stats.json or Vite's --analyze.
Tag all measurements as [HECHO] with timestamp and test conditions.

CWV Thresholds (Good / Needs Improvement / Poor):

Metric	Good	Needs Improvement	Poor
LCP (Largest Contentful Paint)	≤ 2.5s	2.5–4.0s	> 4.0s
INP (Interaction to Next Paint)	≤ 200ms	200–500ms	> 500ms
CLS (Cumulative Layout Shift)	≤ 0.1	0.1–0.25	> 0.25
TTFB (Time to First Byte)	≤ 800ms	800–1800ms	> 1800ms
FCP (First Contentful Paint)	≤ 1.8s	1.8–3.0s	> 3.0s

Step 2 — LCP Optimization

Identify the LCP element: Lighthouse "LCP element" row shows which DOM node.
Eliminate render-blocking resources above the LCP element:
- Move non-critical CSS to <link rel="preload" as="style">
- Remove render-blocking scripts from <head>

Preload the LCP resource:

<link rel="preload" as="image" href="/hero.webp" fetchpriority="high">

Remove loading="lazy" from LCP image — it delays discovery.
Optimize LCP image: compress to WebP/AVIF, serve correct size via srcset.
Reduce TTFB: upgrade hosting, add CDN, enable HTTP/3, implement server-side caching.
Inline critical CSS for above-fold content (< 14 KB gzipped).

Step 3 — INP Reduction

Profile interactions: Chrome DevTools Performance panel → Record → Click/type → look for long tasks.
Break up long tasks: any task > 50ms blocks the main thread. Use scheduler.yield() or setTimeout(0).
Defer non-critical JS: <script defer> or <script type="module">.
Reduce JavaScript parse/compile time: smaller bundles = faster parse.
Virtualize long lists: use @tanstack/react-virtual or similar — never render 1000+ DOM nodes.
Debounce/throttle input handlers: scroll, resize, mousemove events should never fire sync heavy work.
Move heavy work to Web Workers: new Worker('/worker.js') for CPU-intensive operations.

// Break up long task with scheduler.yield()
async function processLargeDataset(items) {
  for (let i = 0; i < items.length; i++) {
    processItem(items[i]);
    if (i % 50 === 0) await scheduler.yield(); // yield every 50 items
  }
}

Step 4 — CLS Prevention

Set explicit dimensions on images and video:

<img src="photo.jpg" width="800" height="600" alt="...">

Reserve space for dynamic content (ads, embeds, lazy-loaded content):
```
.ad-slot { min-height: 250px; }
```
Avoid inserting content above existing content except on user interaction.
Use transform for animations instead of top/left/width/height — transforms don't trigger layout.
Web fonts: use font-display: optional or size-adjust to prevent layout shift from font swap.
Measure CLS by element: Lighthouse shows contributing elements with their score contribution.

Step 5 — Bundle Analysis and Code Splitting

Generate bundle stats: vite build --analyze or webpack --profile --json > stats.json.
Identify chunks > 100 KB (uncompressed). Investigate each.

Implement route-based code splitting:

// React Router / Next.js
const Dashboard = lazy(() => import('./pages/Dashboard'));

Tree-shake unused exports — ensure all imports use named exports, not import *.
Replace heavy dependencies with lighter alternatives:
- moment.js → date-fns (modular, tree-shakeable)
- lodash → native ES2025 or lodash-es
- axios → fetch + ky for interceptors
Implement modulepreload for next-likely routes.

Step 6 — Loading Strategy

Critical path: HTML → Critical CSS (inline) → Render. Nothing else before first paint.
Resource hints:
- <link rel="preconnect"> for third-party origins (fonts, APIs, CDN)
- <link rel="dns-prefetch"> for domains you'll need later
- <link rel="preload"> for critical resources needed in < 3 seconds
- <link rel="prefetch"> for resources needed on next navigation
Script loading strategy:
- type="module" — deferred, modern browsers only
- defer — deferred, good for legacy support
- async — for analytics, ads (not render-critical)
Service Worker caching strategy: Cache-first for static assets, Network-first for API.

Step 7 — Verification

Re-run Lighthouse — compare before/after scores.
Check CWV with PageSpeed Insights (field data takes 28 days to update).
Run performance budget check in CI: fail build if bundle exceeds threshold.
Add web-vitals reporting to production monitoring dashboard.

Decision Framework

What to Optimize First

LCP > 4s	Fix TTFB, preload LCP image, eliminate render-blocking resources
INP > 500ms	Profile long tasks, defer JS, virtualize lists
CLS > 0.25	Add dimensions to images, reserve space for dynamic content
Bundle > 500KB	Code splitting, tree shaking, dependency audit
TTFB > 1800ms	CDN, server caching, Edge rendering, database query optimization

Caching Strategy by Resource Type

Resource	Cache Strategy	Max-Age
HTML	No-cache (revalidate)	0
CSS/JS with hash	Cache-first	1 year
Images	Cache-first	30 days
API responses	Stale-while-revalidate	Per endpoint
Fonts	Cache-first	1 year

Anti-Patterns

loading="lazy" on LCP image — Delays discovery by the browser's preload scanner. LCP images must be eager.
Inlining all CSS to avoid render-blocking — Bloats HTML, kills CDN caching. Only inline critical CSS (above-fold).
preload everything — Creates bandwidth contention. Preload only 1-3 critical resources per page.
Synchronous localStorage access in render path — Blocks the main thread. Move to async storage (IndexedDB) or cache in memory.
requestAnimationFrame for non-visual work — rAF fires at 60fps = every 16ms. Use setTimeout or Workers for non-visual tasks.
Optimizing lab score, ignoring field data — Lighthouse is synthetic. CrUX field data represents real users. Both matter.
Ignoring third-party script impact — Tag managers, chat widgets, and ads regularly contribute 1-2s to LCP. Audit and lazy-load.

Output Artifacts

performance-audit-{date}.md — Baseline measurement report
performance-budget.json — Bundle size and CWV thresholds for CI
src/workers/heavy-task.worker.ts — Web Worker for CPU-intensive work
ADR-PERF-001.md — Performance architecture decisions