feat: add webperf-core-web-vitals skill

skills/webperf-core-web-vitals/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: webperf-core-web-vitals
+description: Intelligent Core Web Vitals analysis with automated workflows and decision trees. Measures LCP, CLS, INP with guided debugging that automatically determines follow-up analysis based on results. Includes workflows for LCP deep dive (5 phases), CLS investigation (loading vs interaction), INP debugging (latency breakdown + attribution), and cross-skill integration with loading, interaction, and media skills. Use when the user asks about Core Web Vitals, LCP optimization, layout shifts, or interaction responsiveness.
+context: fork
+---
+
+# WebPerf: Core Web Vitals
+
+JavaScript snippets for measuring web performance in Chrome DevTools. Execute with `evaluate_script`, capture output with `get_console_message`.
+
+## Scripts
+
+- `scripts/CLS.js` — Cumulative Layout Shift (CLS)
+- `scripts/INP.js` — Interaction to Next Paint (INP)
+- `scripts/LCP-Image-Entropy.js` — LCP Image Entropy
+- `scripts/LCP-Sub-Parts.js` — LCP Sub-Parts
+- `scripts/LCP-Trail.js` — LCP Trail
+- `scripts/LCP-Video-Candidate.js` — LCP Video Candidate
+- `scripts/LCP.js` — Largest Contentful Paint (LCP)
+
+Descriptions, thresholds, and return schemas: `references/snippets.md`, `references/schema.md`
+
+## Script Execution Patterns
+
+Scripts fall into two execution patterns:
+
+### Synchronous (LCP, CLS, LCP-Sub-Parts, LCP-Trail, LCP-Image-Entropy, LCP-Video-Candidate)
+
+Run via `evaluate_script` and return structured JSON immediately from buffered performance data. The page must have already loaded.
+
+### Measuring (INP)
+
+INP requires real user interactions to measure. The workflow is:
+
+1. Run `INP.js` via `evaluate_script` → returns `{ status: "measuring", getDataFn: "getINP" }`
+2. **Tell the user:** "INP measuring is now active. Please interact with the page — click buttons, open menus, fill form fields — then let me know when you're done."
+3. Wait for the user to confirm they've interacted.
+4. Call `evaluate_script("getINP()")` to collect results.
+5. If `getINP()` returns `status: "error"` → the user has not interacted yet. Remind them and wait.
+6. For a full breakdown of all interactions, call `evaluate_script("getINPDetails()")` — returns all recorded interactions sorted by duration.
+
+> The agent cannot interact with the page on behalf of the user for INP measurement. Real user interactions are required.
+
+## Common Workflows
+
+### Complete Core Web Vitals Audit
+
+When the user asks for a comprehensive Core Web Vitals analysis or "audit CWV":
+
+1. **LCP.js** - Measure Largest Contentful Paint
+2. **CLS.js** - Measure Cumulative Layout Shift
+3. **INP.js** - Measure Interaction to Next Paint
+4. **LCP-Subparts.js** - Break down LCP timing phases
+5. **LCP-Trail.js** - Track LCP candidate evolution
+
+### LCP Deep Dive
+
+When LCP is slow or the user asks "debug LCP" or "why is LCP slow":
+
+1. **LCP.js** - Establish baseline LCP value
+2. **LCP-Subparts.js** - Break down into TTFB, resource load, render delay
+3. **LCP-Trail.js** - Identify all LCP candidates and changes
+4. **LCP-Image-Entropy.js** - Check if LCP image has visual complexity issues
+5. **LCP-Video-Candidate.js** - Detect if LCP is a video (poster or video element)
+
+### CLS Investigation
+
+When layout shifts are detected or the user asks "debug CLS" or "layout shift issues":
+
+1. **CLS.js** - Measure overall CLS score
+2. **Layout-Shift-Loading-and-Interaction.js** (from `webperf-interaction` skill) - Separate loading vs interaction shifts
+3. Cross-reference with **webperf-loading** skill:
+   - Find-Above-The-Fold-Lazy-Loaded-Images.js (lazy images causing shifts)
+   - Fonts-Preloaded-Loaded-and-used-above-the-fold.js (font swap causing shifts)
+
+### INP Debugging
+
+When interactions feel slow or the user asks "debug INP" or "slow interactions":
+
+1. **INP.js** - Start measuring. Tell the user to interact with the page and confirm when done.
+2. Call `getINP()` to collect results once the user confirms.
+3. Call `getINPDetails()` to see all interactions ranked by duration.
+4. **Interactions.js** (from `webperf-interaction` skill) - List all interactions with timing
+5. **Input-Latency-Breakdown.js** (from `webperf-interaction` skill) - Break down input delay, processing, presentation
+6. **Long-Animation-Frames.js** (from `webperf-interaction` skill) - Identify blocking animation frames
+7. **Long-Animation-Frames-Script-Attribution.js** (from `webperf-interaction` skill) - Find scripts causing delays
+
+### Video as LCP Investigation
+
+When LCP is a video element (detected by LCP-Video-Candidate.js):
+
+1. **LCP-Video-Candidate.js** - Identify video as LCP candidate
+2. **Video-Element-Audit.js** (from Media skill) - Audit video loading strategy
+3. **LCP-Subparts.js** - Analyze video loading phases
+4. Cross-reference with **webperf-loading** skill:
+   - Resource-Hints-Validation.js (check for video preload)
+   - Priority-Hints-Audit.js (check for fetchpriority on video)
+
+### Image as LCP Investigation
+
+When LCP is an image (most common case):
+
+1. **LCP.js** - Measure LCP timing
+2. **LCP-Subparts.js** - Break down timing phases
+3. **LCP-Image-Entropy.js** - Analyze image complexity
+4. Cross-reference with **webperf-media** skill:
+   - Image-Element-Audit.js (check format, dimensions, lazy loading)
+5. Cross-reference with **webperf-loading** skill:
+   - Find-Above-The-Fold-Lazy-Loaded-Images.js (check if incorrectly lazy)
+   - Priority-Hints-Audit.js (check for fetchpriority="high")
+   - Resource-Hints-Validation.js (check for preload)
+
+## Decision Tree
+
+Use this decision tree to automatically run follow-up snippets based on results:
+
+### After LCP.js
+
+- **If LCP > 2.5s** → Run **LCP-Sub-Parts.js** to diagnose which phase is slow
+- **If LCP > 4.0s (poor)** → Run full LCP deep dive workflow (5 snippets)
+- **If LCP candidate is an image** → Run **LCP-Image-Entropy.js** and **webperf-media:Image-Element-Audit.js**
+- **If LCP candidate is a video** → Run **LCP-Video-Candidate.js** and **webperf-media:Video-Element-Audit.js**
+- **Always run** → **LCP-Trail.js** to understand candidate evolution
+
+### After LCP-Subparts.js
+
+- **If TTFB phase > 600ms** → Switch to **webperf-loading** skill and run TTFB-Sub-Parts.js
+- **If Resource Load Time > 1500ms** → Run:
+  1. **webperf-loading:Resource-Hints-Validation.js** (check for preload/preconnect)
+  2. **webperf-loading:Priority-Hints-Audit.js** (check fetchpriority)
+  3. **webperf-loading:Find-render-blocking-resources.js** (competing resources)
+- **If Render Delay > 200ms** → Run:
+  1. **webperf-loading:Find-render-blocking-resources.js** (blocking CSS/JS)
+  2. **webperf-loading:Script-Loading.js** (parser-blocking scripts)
+  3. **webperf-interaction:Long-Animation-Frames.js** (main thread blocking)
+
+### After LCP-Trail.js
+
+- **If many LCP candidate changes (>3)** → This causes visual instability, investigate:
+  1. **webperf-loading:Find-Above-The-Fold-Lazy-Loaded-Images.js** (late-loading images)
+  2. **webperf-loading:Fonts-Preloaded-Loaded-and-used-above-the-fold.js** (font swaps)
+  3. **CLS.js** (layout shifts contributing to LCP changes)
+- **If final LCP candidate appears late** → Run **webperf-loading:Resource-Hints-Validation.js**
+- **If early candidate was replaced** → Understand why initial content was pushed down (likely CLS issue)
+
+### After LCP-Image-Entropy.js
+
+- **If entropy is very high** → Image is visually complex, recommend:
+  - Modern formats (WebP, AVIF)
+  - Appropriate compression
+  - Potentially a placeholder strategy
+- **If entropy is low** → Image may be over-optimized or placeholder-like
+- **If large file size detected** → Run **webperf-media:Image-Element-Audit.js** for format/sizing analysis
+
+### After LCP-Video-Candidate.js
+
+- **If video is LCP** → Run:
+  1. **webperf-media:Video-Element-Audit.js** (check poster, preload, formats)
+  2. **webperf-loading:Priority-Hints-Audit.js** (check fetchpriority on poster)
+  3. **LCP-Sub-Parts.js** (analyze video loading phases)
+- **If poster image is LCP** → Treat as image LCP (run image workflows)
+
+### After CLS.js
+
+- **If CLS > 0.1** → Run **webperf-interaction:Layout-Shift-Loading-and-Interaction.js** to separate causes
+- **If CLS > 0.25 (poor)** → Run comprehensive shift investigation:
+  1. **webperf-loading:Find-Above-The-Fold-Lazy-Loaded-Images.js** (images without dimensions)
+  2. **webperf-loading:Fonts-Preloaded-Loaded-and-used-above-the-fold.js** (font loading strategy)
+  3. **webperf-loading:Critical-CSS-Detection.js** (late-loading styles)
+  4. **webperf-media:Image-Element-Audit.js** (missing width/height)
+- **If CLS = 0** → Confirm with multiple page loads (might be timing-dependent)
+
+### After INP.js
+
+- **If INP > 200ms** → Run **webperf-interaction:Interactions.js** to identify slow interactions
+- **If INP > 500ms (poor)** → Run full INP debugging workflow:
+  1. **webperf-interaction:Interactions.js** (list all interactions)
+  2. **webperf-interaction:Input-Latency-Breakdown.js** (phase breakdown)
+  3. **webperf-interaction:Long-Animation-Frames.js** (blocking frames)
+  4. **webperf-interaction:Long-Animation-Frames-Script-Attribution.js** (culprit scripts)
+- **If specific interaction type is slow (e.g., keyboard)** → Focus analysis on that interaction type
+
+### Cross-Skill Triggers
+
+These triggers recommend using snippets from other skills:
+
+#### From LCP to Loading Skill
+
+- **If LCP > 2.5s and TTFB phase is dominant** → Use **webperf-loading** skill:
+  - TTFB.js, TTFB-Sub-Parts.js, Service-Worker-Analysis.js
+
+- **If LCP image is lazy-loaded** → Use **webperf-loading** skill:
+  - Find-Above-The-Fold-Lazy-Loaded-Images.js
+
+- **If LCP has no fetchpriority** → Use **webperf-loading** skill:
+  - Priority-Hints-Audit.js
+
+#### From CLS to Loading Skill
+
+- **If CLS caused by fonts** → Use **webperf-loading** skill:
+  - Fonts-Preloaded-Loaded-and-used-above-the-fold.js
+  - Resource-Hints-Validation.js (for font preload)
+
+- **If CLS caused by images** → Use **webperf-media** skill:
+  - Image-Element-Audit.js (check for width/height attributes)
+
+#### From INP to Interaction Skill
+
+- **If INP > 200ms** → Use **webperf-interaction** skill for full debugging:
+  - Interactions.js, Input-Latency-Breakdown.js
+  - Long-Animation-Frames.js, Long-Animation-Frames-Script-Attribution.js
+  - LongTask.js (if pre-interaction blocking suspected)
+
+#### From LCP/INP to Interaction Skill
+
+- **If render delay or interaction delay is high** → Use **webperf-interaction** skill:
+  - Long-Animation-Frames.js (main thread blocking)
+
+> **Note on cross-skill references:** This skill runs in an isolated subagent (`context: fork`). When a decision tree recommends scripts from another skill (e.g., `webperf-loading`, `webperf-interaction`, `webperf-media`), report the recommendation to the user as a next step — do not attempt to execute those scripts directly. The user or the main agent can activate the appropriate skill to continue the investigation.
+
+## Error Recovery
+
+When a script returns `status: "error"`:
+
+- **LCP/CLS/LCP-Sub-Parts/LCP-Trail** → The page may not have finished loading. Ask the user to wait for full load or reload, then re-run the script.
+- **INP** (`getINP()` returns error) → No interactions have been recorded yet. Remind the user to interact with the page, then call `getINP()` again.
+- **LCP-Image-Entropy** → No images with measurable BPP found. This is normal for text-only pages or pages where all images are data URIs.
+- **LCP-Video-Candidate** → No LCP entries found; see LCP error recovery above.
+
+## Visual Highlighting
+
+By default, scripts highlight the LCP element(s) with colored dashed outlines — useful when the user is watching the browser while the agent runs. To disable:
+
+```js
+window.__cwvHighlight = false;
+// then run any LCP script
+```
+
+Scripts that support this flag: `LCP.js`, `LCP-Sub-Parts.js`, `LCP-Trail.js`.