Skip to main content
skill CX Codex

perf-web-optimization — Claude Code skill: what it does & setup

perf-web-optimization guides front-end performance tuning by shrinking JS bundles, deferring heavy scripts, and configuring cache headers. Best when pages load slowly or fail speed benchmarks.

MIT ★ 7,191 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add tech-leads-club/agent-skills --skill perf-web-optimization -a claude-code
Open on GitHub

What perf-web-optimization does

The skill establishes a practical tuning workflow: measure, identify, prioritize, implement, and verify. It targets core page metrics. Hero graphics get loading="eager" alongside fetchpriority="high", while images receive fixed width and height tags to prevent layout shifts. Analytics and third-party widgets are delayed until user touch or click events occur.

For JavaScript bundles, it helps swap bloated dependencies such as moment (67KB) for compact alternatives like dayjs (2KB) or date-fns (12KB). It supplies code-splitting conventions for React lazy and Next.js dynamic imports, as well as strict Cache-Control rules for versioned static assets.

This skill is not designed to execute audits or optimize Astro setups. Running audits requires perf-lighthouse, while framework-specific tuning for Astro relies on perf-astro.

What it helps with

  • trim JavaScript bundle size by replacing heavy libraries
  • prioritize hero image and font delivery to improve LCP
  • prevent layout shifts by enforcing explicit image dimensions
  • defer non-critical third-party scripts until user interaction
  • apply caching headers to static assets and dynamic API routes

Example prompts for the agent

  • Inspect package.json and suggest lightweight alternatives for bloated dependencies
  • Optimize the hero image and font loading strategy on the home page
  • Configure Cache-Control headers for static assets and API endpoints

How to install perf-web-optimization

1Skills CLI (Vercel)

npx skills add tech-leads-club/agent-skills --skill perf-web-optimization -a claude-code

2Manually: put the files in place

~/.claude/skills/perf-web-optimization/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/perf-web-optimization/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about perf-web-optimization

How do I install perf-web-optimization in Claude Code?

Run npx skills add tech-leads-club/agent-skills --skill perf-web-optimization -a claude-code.

What does perf-web-optimization do?

It guides code-level web tuning, covering image prioritization, script deferral, bundle minimization, and browser cache policies.

Can perf-web-optimization run automated Lighthouse audits?

No, running audits and analyzing report scores is delegated to the perf-lighthouse skill.

Source text

SKILL.md · MIT
---
name: perf-web-optimization
description: '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).'
---

# 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 scripts

© tech-leads-club · MIT · tech-leads-club/agent-skills

Similar skills

All skills for Frontend and UI →

From the same set130

The whole set →
docs-writer The docs-writer skill creates, edits, and reviews project documentation. Use it for READMEs, Markdown files, and pages under docs/. CX Codex +1 ★ 7,191repo stars perf-astro The perf-astro Claude Code skill tunes Astro builds with inlined critical CSS, minification, non-blocking fonts and an LCP preload, aiming for 95+ Lighthouse scores. CX Codex +1 ★ 7,191repo stars tactical-ddd Audits domain models for anemia and refactors them into rich aggregates using tactical DDD patterns in Claude Code. CX Codex +1 ★ 7,191repo stars nx-workspace nx-workspace — a skill for exploring an Nx monorepo from the CLI: list projects, read resolved config, find affected projects and wire affected commands into CI. CX Codex +1 ★ 7,191repo stars state-context-interface The state-context-interface rule separates a component’s UI from its state implementation with a context split into state, actions, and meta. Use it when the same UI needs to work with different providers. CX Codex +1 ★ 7,191repo stars learning-opportunities learning-opportunities adds optional 10–15 minute exercises to a Claude session, so the person who shipped the code can still explain how it works. CX Codex +1 ★ 7,191repo stars confluence-assistant confluence-assistant operates Confluence spaces through Atlassian MCP tools. Helps Claude Code search team documentation, create structured pages, and update existing entries using Markdown. CX Codex +1 ★ 7,191repo stars security-threat-model security-threat-model reads your repository and writes a threat model: trust boundaries, assets, realistic abuse paths and mitigations, saved as a Markdown file. CX Codex +1 ★ 7,191repo stars

Project sponsors

Companies that keep this analytics open