Skip to content

bestdeejay-design/agent-skills / skills/frontend-performance

frontend-performance

Verified

Audit web performance depth beyond Lighthouse. Use when the user asks for a performance audit, Core Web Vitals (CWV) review, bundle-size analysis, or to optimize loading — including slow LCP/FCP/INP/CLS, a heavy JS/CSS bundle, or missing HTTP/2, text compression, browser caching, HSTS, resource hints, service worker, or speculation rules. Triggers (casual phrasings included): 'performance audit', 'perf audit', 'frontend perf', 'lighthouse', 'core web vitals', 'cwv', 'lcp', 'cls', 'inp', 'page speed', 'bundle size', 'optimize speed', 'why is my site slow', 'make it faster', 'speed up my page', 'check HTTP/2 and compression', 'проверь производительность', 'ускорь сайт'. Two engines: perf_headers.py (pure-Python stdlib, offline — headers, protocol, page weight, duplicate libs, hints, SW, streaming, virtualization) and audit.js (real Chrome + Lighthouse ≥13 — LCP/FCP/INP/CLS, critical chains, render-blocking). Maps Front-End-Checklist Performance (43 rules). Invoked by /frontend and mobile-frontend.

frontend-performance

A performance specialist that goes beyond what frontend-perfection already does. frontend-perfection runs Lighthouse + a couple of resource-hint checks and owns contrast/tokens/SEO/a11y. This skill owns performance depth: the network/header and built-asset layer that Lighthouse cannot see offline, plus a focused Core Web Vitals Lighthouse run.

Two engines, clearly split by what they can measure:

  • perf_headers.py — PURE Python 3 stdlib, OFFLINE. Inspects response headers + protocol + transfer timing for a URL, and statically analyzes a built asset tree (page weight, largest bundles, duplicate libs, missing preloads, GIF→video, service worker, speculation rules, streaming, virtualization, third-party async). No network needed for the directory mode.
  • audit.js — real Chrome via chrome-launcher + Lighthouse >= 13 (stable API, .default fallback). Measures the runtime metrics: LCP, FCP, INP, CLS, TTFB, critical request chains, render-blocking resources, compression, HTTP/2.

When to use

  • User asks for a "performance audit", "page speed", "core web vitals", "bundle size", "optimize loading", "check HTTP/2 / compression / caching".
  • User reports slow LCP/CLS/INP or a heavy bundle.
  • frontend-perfection already passed but the user wants perf depth, or the orchestrator (/frontend, mobile-frontend) delegates the perf slice.

Composition

  • For contrast/tokens/SEO/a11y/OG — load frontend-perfection (this skill does NOT reimplement those; it owns performance only).
  • For SEO-layer breadth — load seo-toolkit.
  • For a visual direction before building — load frontend-design-taste.

Workflow

  1. Locate the target — a live URL, or a built asset directory (static HTML/CSS/JS or a bundled SPA).
  2. Run the offline auditor (no Chrome needed) and capture evidence:
    python3 scripts/perf_headers.py --url https://example.com --out perf-url.json
    echo "perf_headers.py(url) exit=$?"
    python3 scripts/perf_headers.py --dir ./dist --out perf-dist.json
    echo "perf_headers.py(dir) exit=$?"
    
    Exit 0 = no fail checks; 1 = at least one fail; 2 = runner error. Keep the --out JSON and the printed fail lines — they are the evidence that the audit ran and what it found. Paste the exit status and the fail summary into the report; do not summarize from memory.
  3. Run the Lighthouse CWV runner (real Chrome) for the runtime metrics, capturing evidence the same way:
    node scripts/audit.js --url https://example.com --mobile --out lh-perf.json
    echo "audit.js(mobile) exit=$?"
    node scripts/audit.js --url https://example.com --desktop --out lh-perf-d.json
    echo "audit.js(desktop) exit=$?"
    
    Default --threshold 90 on the performance category; exit 0 only when performance ≥ threshold. Add --only performance (default) or another category if iterating. Record the printed performance score and the failed weighted audits from each --out JSON as evidence.
  4. Fix by audit id — every fix references the audit it closes (perf:http2-3, perf:page-weight, perf:lcp, perf:js-bundle-size, …).
  5. Re-audit until green on both engines and both form factors.
  6. Write the before/after report — input paths, exact commands, the captured exit statuses (0/1/2) for every engine run, the real fail lines and scores from each --out JSON, interpretation, and what was deliberately NOT done. Evidence over assertion: the report must show the command, its exit status, and the output — not a paraphrase.

audit.js — Lighthouse runner (stable API)

  • Real Chrome via chrome-launcher (default channel = installed Chrome; --no-headless to watch). No Playwright internals, no private CDP fields.
  • Lighthouse >= 13 support: falls back to require("lighthouse").default.
  • Dependency isolation: local node_modules → NODE_PATH → npm root -g. Install instead of dying:
    npm i lighthouse chrome-launcher          # in the script's dir
    # or globally:
    npm i -g lighthouse chrome-launcher && export NODE_PATH=$(npm root -g)
    
  • Output: compact JSON (--out) with the performance score, a cwv block (LCP/FCP/INP/CLS/TBT/Speed-Index + key audits with numeric values), and only the failed weighted audits (id, title, score, weight).
  • Exit codes: 0 performance ≥ threshold, 1 below, 2 runner error.
  • Default category is performance; --only <category> to scope.

perf_headers.py — offline auditor (Python stdlib, no deps)

Checks and their ids. Tag static = offline header/asset check, lighthouse = measured by audit.js, manual = needs WebPageTest/human.

idchecklist rule (Performance)taghow measured
perf:http2-3Enable HTTP/2 or HTTP/3staticresponse protocol (info if urllib can't confirm — verify in Lighthouse)
perf:text-compressionEnable text-based compressionstaticcontent-encoding: gzip|br
perf:browser-cachingEnable browser cachingstaticcache-control max-age + etag
perf:hsts(security reused) HSTSstaticstrict-transport-security
perf:sec:*(security reused) CSP/XCTO/XFO/Referrerstaticpresence of security headers
perf:content-typecorrect content-typestaticcontent-type present
perf:ttfbReduce TTFBstaticHEAD latency (best-effort)
perf:page-weightKeep page weight <1500KB (<500KB ideal)staticsum of built tree / HTML doc size
perf:js-bundle-sizeOptimize JS bundle sizestaticlargest .js files vs 250KB
perf:css-sizeOptimize CSS file sizestaticlargest .css files vs 100KB
perf:no-dup-js-libsRemove duplicate JS librariesstaticmd5 content dup + version-stripped name
perf:gif-to-videoConvert animated GIFs to videostatic.gif presence
perf:resource-hintsUse resource hints (preload/prefetch/preconnect)static<link rel> hints in HTML
perf:preconnectUse preconnect for critical 3p originsstaticrel=preconnect
perf:fetchpriorityUse fetchprioritystaticfetchpriority attribute
perf:no-lazy-above-foldDisable lazy loading above the foldstaticearly <img loading=lazy> / missing preload
perf:lazy-offscreenLazy loading for offscreen contentstatic<img loading=lazy> when 3+ imgs
perf:service-workerRegister a service workerstaticserviceWorker / sw.js
perf:speculation-rulesSpeculation Rules APIstaticspeculationrules
perf:stream-htmlStream HTML to browserstatictransfer-encoding / renderToPipeableStream
perf:source-mapsSource maps for debuggingstatic.map / sourceMappingURL
perf:virtualize-listsVirtualize long lists/tablesstatic>500 <li> heuristic
perf:third-party-asyncOptimize third-party script loadingstaticexternal <script> async/defer
perf:cdnUse a CDNstaticserver/via header heuristic
perf:lcpOptimize LCP (<2.5s, Critical)lighthouselargest-contentfulpaint
perf:fcpOptimize FCP (<1.8s)lighthousefirst-contentful-paint
perf:inpOptimize INP (<200ms)lighthouseinteractive (TBT proxy)
perf:clsMinimize CLS (<0.1)lighthousecumulative-layout-shift
perf:load-time-3sPage load <3slighthousespeed-index / load
perf:critical-chainsMinimize critical request chainslighthousecritical-request-chains
perf:no-render-blockingEliminate render-blocking resourceslighthouserender-blocking-resources
perf:min-http-requestsMinimize HTTP requestslighthousenetwork-requests
perf:dom-sizeReduce DOM size/complexitylighthousedom-size
perf:no-legacy-jsAvoid legacy JS to modern browserslighthouselegacy-javascript
perf:no-js-redirectsAvoid JS-based redirectslighthouseredirects
perf:font-loadingOptimize web font loadinglighthousefont-display / render-blocking
perf:defer-on-interactionLoad non-critical code on interactionlighthouseunused-javascript / TBT
perf:viewport-awareLoad code when near viewportlighthouseunused-javascript
perf:bfcacheOptimize back/forward cachestaticheuristic: no unload listeners (manual confirm)
perf:secure-js-libsUse secure/up-to-date JS libslighthouselighthousec.js-libraries (best-effort)
perf:webpagetestAnalyze with WebPageTestmanualhuman/WebPageTest run
perf:consent-mode-v2Google Consent Mode v2manualprivacy/consent config review
perf:gtm-efficientOptimize GTM implementationmanualtag-config review
perf:offline-fallbackOffline fallback pagestaticservice worker + offline route (best-effort)
perf:loading-indicatorsShow loading indicatorsstaticapp-code review (best-effort)

Constraints / non-goals

  • audit.js opens a real Chrome; do not substitute CLI lighthouse headless-shell in the default call.
  • perf_headers.py is offline and stdlib-only — no PyYAML, no requests, no third-party packages. Network-dependent checks (URL mode) degrade to info when the host is unreachable; the directory mode never needs a network.
  • HTTP/2 or /3 cannot be confirmed by urllib (it speaks HTTP/1.1). The perf:http2-3 check reports the observed protocol and marks itself info; confirm with Lighthouse / WebPageTest.
  • Do NOT reimplement contrast/token/SEO/a11y checks — those belong to frontend-perfection.
  • Do NOT fix by hiding audits: raise the underlying metric at the root.
  • Do NOT delete or modify user tests/screenshots; artifacts go to --out.

Examples

Full loop on a live site:

python3 scripts/perf_headers.py --url https://example.com --out perf-url.json
node scripts/audit.js --url https://example.com --mobile --out lh-perf.json
node scripts/audit.js --url https://example.com --desktop --out lh-perf-d.json

Built SPA in ./dist (no network needed):

python3 scripts/perf_headers.py --dir ./dist --out perf-dist.json

Iterate on performance until green:

node scripts/audit.js --url http://localhost:8377/ --mobile --only performance

See references/canonical-patterns.md for the canonical Front-End-Checklist Performance sources this skill is aligned with.

Boundaries

  • Do not use for visual design critique or accessibility; use frontend-design-taste or frontend-a11y.

Evidence and completion gate

Run the documented command against the user’s actual input. Report the command, exit status, files changed or produced, and relevant stdout/stderr. Separate blocked or pre-existing failures from failures introduced by the current work. Do not call the result complete when the script was only described or when an artifact was not reopened and checked.

rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall