skilldrop-cli 0.16.35 → 0.16.36

package/packs/frontend/skills/web-performance-review/examples/quayside-article.md

@@ -0,0 +1,103 @@
+# Worked example: Quayside Ledger article page
+
+## Input
+
+The user says: *"Our article pages feel janky and Search Console is unhappy. Here's a Lighthouse
+run of the Harbour Bridge story. Our RUM dashboard says, for mobile over the last 28 days, LCP p75
+3.4 s, INP p75 160 ms, CLS p75 0.31. What do we fix first?"* and supplies
+[`quayside-article-lhr.json`](quayside-article-lhr.json), a hand-built Lighthouse 12 result
+(default mobile, simulated throttling). All names and hosts are fictional.
+
+The agent passes the RUM numbers to the script with the report:
+
+```bash
+python3 scripts/lh_summary.py examples/quayside-article-lhr.json \
+  --lcp-p75 3400 --inp-p75 160 --cls-p75 0.31 --field-source "RUM, last 28 days, mobile"
+```
+
+## Script output (real; run header and main-thread section cut)
+
+```markdown
+## Field data (real users, p75): decides whether there is a problem
+RUM, last 28 days, mobile
+
+| Metric | p75 | Rating | Share good |
+|---|---|---|---|
+| LCP | 3.40 s | needs-improvement | - |
+| INP | 160 ms | good | - |
+| CLS | 0.31 | poor | - |
+
+Core Web Vitals (field): FAILED: LCP needs-improvement, CLS poor
+
+## Lab metrics (this run): explains why
+
+Performance score: 78 (a lab weighting, not a Core Web Vitals result)
+
+| Metric | Value | Lab rating | Threshold |
+|---|---|---|---|
+| FCP | 2.05 s | needs-improvement | good <= 1800ms, poor > 3000ms |
+| LCP | 3.12 s | needs-improvement | good <= 2500ms, poor > 4000ms |
+| TBT | 140 ms | good | good <= 200ms, poor > 600ms |
+| CLS | 0.22 | needs-improvement | good <= 0.1, poor > 0.25 |
+| Server response (lab TTFB) | 1.42 s | - | - |
+
+## LCP element
+Selector: article > figure.article-lead > img.article-lead__image
+Flags: fetchpriority=high present
+
+| Phase | Time | Share |
+|---|---|---|
+| TTFB | 1.65 s | 53% |
+| Resource load delay | 180 ms | 6% |
+| Resource load duration | 820 ms | 26% |
+| Element render delay | 470 ms | 15% |
+Dominant phase: TTFB
+
+## Layout shift culprits (load window only; shifts after load are not in a lab run)
+- body > div.ad-slot.ad-slot--top: 0.150, cause: Injected iframe (https://ads.adharbor.example/serve/frame.html)
+- article > figure.article-lead > img.article-lead__image: 0.070, cause: Unsized image element
+
+## Failing opportunities and diagnostics, ranked by the vital they move
+| Audit | Est. load saving | Metric savings | Note |
+|---|---|---|---|
+| * server-response-time: Reduce initial server response time | 1.32 s | FCP 1.32 s, LCP 1.32 s |  |
+| * unused-css-rules: Reduce unused CSS | 150 ms / 69 KiB | FCP 150 ms, LCP 150 ms |  |
+| * layout-shifts: Avoid large layout shifts | - | CLS 0.22 |  |
+| * unsized-images: Image elements do not have explicit width and height | - | none | acts on CLS directly |
+```
+
+## What the agent decides
+
+- CLS is the vital furthest past its threshold (0.31 against 0.1, poor), so the shift fixes go
+  first, even though the script's table lists the server fix first by milliseconds.
+- The LCP image already has `fetchpriority="high"` and almost no load delay, so the preload
+  advice a plain review gives would change nothing. TTFB is 53% of LCP: the server is the LCP fix.
+- INP is good in the field, so TBT (140 ms) and the ad script's long task are not on the list.
+- Field CLS (0.31) is above lab CLS (0.22): part of the shift happens after load, where this run
+  can't see it.
+
+## Reply
+
+Readers do have a problem, and layout shift is the bigger one: on mobile, CLS at p75 is 0.31
+(poor; good is 0.1) and LCP is 3.4 s (needs improvement; good is 2.5 s). Responsiveness is fine
+(INP 160 ms). Most of the shift comes from the top ad slot, and most of the LCP time is spent
+waiting for the server.
+
+1. **Reserve space for the top ad.** `div.ad-slot--top` grows when the ad iframe arrives, which is
+   0.15 of the 0.22 shift in this run. Give the slot a `min-height` equal to the tallest ad it serves
+   on mobile. Moves CLS.
+2. **Give the lead image dimensions.** `img.article-lead__image` (`bridge-1200.webp`) has no
+   `width` or `height`, which is another 0.07 of the shift. Add both attributes, or an
+   `aspect-ratio`, so the space is held before the image loads. Moves CLS.
+3. **Cut the article's server response.** The HTML took 1.42 s to arrive, and time to first byte
+   is 1.65 s of the 3.12 s lab LCP. Serve the article HTML from the CDN cache, or find where the
+   backend spends that time. Lighthouse estimates up to 1.3 s off LCP in the lab. Moves LCP and FCP.
+4. **Then trim the stylesheet.** `site.css` is 77% unused, about 150 ms of LCP in the lab. Small;
+   do it after the three above.
+
+What this run can't show: field CLS is higher than the run's 0.22, so some shifting happens after
+load (later ads, scrolling) that a single page-load test doesn't record. RUM that reports which
+element shifted would name it. The numbers come from one run on an emulated mid-range phone on
+slow 4G; re-test with the median of three to five runs, then watch RUM p75 over the following weeks.
+
+**To confirm:** the ad sizes the top slot serves on mobile, which set its `min-height`.

package/packs/frontend/skills/web-performance-review/manifest.json

@@ -0,0 +1,48 @@
+{
+  "name": "web-performance-review",
+  "version": "0.1.0",
+  "description": "Read a Lighthouse report or PageSpeed Insights result, with field data when there is any (CrUX, PSI loadingExperience or RUM p75), and say what makes the page slow for real users and what to fix first, ranked by how much each fix moves LCP, INP and CLS at the 75th percentile. Names the LCP element and which LCP phase dominates, the elements that shift and why, the long tasks and third parties by main-thread time, and treats estimated savings as lab estimates that overlap. Use when the user shares a Lighthouse JSON or PSI result and asks \"why is this page slow\", \"what should we fix first\", \"we score 92 but Search Console says LCP is poor\", \"did our change fix INP\", \"review this Lighthouse report\", or \"how do we pass Core Web Vitals\".",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [],
+    "optional": []
+  },
+  "related": [
+    "accessibility-audit",
+    "observability-plan",
+    "rendering-strategy"
+  ],
+  "handoff": [
+    {
+      "to": "observability-plan",
+      "when": "there is no field data, or the review needs RUM with per-element attribution to find after-load shifts or slow interactions",
+      "purpose": "Set up real-user collection of LCP, INP and CLS at p75 so fixes can be verified on users, not on one lab run.",
+      "fallback": "If observability-plan is absent, name the three vitals to collect at p75 per page type and form factor, with the element attribution for each, in one paragraph."
+    }
+  ],
+  "tags": [
+    "web-performance",
+    "core-web-vitals",
+    "lighthouse",
+    "frontend"
+  ],
+  "permissions": {
+    "network": [
+      "registry.npmjs.org"
+    ],
+    "commands": [
+      "lighthouse",
+      "npx"
+    ],
+    "files": "named-paths",
+    "notes": "The script reads the Lighthouse, PageSpeed Insights or CrUX JSON it is given and writes only an -o path the user names; it makes no network calls. The instructions run the Lighthouse CLI (through npx, which fetches it from the npm registry) against the page the user names."
+  },
+  "model": {
+    "tier": "standard",
+    "rationale": "The metrics, opportunities and the elements behind them are read out of the Lighthouse report by its script; the model ranks fixes by what moves the user-facing numbers."
+  }
+}

package/packs/frontend/skills/web-performance-review/reference.md

@@ -0,0 +1,105 @@
+# web-performance-review reference
+
+## Thresholds
+
+Core Web Vitals are judged at the 75th percentile of real page loads, per form factor.
+
+| Metric | Good | Needs improvement | Poor | Field or lab |
+|---|---|---|---|---|
+| LCP | ≤ 2.5 s | 2.5–4 s | > 4 s | both |
+| INP | ≤ 200 ms | 200–500 ms | > 500 ms | field only (or a Lighthouse timespan run) |
+| CLS | ≤ 0.1 | 0.1–0.25 | > 0.25 | both; lab sees the load window only |
+| FCP | ≤ 1.8 s | 1.8–3 s | > 3 s | both, supporting metric |
+| TTFB | ≤ 0.8 s | 0.8–1.8 s | > 1.8 s | field; lab has `server-response-time` |
+| TBT | ≤ 200 ms | 200–600 ms | > 600 ms | lab only, a proxy for INP |
+
+A page passes Core Web Vitals when LCP, INP and CLS are all good at p75. With no INP data, CrUX
+assesses on LCP and CLS.
+
+The Performance score (Lighthouse 10 and later) weights lab metrics: TBT 30%, LCP 25%, CLS 25%,
+FCP 10%, Speed Index 10%. It is a lab number. A page can score 90+ and fail every vital in the
+field, or score 50 and pass.
+
+## Fields the script reads
+
+**Lighthouse result (LHR):** `lighthouseVersion`, `fetchTime`, `finalDisplayedUrl` (older:
+`finalUrl`), `runWarnings`, `runtimeError`, `environment.benchmarkIndex`, `entities` (origins
+grouped by company, `isFirstParty`), `configSettings.formFactor`, `.screenEmulation`,
+`.throttlingMethod`, `.throttling` (`rttMs`, `throughputKbps`, `cpuSlowdownMultiplier`; the
+`devtools` method uses `requestLatencyMs`, `downloadThroughputKbps`), `categories.performance.score`
+(0–1), and `audits.<id>` with `score`, `scoreDisplayMode`, `numericValue`, `displayValue`,
+`metricSavings` (Lighthouse 11 and later: `{LCP, FCP, TBT, CLS, INP}`) and `details`
+(`type` is `opportunity`, `table`, `list` or `checklist`; rows in `details.items`; opportunities
+add `overallSavingsMs` and `overallSavingsBytes`). An audit with score ≥ 0.9 passed.
+
+**PageSpeed Insights v5:** `lighthouseResult` (the LHR), `loadingExperience` (this URL) and
+`originLoadingExperience` (whole origin). Each has `metrics.<KEY>.percentile`, `.category`
+(`FAST`, `AVERAGE`, `SLOW`) and `.distributions`. Keys: `LARGEST_CONTENTFUL_PAINT_MS`,
+`INTERACTION_TO_NEXT_PAINT`, `CUMULATIVE_LAYOUT_SHIFT_SCORE` (**multiplied by 100**: 14 means
+0.14), `FIRST_CONTENTFUL_PAINT_MS`, `EXPERIMENTAL_TIME_TO_FIRST_BYTE`. `origin_fallback: true`
+means the URL had too little traffic and the numbers are the origin's. The PSI strategy (mobile
+or desktop) sets which form factor the field data is.
+
+**CrUX API record:** `record.key` (`url` or `origin`, `formFactor`), `record.metrics.<name>.percentiles.p75`
+(CLS p75 is a string such as `"0.14"`), `histogram[0].density` (share good), `collectionPeriod`.
+
+## Audits by the vital they act on
+
+| Audit id | Acts on | Reads as |
+|---|---|---|
+| `largest-contentful-paint-element` | LCP | the element, and the phase table (`TTFB`, `Load Delay`, `Load Time`, `Render Delay`) |
+| `lcp-lazy-loaded` | LCP | score 0 means the LCP image has `loading="lazy"` |
+| `prioritize-lcp-image` | LCP | the LCP image is requested late; a preload or `fetchpriority` would start it sooner |
+| `server-response-time`, `redirects`, `uses-rel-preconnect` | LCP, FCP | time before the first byte or first request |
+| `render-blocking-resources` | FCP, LCP render delay | CSS or sync JS in the head |
+| `uses-responsive-images`, `modern-image-formats`, `uses-optimized-images`, `offscreen-images` | LCP only when the LCP image is in the rows | otherwise bytes and load time |
+| `unused-javascript`, `unused-css-rules`, `unminified-*`, `uses-text-compression` | whatever `metricSavings` says | often load time only |
+| `layout-shifts` (older: `layout-shift-elements`), `unsized-images`, `font-display`, `non-composited-animations` | CLS | the element and the cause |
+| `long-tasks`, `bootup-time`, `mainthread-work-breakdown`, `third-party-summary`, `third-party-facades` | TBT, a proxy for INP | scripts and entities by main-thread time |
+
+Lighthouse 12 also emits `*-insight` audits (`lcp-breakdown-insight` or `lcp-phases-insight`,
+`lcp-discovery-insight`, `cls-culprits-insight`, `third-parties-insight`,
+`render-blocking-insight`); the script reads the LCP and third-party ones when the classic audit is
+missing.
+
+## LCP phases
+
+| Phase | What it measures | When it dominates |
+|---|---|---|
+| TTFB | navigation start to the HTML's first byte | cache the HTML (CDN or edge), remove redirects, fix backend time |
+| Resource load delay | first byte to the LCP resource's request | remove `loading="lazy"`, add `fetchpriority="high"`, put the `<img>` in the server HTML; a CSS background or JS-inserted image needs `<link rel="preload" as="image" fetchpriority="high">` |
+| Resource load duration | the LCP resource's download | `srcset`/`sizes` matched to the viewport, AVIF or WebP, a CDN close to users |
+| Element render delay | resource loaded to element painted | inline critical CSS, defer non-critical JS, avoid client-side rendering of the LCP element, break up long tasks before paint |
+
+A text LCP element has zero load delay and duration. The healthy split puts most of the time in
+TTFB and load duration, with load delay and render delay near zero.
+
+## CLS causes Lighthouse reports
+
+| Cause | Fix |
+|---|---|
+| Unsized image element | `width` and `height` attributes, or CSS `aspect-ratio` |
+| Web font loaded | `font-display: optional` or `swap` with a `size-adjust`ed fallback; preload the font |
+| Injected iframe, ad or banner | reserve the slot with `min-height`; overlay banners instead of pushing content |
+| Media element | dimensions on `<video>` and embeds |
+| Non-composited animation | animate `transform` and `opacity` only |
+
+A navigation run records shifts during load. Shifts on scroll, after consent clicks or from late
+ads count in field CLS and not in the lab, so field CLS above lab CLS points there; the web-vitals
+library's attribution build reports the element per shift in RUM.
+
+## Run settings
+
+| Preset | RTT | Throughput | CPU | Screen |
+|---|---|---|---|---|
+| Default mobile (also PSI mobile) | 150 ms | 1.6 Mbps | 4x slowdown | 412 × 823 (Moto G Power) |
+| `--preset=desktop` (also PSI desktop) | 40 ms | 10 Mbps | 1x | 1350 × 940 |
+
+`throttlingMethod: simulate` (default) loads unthrottled and models the throttled timings, so
+metrics are estimates; `devtools` applies throttling for real; `provided` applies none.
+`benchmarkIndex` is the host CPU's score: a slow or busy machine inflates TBT and LCP. Runs
+compare only with the same URL, preset, throttling, Lighthouse version and a similar host.
+Lighthouse scores vary between runs of the same page; take the median of 3 to 5.
+
+CrUX field data is a rolling 28 days, so a fix shows fully about four weeks after release. RUM
+p75 for the same days shows it sooner.