Source: addyosmani/agent-skills · Maintainer: community: Addy Osmani · License: MIT · Checked: 24 October 2026
What is the performance-optimization skill?
The performance-optimization skill makes Claude Code and other coding agents treat speed work as an experiment: take a baseline, find the actual bottleneck, change one thing, measure again the same way, and throw the change away if it didn't beat the noise. It is for developers who want an agent to fix slow pages, endpoints and queries without piling on "optimizations" nobody measured.
It comes from addyosmani/agent-skills, Addy Osmani's MIT-licensed set of 25 engineering skills. The skill's description reads: "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."
It is the fourth most installed skill in the repo. As of 24 October 2026, its skills.sh page listed 63.9K installs (snapshot, 24 October 2026), with Pass results from all three security audits shown (Gen Agent Trust Hub, Socket and Snyk).
What does it do?
The SKILL.md opens with its rule: "Measure before optimizing." It also says when not to use it: "Don't optimize before you have evidence of a problem."
The workflow has five steps:
- Measure. Use both synthetic data (Lighthouse, the DevTools Performance tab) and real user data (the
web-vitalslibrary, CrUX). Synthetic runs catch regressions in CI; field data proves a fix helped real users. - Identify. A decision tree starts from the symptom: slow first load, sluggish interaction, slow page after navigation, or a slow API. Tables map symptoms to likely causes, for example poor INP to heavy JavaScript on the main thread, or memory growth to leaked references and unbounded caches.
- Fix. "Fix the one thing Step 2 identified, nothing else." Each common anti-pattern gets a rule and a link to a worked fix.
- Verify. Re-measure with the same command and conditions, change one thing at a time, and compare the gain against run-to-run variance. A result inside the noise, a worse result, or a win that turned a test red all mean revert.
- Guard. Protect the metric users feel with a synthetic budget in CI and field monitoring on p75 movement.
The Core Web Vitals targets in the skill (LCP 2.5s or less, INP 200ms or less, CLS 0.1 or less for "Good") match Google's Web Vitals guidance, which measures them at the 75th percentile of page loads.
The anti-patterns it covers:
| Area | Anti-pattern | The skill's rule, in short |
|---|---|---|
| Backend | N+1 queries | Fetch the relation in the same query, not in a loop |
| Backend | Unbounded fetching | Every list endpoint paginates with a limit and stable order |
| Database | Query ignores its index | Read EXPLAIN ANALYZE before and after; an index that doesn't change the plan is a revert |
| Backend | Pool exhaustion | One pool per process; use a proxy like pgbouncer for serverless instead of raising max |
| Backend | Missing caching | Cache only what is expensive and read far more than written; every input that changes the response goes in the key |
| Frontend | Unoptimized images | Width and height on every image, fetchpriority="high" on the LCP image, lazy loading below the fold |
| Frontend | Re-renders | Hoist constants; use React.memo and useMemo only where the profile shows cost |
| Frontend | Large bundles | Route-level code splitting and lazy loading heavy features |
Two ideas stand out. First, "'Neutral' is a revert, not a keep": the skill argues that unmeasured changes add complexity forever. Second, it asks for a ledger of every attempt, kept or reverted, in the PR description or a PERF.md, so the next person or agent doesn't rerun an idea that already failed.
It also suggests starting budgets (for example under 200KB of gzipped JavaScript on initial load, API p95 under 200ms, Lighthouse performance score of 90 or more) and enforcing them in CI with npx bundlesize and npx lhci autorun.
What's in the folder:
SKILL.md: the workflow, decision tree, rules, rationalizations, red flags and checklist.references/optimization-patterns.md: worked code for each anti-pattern, opened only when the agent reaches that kind of code.
The skill also points to references/performance-checklist.md at the repo root, with a TTFB diagnosis, frontend and backend checklists, caching strategies such as request coalescing and negative caching, and measurement commands. That file is outside the skill folder.
How do you install the performance optimization skill?
Whole set as a Claude Code plugin. From the README:
/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills
This brings every skill, the shared checklists, four agent personas and nine slash commands, including /webperf. Plugin skills are namespaced as /plugin-name:skill-name per the Claude Code skills docs, so this one is /agent-skills:performance-optimization. If the marketplace step fails over SSH, the README gives the HTTPS form: /plugin marketplace add https://github.com/addyosmani/agent-skills.git.
Just this skill. The command on skills.sh, using the skills CLI:
npx skills add https://github.com/addyosmani/agent-skills --skill performance-optimization
Add -g for all projects. The folder, including its own references/optimization-patterns.md, lands in .claude/skills/performance-optimization/, or ~/.claude/skills/performance-optimization/ with -g. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills.
The README's warning applies here: a per-skill install "copies only skills/<name>/, not the repo-level references/ directory." The skill's own patterns file comes along, but its link to performance-checklist.md breaks. Use the plugin, or copy that checklist into the installed skill's references/ folder.
How do you use it?
The skill loads when a task mentions slowness, Core Web Vitals, N+1 queries or profiling. Give it a symptom and, if you have one, a number.
Example prompts (suggestions, not quotes from the repo):
The product page LCP is 4.1s on mobile. Use the performance-optimization skill: baseline first, then find the bottleneck.GET /api/orders got slow after last week's release. Profile it and check for N+1 queries.This query takes 900ms. Run EXPLAIN ANALYZE and tell me whether an index would actually help.Typing in the search box lags. Profile the main thread and fix only what the trace shows.Add a bundle size budget and Lighthouse CI to our pipeline so regressions fail the build.
With the plugin installed, /webperf runs the repo's web-performance-auditor persona. Its command file says it runs in Deep mode when you give it a Lighthouse JSON report, PageSpeed Insights or CrUX data, a DevTools trace, or a live URL with the Chrome DevTools MCP server, and in Quick mode otherwise, where it scans source code and labels each finding as "potential impact".
Requirements: no API keys or scripts in the skill. To measure, the agent needs whatever tools fit the job: a browser with DevTools or Lighthouse, your database's query plan output, or your APM. Without real measurements the skill's own rules say not to optimize.
Tips and limits
From the files, not from testing:
- Expect reverts. The keep-or-revert table is strict: within noise, worse, or a red test all mean revert. That is the point, but it can feel slow.
- Node and Postgres flavored. Backend examples use JavaScript timing,
EXPLAIN ANALYZEand pgbouncer. The ideas carry over; the commands may not. - React examples on the frontend. Re-render advice is about React. For other frameworks, the measure-first loop still applies.
- Budgets are starting points. The suggested numbers are defaults, not standards. Set your own in the spec if they differ.
- Measurement needs access. The skill wants both synthetic and field data. If you have no RUM or CrUX data for the page, say so, so the agent knows its baseline is synthetic only.
- No scripts. It runs nothing on its own; the agent runs your tools when you allow it.
- License. MIT, so you can fork and tune it as long as you keep the copyright notice.
Save it in your Kipt library
In Kipt, open Skills and paste the skill's GitHub folder link into the import box. Kipt reads the SKILL.md and its files, including optimization-patterns.md; for a repo with many skills it shows a list to pick from. You can also drop a folder or a .zip, which lets you add performance-checklist.md to the skill's references/ folder first so the link works. Your skills live in your own private GitHub repo and install into Claude Code or Codex with one command:
npx skills add https://github.com/<you>/<repo>.git --all -g
Kipt is not affiliated with Addy Osmani or addyosmani/agent-skills.
Similar skills
- Core Web Vitals skill: Addy Osmani's browser-focused skill for LCP, INP and CLS.
- Web performance skill: Cloudflare's web-perf skill for auditing page speed.
- Postgres best practices skill: Supabase's rules for indexes, pooling and locking.
- Frontend UI engineering skill: the same repo's skill for building the UI you will later measure.