Performance Optimization skill for Claude Code: measure, fix, verify, guard

Addy Osmani's skill that makes Claude measure before it optimizes, fix one bottleneck at a time, and revert changes that do not help.

Installs: 70.1K; on skills.sh
Stars: 112.6K; on GitHub
Files: 1; besides SKILL.md
Updated: Nov 2026; last repo commit

Claude follows a five-step loop: measure with real data, identify the actual bottleneck, fix that one thing, verify by measuring again, and guard against regression. A change that is neutral or worse is reverted. The SKILL.md says "Neutral" is a revert, not a keep.

It uses Core Web Vitals targets of LCP at 2.5 seconds or less, INP at 200 ms or less and CLS at 0.1 or less. It bundles one reference file, references/optimization-patterns.md, with worked fixes. It also links to a shared performance-checklist.md in the wider pack.

Good for

Developers chasing slow pages or Core Web Vitals scores
Backend developers fixing N+1 queries and slow endpoints
Teams adding performance checks to CI

Install performance-optimization

Claude Code

Copy this prompt.

Install the performance-optimization skill in Claude Code. Run this command:

/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

The skill links to ../../references/performance-checklist.md, which lives at the repo level in the pack.

From the project README. Source.

What's in the skill

When it loads

Optimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.

Sections in SKILL.md

Overview
When to Use
Core Web Vitals Targets
The Optimization Workflow
Step 1: Measure
Where to Start Measuring
Step 2: Identify the Bottleneck
Step 3: Fix the Bottleneck
Step 4: Verify (Keep or Revert)
Step 5: Guard Against Regression
See Also
Common Rationalizations
Red Flags
Verification

Key facts

Author: addyosmani (agent-skills pack)
Repository: addyosmani/agent-skills
Installs on skills.sh: 70,109 (2 Nov 2026)
GitHub stars (repo): 112,555 (2 Nov 2026)
License: MIT
Last commit (repo): 1 Nov 2026
What installs: SKILL.md and references/optimization-patterns.md (2 files); bundles no scripts. Links to a shared references/performance-checklist.md in the pack
Works in: Claude Code, Cursor, Codex, Copilot, Cline and more through the skills CLI; native Claude Code and Codex plugins
Needs: Tools you already use to measure (Lighthouse, DevTools, web-vitals); the pack for the checklist it links to
skills.sh audits: Gen Agent Trust Hub pass, Socket pass, Snyk pass

What it includes

Baseline with synthetic and real-user data
Claude uses Lighthouse or DevTools for controlled runs, and the web-vitals library or CrUX for real-user data. It can use Chrome DevTools MCP for traces.
Runs code · Step 1: Measure
Use the symptom to decide what to measure
Claude finds the real cause before changing anything.
Read · Step 2: Identify the bottleneck
One fix at a time, from a list of usual suspects
The list includes N+1 queries, unbounded fetching, ignored indexes, connection pool exhaustion, missing caching, images, re-renders and bundle size. Worked fixes are in references/optimization-patterns.md.
Try: “Our dashboard LCP is 4s. Profile it and fix the biggest bottleneck.”
Write · Step 3: Fix the bottleneck
Keep or revert based on a re-measure
Same conditions and budget as the baseline, one change at a time, and repeated runs to beat noise. Neutral or worse is reverted.
Runs code · Step 4: Verify
Budgets and CI checks
The skill gives example budgets and two CI commands: bundlesize and Lighthouse CI.
Runs code · Step 5: Guard against regression
LCP, INP and CLS thresholds
Good means LCP 2.5 s or less, INP 200 ms or less, CLS 0.1 or less.
Read · Core Web Vitals targets

From the official docs

Permissions

Low risk

The skill is instructions, but Claude may edit code and run npx commands that download and run npm packages. Review each command before you approve it.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It can run npx commands that download packages
The CI step uses npx bundlesize and npx --package=@lhci/cli lhci autorun. Check what Claude plans to run and which package it fetches.

Security advisories

No published security advisories as of Nov 2, 2026.

Technical details

Turning on read-only	The skill defines no read-only switch.
Talks to	npm registry, when npx downloads bundlesize or @lhci/cli
Scopes	Claude edits code and config to apply fixes Claude may run your tests, profilers and builds The SKILL.md gives npx commands for bundlesize and Lighthouse CI

Questions

What does the Performance Optimization skill do?

It makes Claude optimize with evidence. It measures a baseline, finds the real bottleneck, applies one fix, measures again and reverts anything that does not clearly help.

How do I install it?

Use the install box at the top of this page. It installs the whole agent-skills pack so the shared performance checklist the skill links to is included. A per-skill install leaves that folder out, per the README.

Does it need Lighthouse or Chrome?

It names Lighthouse, Chrome DevTools, the web-vitals library and CrUX as ways to measure. Chrome DevTools MCP is mentioned as one option for performance traces. The SKILL.md does not require any one of them.

Will it run anything on my machine?

Possibly. For CI checks it gives npx bundlesize and npx --package=@lhci/cli lhci autorun, and Claude may run your tests, builds and profilers. Read each command before you approve it.

Does it cover backend and database performance too?

Yes. It covers frontend, backend, queries and databases, including N+1 queries, pagination, indexes with EXPLAIN ANALYZE, connection pools and caching.

Does it work in Cursor, Codex or Copilot?

Yes. The README documents a Codex plugin, the skills CLI for 70+ agents including Cursor, and manual setup for Cursor and Copilot. The slash commands (/spec, /plan, /build and so on) are Claude Code commands and do not appear in Copilot, where you invoke skills by name. The README does not describe a Claude app install.

Is it safe to install?

It is low risk. The skill itself bundles no scripts. Claude may run npx commands that download and run npm packages, and it edits your code, so review commands and diffs, and work on a branch.

Information

updated Nov 2, 2026

Repository: addyosmani/agent-skills
Folder: skills/performance-optimization

addyosmani/agent-skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 3

addyosmani/agent-skills README · github.com
performance-optimization SKILL.md · github.com
github.com · github.com