What is the web performance skill?
The web performance skill is a SKILL.md in web-quality-skills. It tells an AI coding agent to build a field-plus-lab baseline, change only code tied to a measured bottleneck, and report before and after numbers. It carries a starting budget, TTFB and compression rules, image and font guidance, caching headers and third-party script patterns.
This is the performance folder in addyosmani/web-quality-skills. It covers loading and runtime performance and uses field data from CrUX or first-party monitoring to rank user impact, then a DevTools trace to find causes.
The README names four kinds of evidence: CrUX field data, first-party real-user monitoring, a DevTools trace or Lighthouse lab run, and static source inspection. Its rule is that field data shows impact and lab traces explain it.
What changes in your agent's output
- The agent measures before it edits and re-runs an equivalent lab measurement after, then states conditions and uncertainty.
- Field verification is reported as pending until enough new user data arrives.
- Fixes target only the code and assets tied to a measured bottleneck.
- Images move to AVIF or WebP with responsive sizes, and the likely LCP image gets priority.
- Third-party scripts load with a strategy or a facade instead of blocking the page.
What the skill covers
The starting budget lists page weight under 1.5 MB, compressed JavaScript under 300 KB, CSS under 100 KB, above-the-fold images under 500 KB, fonts under 100 KB and third-party code under 200 KB. It calls these initial guardrails, not universal thresholds.
Other sections cover server response with a TTFB target under 800 ms, Brotli, HTTP/2 or HTTP/3 and Early Hints, plus fonts, cache headers, layout thrashing, list virtualization and View Transitions.
Who the web performance skill is for
Best for
- Pages that feel slow and need a ranked, evidence-backed fix list.
- Teams that want budgets and before and after numbers in every agent report.
- Pairing with core-web-vitals when the target is LCP, INP or CLS specifically.
Not for
- Guessing. The skill refuses to edit before a baseline exists when the page can run.
- Animation craft. For motion cost see fixing-motion-performance.
- Server tuning beyond headers and caching guidance.
Use it with UiChemy
A page generated by UiChemy lands in Elementor or Gutenberg, where weight comes from images, fonts and plugins. Run this skill on the live URL to find what is heavy, then fix it in the editor. Click Get Started on uichemy.com.
How to install Web Performance Skill: Measured Speed Fixes for AI Agents
git clone https://github.com/addyosmani/web-quality-skills.gitClone the repository
Run
git clone https://github.com/addyosmani/web-quality-skills.git. Each skill is a folder inside the skills directory, and performance is skills/performance.Copy the skill folder
Copy skills/performance into the folder where your agent loads skills, for one project or globally. The README's manual route copies the whole skills directory, which keeps the cross-links between the sibling skills working. Copy the folder as a whole, because SKILL.md links to references/MEASUREMENT.md for the measurement workflow.
Add live browser tools if you have them
The README says the skills prefer Chrome DevTools MCP for traces and Lighthouse runs when your agent exposes it. Without it they fall back to the Lighthouse CLI, PageSpeed Insights and manual checks.
Ask in plain words
Skills activate when your request matches their description, for example by asking for a quality review of a page.
Check that it loaded
Ask the agent to speed up one page. It should first record a field-plus-lab baseline, target only the measured bottleneck, and report before and after values with the test conditions.
Key features
- Field-plus-lab baselineThe agent reads references/MEASUREMENT.md and records a baseline before editing when a page can run.
- Starting performance budgetA table of limits for total weight, JavaScript, CSS, above-fold images, fonts and third-party code, marked as initial guardrails.
- Server response rulesTTFB under 800 ms, Brotli preferred over gzip, HTTP/2 or HTTP/3, edge caching and Early Hints when a trace shows slow HTML.
- Image optimizationA format table covering AVIF, WebP, PNG and SVG, responsive images and priority for the LCP image.
- Font strategyLoading strategy, preloading critical fonts and variable fonts.
- CachingCache-Control header guidance and service worker caching.
- Runtime fixesAvoid layout thrashing, debounce expensive work, use requestAnimationFrame and virtualize long lists.
- View TransitionsA section on smoother navigations with the View Transitions API.
- Third-party controlLoad strategies and the facade pattern for heavy embeds.
- Metric interpretation tableSeparates field LCP, INP and CLS at p75 from lab values, and calls TBT a rough INP proxy rather than field INP.
Frequently asked questions
What is the web performance skill?
It is the performance folder of addyosmani/web-quality-skills. It guides an AI coding agent to measure with field and lab data, fix only measured bottlenecks, and report before and after results with conditions and uncertainty.
How do I install it without npx?
Clone the repository with git and copy skills/performance, or the entire skills directory, into the folder your agent reads for skills. Keep the references folder inside, since SKILL.md points to a measurement workflow file there.
What budget does it recommend?
Page weight under 1.5 MB, compressed JavaScript under 300 KB, compressed CSS under 100 KB, above-fold images under 500 KB, fonts under 100 KB and third-party code under 200 KB. The skill says to calibrate them to your devices, networks and pages.
Does it need Chrome DevTools MCP?
It prefers it for performance traces and CrUX context, but the README says the skills fall back to the Lighthouse CLI, PageSpeed Insights and CrUX tools, manual browser checks and static inspection instead of stopping.
What is the difference between field and lab data here?
Field data from CrUX or real-user monitoring shows how users experienced the page and decides priority. A lab trace reproduces one controlled session and explains the cause. The skill says a PerformanceObserver snippet in one browser is a lab observation.
How does it differ from the Core Web Vitals skill?
This skill is broad: server, images, fonts, caching, scripts and runtime work. core-web-vitals narrows to LCP, INP and CLS diagnosis. The web quality audit skill orchestrates both with accessibility and SEO.
What license does it use?
The repository and the SKILL.md frontmatter say MIT. The 37.7K install count on this page comes from a third-party skills listing and is not stated in the repository. The repository README and SKILL.md linked in the sources section are the authority for details.