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
npx skills add tech-leads-club/agent-skills --skill perf-web-optimization -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/perf-web-optimization/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/perf-web-optimization/
1Skills CLI (Vercel)
npx skills add tech-leads-club/agent-skills --skill perf-web-optimization -a codex2Manually: put the files in place
.agents/skills/perf-web-optimization/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add tech-leads-club/agent-skills --skill perf-web-optimization -a cursor2Manually: put the files in place
.cursor/skills/perf-web-optimization/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install tech-leads-club/agent-skills 'packages/skills-catalog/skills/(performance)/perf-web-optimization'2Manually: put the files in place
.github/skills/perf-web-optimization/SKILL.md1Skills CLI (Vercel)
npx skills add tech-leads-club/agent-skills --skill perf-web-optimization -a gemini-cli2Platform CLI
gemini skills install https://github.com/tech-leads-club/agent-skills --path 'packages/skills-catalog/skills/(performance)/perf-web-optimization'Manually: put the files in place
.devin/skills/perf-web-optimization/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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