optimize-performance
Skill141 starsChanged 33 days agoUnlicenseView on GitHub
Make a page in this starter actually smooth — build it, scroll it in real Chrome on PC and on an emulated phone, fix what the measurement blames, re-measure to prove it. Covers first-scroll jank and micro-freezes, dropped frames during scroll-driven animation, blur/filter and layer-promotion cost, per-frame style writes, lazy media decoding mid-reveal, hydration and lazy chunks landing mid-scroll, the first scroll after a loader, image sequences, INP and bundle cost. Use when the user says "it's slow", "janky", "micro freezes", "stutters on first scroll", "laggy scrolling", "optimise performance", "measure performance", or before shipping any animation-heavy page. For a three.js/WebGL scene use `optimize-3d-scene` first — that skill owns the GPU scene; this one owns the page around it. For load scores use `optimize-load`; for real-phone behaviour use `mobile-device-qa`.
7 other projects use a version of this.
Adopted by
Most recently taken up by
- wollemiahq/skillstheir own version, first seen Nov 1, 2026
- VelimirMueller/ai-development-skillstheir own version, first seen Oct 25, 2026
- VelimirMueller/claude-skillstheir own version, first seen Oct 11, 2026
- maksimzayats/diwiretheir own version, first seen Oct 8, 2026
- emaraschio/cursor-commandstheir own version, first seen Aug 7, 2026
- igmarin/rails-agent-skillstheir own version, first seen Jul 30, 2026
Other versions7 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 7
- maksimzayats/diwire★ 254same name
- igmarin/rails-agent-skills★ 26same name
- emaraschio/cursor-commands★ 9same name
- VelimirMueller/ai-development-skills★ 7same name
- VelimirMueller/claude-skills★ 7same name
- wollemiahq/skills★ 2same name
- gologo13/agent-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository20 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- aeo-visibilitySkill
- figma-to-sectionSkill
- i18n-seoSkill
- local-seoSkill
- mobile-device-qaSkill
- optimize-3d-sceneSkill
- optimize-loadSkill
- payload-adminSkill
- payload-analyticsSkill
- payload-cmsSkill
- qa-verifySkill
- schema-markupSkill
- seo-auditSkill
- seo-growSkill
- ship-checkSkill
- site-migrationSkill
- supabase-authSkill
- supabase-dbSkill
The file
We split this skill into the rules it gives an agent
8 rules. 0 are common, 3 are distinctive, and 5 are very specific to this project.
0
Common
Most of the 7 edited versions we read keep these.
3
Distinctive
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 26
idealon PC and mobile, cold and warm: no frame over 50 ms, ≤ 1 % dropped frames, p99 ≤ 33 ms (budgets against 60 Hz even on a 120 Hz … - Distinctive: line 43
Tracing perturbs what it measures: Use a trace or profile to *explain* a freeze, never to *measure* one.
- Very specific: line 158
Blur once per line, never per letter or word: Every letter animating its own filter: blur() is a separate filtered layer re-rasterised per …
- Distinctive: line 223
Never report a fix you did not re-measure.
- Distinctive: line 224
Never change the design to win frames — a visual-weight trade (fewer particles, lighter blur) is the client's call: screenshot before/after …
- Very specific: line 232
Check the animations still *play*: warming a page by pre-scrolling it consumes every mode="once" reveal before anyone sees it.
- Very specific: line 236
Retro: Before closing, read your own notes once more: a fix with a measured before/after that the next project could reuse → …
- Very specific: line 243
Update the vault in the same turn: obsidian/meta/changelog.md with the measured numbers, an ADR in obsidian/meta/decisions-log.md if the …
“Common” is measured: kept by at least 6 in 10 of the 7 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Optimise page performance
This starter is built for animation-heavy marketing sites: springs on scroll,
text engines, Lenis smooth scroll, full-bleed imagery, often a WebGL scene. That
combination has characteristic failures, and they are not the ones people go
looking for. This skill was rewritten from scroll passes on ~50 production
sites built from this starter; each lever says whether it is a rule (held on
≥ 3 sites) or observed (1–2). Read obsidian/knowledge/fix-catalog.md and
obsidian/knowledge/pitfalls.md before fixing.
The loop is the skill. Build → measure → attribute → fix one thing → re-measure. Never skip to the fix; never report a win you did not measure.
If the project renders a three.js / WebGL scene (
threeinpackage.json, or a canvas with a render loop) — hard rule 14 sends you tooptimize-3d-scenefirst. Come back here for the page around the scene.
The bar
ideal on PC and mobile, cold and warm: no frame over 50 ms, ≤ 1 % dropped
frames, p99 ≤ 33 ms (budgets against 60 Hz even on a 120 Hz panel). smooth is
no frame > 100 ms and ≤ 3 % dropped; anything else is janky. A 50 ms frame is
three dropped frames at 60 Hz — where a hitch stops being subliminal.
0. Rules of measurement
- Measure the build, never
next dev.yarn build && yarn start. Kill the old server by port first; start the new one only if the build succeeded. - Baseline before you touch anything.
- 3 runs, medians; a
1/3freeze may be noise — re-run before fixing. A result near the 1 % line is a draw: A/B the two builds back to back (interleaved, ≥ 2 rounds) and compare per-frame work, not one record. - Throttle the CPU (4×) on the phone pass, and emulate 4G — localhost
hides lazy-load freezes; any
fetchedduring a pass is a freeze waiting for a slower link. - Change one thing at a time, same config before and after.
- Tracing perturbs what it measures. Use a trace or profile to explain a freeze, never to measure one.
- A busy machine fakes regressions. Above a load average of ~15 a scroll verdict is unreliable (GPU contention reads as janky) — re-run, don't act. Probes use a plain Chrome UA (the default puppeteer UA gets the robot form).
1. The scroll test — run this before anything else
node tools/qa/scroll-test.mjs --url http://localhost:3000/ # PC wheel + mobile touch (4× CPU), cold then warm
node tools/qa/scroll-test.mjs --url … --devices mobile --runs 1 # chase one freeze
node tools/qa/scroll-test.mjs --url … --first-scroll # + a scroll from the loader's unlock frameIt opens a visible Chrome (headless GPU behaviour differs), waits until the
page can actually scroll (Lenis running, no overflow: hidden), scrolls top →
bottom like a person — wheel bursts on PC, touch flings on mobile — jumps back,
and scrolls again warm. Every frame over 50 ms is reported with its section,
cause and reproducibility:
| cause | who owned the frame | look at |
decode (media fetched just before) | an image/video decoded in the revealing frame | §2 lazy media |
gpu / raster (main thread idle) | the GPU process: first paint of a big layer, a blur, a texture upload, a compile | §3 blur, layers, fill; optimize-3d-scene |
script | JS — the LoAF names file, function, invoker (FrameRequestCallback = a rAF loop) | the named loop; per-frame writes §3 |
script: React render | a render/commit mid-scroll (state set on scroll/in-view, a big subtree) | §2 hydration, §3 flags at the leaf |
script: React mounting a lazy chunk | a dynamic() chunk loading inside the scroll | §2 |
render (style / layout / paint) | style/layout — or, with 2–8 ms render inside a 200–900 ms frame, a GPU wait | §3 blur, per-frame styles |
Plus the worst sections by dropped frames — a page-wide 4 % was one section at 29 %. Read it as a diagnosis:
- Cold bad, warm clean → first-visit work inside animating frames — the most common shape in this starter. §2.
- Both bad → a steady per-frame cost. §3.
- Desktop drops steadily with the main thread idle on a WebGL page → the
120 Hz panel: cap the scene's draw at 60 fps (
optimize-3d-scene§5). - Both clean → the complaint is about load (
optimize-load) or about the real phone (mobile-device-qa).
Lighthouse never scrolls; you won't find this by hand either, because by the
time you scroll your own site you've warmed it. references/measuring.md has a
bench for tracing a freeze the tool already located;
tools/qa/profile.mjs --url … --scroll-to "<selector>" names the code.
The test's first scroll starts ~1 s after the page unlocks — a person's starts
the instant the loader lets go. Work landing in that second (a scene build,
section hydration) passed the test and was a reviewer's first impression on one
site. Probe that moment: scroll-test.mjs --first-scroll wheels from the
unlock frame — §2.
What it can't tell you: a phone's GPU (throttling slows the CPU, nothing
slows the Mac's GPU — use the counted checks in optimize-3d-scene), a real
network, iOS Safari. That's mobile-device-qa.
2. First-visit work — the usual culprit
Lazy media decoding mid-reveal
next/image marks anything below the fold loading="lazy"; on a first visit
the fetch, decode and first paint land in the frame a reveal starts. The
tell: frames drop, the longest main-thread task is ~20 ms — the stall is in
raster/decode, not JS. The fix: decode the page's media up front — behind the
opening loader if there is one — warming the next/image candidate, not the
source file (references/fixes.md has the implementation and its four traps).
Warm in idle time well after first interaction or under the loader, never
"600 ms after the entrance" — that put a model decode on the first scroll
(~700 ms stalls, observed).
Image sequences scrubbed by scroll (phones)
Each drawImage decodes synchronously on the main thread (3.3 s of decode in a
3,000 px scroll, observed). Ship a centre-cropped portrait set for portrait
phones (~⅓ the bytes), size the canvas to the frame, decode ahead with
createImageBitmap / img.decode() off the scroll path, request nearest-first
a few per task (all 150 at once made a ~150 ms frame). Observed (2): janky →
ideal hosted.
Hydration, lazy chunks and scene builds inside the scroll
- A
dynamic()chunk that loads on scroll lands its fetch, parse and mount in the revealing frame. Preload it afterload, mount below-fold scenes on idle after load rather than on proximity, or stop making it dynamic. - Below-fold hydration (
HydrateNear,RobotText lazy) trades TBT for a hydration frame mid-scroll. One site's on-approach hydration made mobile scroll janky every run (75–100 ms frames); one block per idle moment after load kept it smooth — rule (optimize-load§4). Check the scroll test either way. - The first scroll after a loader. Build the scene and hydrate the sections
under the loader, not at its lift; split the curtain-lift's entrances into
their own tasks (rule: a 54–73 ms lift frame gone). Stop Lenis while the
loader is up — a preloader's
overflow: hiddendoesn't stop it: a wheel flick under one loader landed the page 1,643 px down. Details:mobile-device-qa§first scroll. - One bad frame at the loader's lift is not a scroll problem — it's the entrance; fix it there, don't chase it here.
Other first-visit costs
- Fonts —
next/fontonly, Latin WOFF2 subsets. A late webfont reflows every text engine at once. - First paint of a large composited layer — a full-bleed image, a
backdrop-filter, a bigfilter: blur(). Pre-promote reveal layers: before blaming a blur or glass, render the reveals at rest — if the drops vanish, it's each block's first-frame layer promotion →will-change: opacity, transformfrom load until the reveal ends. Rule (3 sites — the glass was innocent each time). - A panel fading in from opacity 0 isn't painted while transparent, so it
all rasterises in its first visible frame (40–90 ms, main idle):
will-change: opacityon the content keeps it painted (observed). - Canvases gated by a scroll flag compile on their first draw — prewarm one hidden frame at mount (observed).
3. Steady-state scroll cost
- Blur once per line, never per letter or word. Every letter animating its
own
filter: blur()is a separate filtered layer re-rasterised per frame — desktop scroll janky with the main thread idle. Keep the per-letter opacity/transform stagger; put one blur on the line (or paragraph) that sharpens over the wave and is removed at rest. Rule (5+ sites: 5–6 % → < 1 % dropped; 575–925 ms freezes → none; body copy too — per-word blur on card paragraphs was 880 ms frames). Don't toggle the filter per letter mid-reveal (re-creates layers); exclude the LCP title (a blurred line-box became one site's LCP at 7 s). Use the line-reveal pattern the project sanctions (an ADR) — the engine is protected. - No permanent
will-changeon per-character spans. It makes every character a layer for the whole visit (~970 ms frames with a text-shadow halo, observed). Promote a character only while it moves; waiting =opacity: 0, settled =transform/filter: none. - One clock per text effect, latched — never restart on re-entry, or every title replays on the way back (warm 0.1 → 9.9 % dropped, observed).
- Write per-frame styles only when they change, on the smallest element.
Cache the last written value and skip equal writes; never write a CSS
variable on
<html>per frame (571 elements restyled per frame); never write pointer-driven variables during touch scroll. Rule (mobile 9 % → ~1 %; desktop 1.0 → 0 %, 117–130 restyles/frame gone). - Read scroll flags at the leaf. A flag that flips mid-scroll, read by card components, rebuilt every per-letter binding (150–240 ms React render, observed): subscribe only the canvas/video that needs it.
- Never let a canvas buffer follow a scroll-scrubbed box — hold the buffer
at the final size and stretch with CSS (
optimize-3d-scene§6). - Everything per-frame goes through the shared ticker
(
src/lib/animation/ticker.ts). A component with its own rAF is a bug — and a duplicate loop also doubles motion speed (§5 ofoptimize-3d-scene). getBoundingClientRectper frame per component.<SpringTrigger>/<ProgressTrigger>read layout every frame — hoist one measurement, gate on in-view, raiseframeInterval.- Compositor-only properties.
transformandopacityare free;filter,backdrop-filter,clip-path,width/height/top/leftare not. Masks on glass repaint every frame (250–490 ms, observed twice). background-attachment: fixedrepaints on scroll — but profile the section before blaming the most suspicious CSS (profile.mjs --scroll-to); one site's fixed layers moved 53 → 50 dropped frames, the real cost was a per-frame CSS variable.<Image fill>inside rounded, 3D-transformed tiles halved one phone's frame rate (observed).<model-viewer>swallows touch scrolling —touch-action="pan-y"on it (observed).- Respect the engine's protection.
src/components/animation/springs/andsrc/hooks/animation/are#do-not-modifywithout sign-off (hard rule 2). Fix the usage first.
4. Load cost
Owned by optimize-load (Lighthouse, people + robot). The page-side basics:
hero image priority, everything else sized and lazy; next/font/local, no
font-CDN <link>; Server Components by default; yarn build's First Load JS
per route — a marketing route above ~120 KB gz deserves an explanation;
grep -l ZodError .next/static/chunks/*.js prints nothing.
5. Prove it, then report it
Re-run the exact baseline command, same config, same runs. Report:
- the numbers before and after (verdict, dropped %, worst frame, per device and pass) and the config/load they were taken under;
- what you changed and why the measurement blamed it;
- what you did not fix and why, and what you reverted;
- anything you could not measure (a real phone's GPU, iOS).
Never report a fix you did not re-measure. "Should be faster" is not a result. Never change the design to win frames — a visual-weight trade (fewer particles, lighter blur) is the client's call: screenshot before/after and ask.
6. Then close the loop
yarn lint,npx tsc --noEmit -p .,yarn build,.claude/scripts/verify.sh— zero FAILs (hard rule 11).qa-verifyif any UI changed — a perf fix that breaks a reveal is not a win. Check the animations still play: warming a page by pre-scrolling it consumes everymode="once"reveal before anyone sees it.node tools/qa/check-motion.mjs --url …— reduced motion and the robot form still answer (a looping spring underskipAnimationhangs the page).- Retro. Before closing, read your own notes once more: a fix with a
measured before/after that the next project could reuse →
obsidian/knowledge/fix-catalog.md(symptom, fix, evidence, rule/observed — a second site confirming an entry bumps its count; three makes it a rule); a hypothesis or tool reading that misled you →obsidian/knowledge/pitfalls.md; a skill that was wrong or silent → edit it now, and log it inobsidian/meta/changelog.md. - Update the vault in the same turn:
obsidian/meta/changelog.mdwith the measured numbers, an ADR inobsidian/meta/decisions-log.mdif the fix changed how the project works.
Related
[[optimize-performance]] · [[optimize-3d-scene]] · [[optimize-load]] · [[mobile-device-qa]] · [[qa-verification]] · [[testing-pipeline]] · [[ship]]
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

