web-performance-skill-cascade

Cascaded web performance skills and Lighthouse tooling for AI agents: Core Web Vitals, budgets, JavaScript, images, fonts, caching, and CI checks.

This is Mirogate's open-source performance contribution for AI-assisted frontend engineering. It ships a real Codex skill, portable Markdown modules, report analysis, budget generation, scenarios, and before/after performance demos.

Why Cascaded Performance Skills

Performance work fails when every issue is treated as "make the Lighthouse score green." A slow page can be limited by LCP discovery, main-thread JavaScript, image weight, font shifts, cache headers, third-party scripts, or verification gaps.

This project keeps a small root skill and loads focused modules only when the task needs them.

flowchart TD
  A["Page, PR, or Lighthouse report"] --> B["web-performance root skill"]
  B --> C{"Relevant performance surface?"}
  C --> D["Lighthouse / Core Web Vitals"]
  C --> E["LCP / images / fonts"]
  C --> F["INP / JavaScript / third-party"]
  C --> G["CLS / caching / delivery"]
  D --> H["Patch + verify + residual risk"]
  E --> H
  F --> H
  G --> H

Loading

Quick Start

npm install
npm test
node scripts/compose.mjs --scenario landing-page-lcp
node scripts/analyze.mjs --report examples/lighthouse/mirogate-uae-mobile.json
node scripts/budget.mjs --init --target green --stdout

Run a local Lighthouse audit when Chrome is available:

node scripts/audit.mjs --url https://example.com --device mobile --runs 3 --timeout 120000 --out reports/

Use PageSpeed only when API quota and an API key are available:

node scripts/audit.mjs --url https://example.com --source pagespeed --api-key "$PAGESPEED_API_KEY"

What Is Included

• skills/web-performance/SKILL.md: the Codex root skill.
• skills/web-performance/references/: focused performance modules.
• portable/web-performance-cascade.md: portable bundle for Claude Code, Cursor, or other agents.
• scripts/audit.mjs: local Lighthouse or PageSpeed report collection with timeouts.
• scripts/analyze.mjs: Lighthouse JSON to prioritized Markdown or JSON.
• scripts/budget.mjs: green-target Lighthouse CI-style budgets.
• scripts/compose.mjs: assembles root skill plus selected modules for a scenario.
• scripts/validate.mjs: checks module metadata, scenarios, fixtures, and demos.
• examples/scenarios/: task-to-module examples.
• examples/performance-patches/: before/after demos for common performance mistakes.

Module Map

Module	Use When
lighthouse-scoring	Interpreting Lighthouse scores, weights, run conditions, and variability.
core-web-vitals	LCP, INP, CLS, field data, PageSpeed/CrUX, and web-vitals attribution.
lcp-critical-path	Hero media, TTFB, preload, critical CSS, and render-blocking resources.
inp-main-thread-js	INP/TBT, long tasks, hydration, event handlers, and workers.
cls-layout-stability	Layout shifts from images, fonts, banners, embeds, and animations.
images-media	Responsive images, AVIF/WebP, lazy loading, video, and media byte weight.
fonts-css-rendering	Font loading, critical CSS, unused CSS, and render blocking.
javascript-bundles	Unused JS, code splitting, minification, and dependency weight.
caching-delivery-edge	Compression, cache headers, Cloudflare/CDN rules, immutable assets.
third-party-scripts	Analytics, chat widgets, embeds, tag managers, and consent-aware loading.
accessibility-seo-guardrails	Performance fixes that must preserve crawlability and accessibility.
verification-budgets	Lighthouse CI assertions, budgets, repeated runs, and residual risk.

Example Scenarios

node scripts/compose.mjs --scenario landing-page-lcp
node scripts/compose.mjs --scenario spa-inp
node scripts/compose.mjs --scenario cls-regression
node scripts/compose.mjs --scenario image-heavy-page
node scripts/compose.mjs --scenario third-party-scripts
node scripts/compose.mjs --scenario cloudflare-static-site

Mirogate Dogfood Fixture

The first fixture is based on a local Lighthouse run against https://mirogate.com/uae/:

• Performance: 84
• Accessibility: 92
• Best practices: 96
• SEO: 100
• FCP/LCP: 2.7s
• CLS: 0.074
• TBT: 0ms
• Main opportunity: unused/unminified JavaScript

The fixture is intentionally not treated as a public benchmark. It is a stable parser and documentation example.

Limits

This is not a guarantee of perfect Lighthouse scores, SEO ranking improvement, Google affiliation, or real-user field success. Lighthouse is lab data. Core Web Vitals field health still requires field data such as CrUX, PageSpeed field data, or RUM.

Use official references for policy decisions:

• Lighthouse scoring: https://developer.chrome.com/docs/lighthouse/performance/performance-scoring
• Core Web Vitals: https://web.dev/articles/vitals
• Lighthouse CI: https://github.com/GoogleChrome/lighthouse-ci/blob/main/docs/configuration.md
• PageSpeed Insights API: https://developers.google.com/speed/docs/insights/v5/get-started
• web-vitals: https://github.com/GoogleChrome/web-vitals

Security

Please report security issues to security@mirogate.com. See SECURITY.md.