Merge pull request #61 from nucliweb/feat/agent-skills

Agent SKILLs

Author: nucliweb

.claude/settings.json

@@ -0,0 +1,22 @@
+{
+  "skills": [
+    {
+      "path": "./skills/webperf"
+    },
+    {
+      "path": "./skills/webperf-core-web-vitals"
+    },
+    {
+      "path": "./skills/webperf-interaction"
+    },
+    {
+      "path": "./skills/webperf-loading"
+    },
+    {
+      "path": "./skills/webperf-media"
+    },
+    {
+      "path": "./skills/webperf-resources"
+    }
+  ]
+}

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

@@ -0,0 +1,311 @@
+---
+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. Compatible with Chrome DevTools MCP.
+---
+
+# WebPerf: Core Web Vitals
+
+JavaScript snippets for measuring web performance in Chrome DevTools. Execute with `mcp__chrome-devtools__evaluate_script`, capture output with `mcp__chrome-devtools__get_console_message`.
+
+## Available Snippets
+
+| Snippet | Description | File |
+|---------|-------------|------|
+| Cumulative Layout Shift (CLS) | Quick check for Cumulative Layout Shift, a Core Web Vital that measures visual stability | scripts/CLS.js |
+| Interaction to Next Paint (INP) | Tracks Interaction to Next Paint, a Core Web Vital that measures responsiveness | scripts/INP.js |
+| LCP Image Entropy | Checks if images qualify as LCP candidates based on their entropy (bits per pixel) | scripts/LCP-Image-Entropy.js |
+| LCP Sub-Parts | Breaks down Largest Contentful Paint into its four phases to identify optimization opportunities | scripts/LCP-Sub-Parts.js |
+| LCP Trail | Tracks every LCP candidate element during page load and highlights each one with a distinct pastel-c | scripts/LCP-Trail.js |
+| LCP Video Candidate | Detects whether the LCP element is a <video> and audits the poster image configuration — the most co | scripts/LCP-Video-Candidate.js |
+| Largest Contentful Paint (LCP) | Quick check for Largest Contentful Paint, a Core Web Vital that measures loading performance | scripts/LCP.js |
+
+## Execution with Chrome DevTools MCP
+
+```
+1. mcp__chrome-devtools__navigate_page  → navigate to target URL
+2. mcp__chrome-devtools__evaluate_script → run snippet code (read from scripts/ file)
+3. mcp__chrome-devtools__get_console_message → capture console output
+4. Interpret results using thresholds below, provide recommendations
+```
+
+## 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-Sub-Parts.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-Sub-Parts.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 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** - Measure overall INP value
+2. **Interactions.js** (from Interaction skill) - List all interactions with timing
+3. **Input-Latency-Breakdown.js** (from Interaction skill) - Break down input delay, processing, presentation
+4. **Long-Animation-Frames.js** (from Interaction skill) - Identify blocking animation frames
+5. **Long-Animation-Frames-Script-Attribution.js** (from 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-Sub-Parts.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-Sub-Parts.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-Sub-Parts.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)
+  - LongTask.js (long tasks delaying rendering)
+
+### Multi-Metric Correlation
+
+When multiple CWV metrics are poor, prioritize investigation:
+
+- **If LCP > 2.5s AND CLS > 0.1** → Likely shared root cause:
+  1. Check for late-loading content pushing LCP element
+  2. Run LCP-Trail.js to see LCP candidate changes
+  3. Run Layout-Shift-Loading-and-Interaction.js to correlate timing
+
+- **If LCP > 2.5s AND INP > 200ms** → Main thread congestion:
+  1. Run Long-Animation-Frames.js
+  2. Run webperf-loading:Script-Loading.js
+  3. Run webperf-loading:JS-Execution-Time-Breakdown.js
+
+- **If CLS > 0.1 AND INP > 200ms** → Layout thrashing or interaction-triggered shifts:
+  1. Run Layout-Shift-Loading-and-Interaction.js
+  2. Run Interactions.js
+  3. Check if shifts occur during/after interactions
+
+---
+
+---
+
+## Cumulative Layout Shift (CLS)
+
+Quick check for Cumulative Layout Shift, a Core Web Vital that measures visual stability. CLS tracks how much the page layout shifts unexpectedly during its lifetime, providing a single score that represents the cumulative impact of all unexpected layout shifts.
+
+**Script:** `scripts/CLS.js`
+
+**Thresholds:**
+
+| Rating | Score | Meaning |
+|--------|-------|---------|
+| 🟢 Good | ≤ 0.1 | Stable, minimal shifting |
+| 🟡 Needs Improvement | ≤ 0.25 | Noticeable shifting |
+| 🔴 Poor | > 0.25 | Significant layout instability |
+
+---
+
+## Interaction to Next Paint (INP)
+
+Tracks Interaction to Next Paint, a Core Web Vital that measures responsiveness. INP evaluates how quickly a page responds to user interactions throughout the entire page visit, replacing First Input Delay (FID) as a Core Web Vital in March 2024.
+
+**Script:** `scripts/INP.js`
+
+**Thresholds:**
+
+| Rating | Time | Meaning |
+|--------|------|---------|
+| 🟢 Good | ≤ 200ms | Responsive, feels instant |
+| 🟡 Needs Improvement | ≤ 500ms | Noticeable delay |
+| 🔴 Poor | > 500ms | Slow, frustrating experience |
+
+---
+
+## LCP Image Entropy
+
+Checks if images qualify as LCP candidates based on their entropy (bits per pixel). Since Chrome 112, low-entropy images are ignored for LCP measurement.
+
+**Script:** `scripts/LCP-Image-Entropy.js`
+
+**Thresholds:**
+
+| BPP | Entropy | LCP Eligible | Example |
+|-----|---------|--------------|---------|
+| < 0.05 | 🔴 Low | ❌ No | Solid colors, simple gradients, placeholders |
+| ≥ 0.05 | 🟢 Normal | ✅ Yes | Photos, complex graphics |
+
+---
+
+## LCP Sub-Parts
+
+Breaks down Largest Contentful Paint into its four phases to identify optimization opportunities. Understanding which phase is slowest helps you focus your optimization efforts where they'll have the most impact. Based on the Web Vitals Chrome Extension.
+
+**Script:** `scripts/LCP-Sub-Parts.js`
+
+---
+
+## LCP Trail
+
+Tracks every LCP candidate element during page load and highlights each one with a distinct pastel-colored dashed outline — so you can see the full trail from first candidate to final LCP.
+
+**Script:** `scripts/LCP-Trail.js`
+
+---
+
+## LCP Video Candidate
+
+Detects whether the LCP element is a <video> and audits the poster image configuration — the most common source of avoidable LCP delay when video is the hero element.
+
+**Script:** `scripts/LCP-Video-Candidate.js`
+
+---
+
+## Largest Contentful Paint (LCP)
+
+Quick check for Largest Contentful Paint, a Core Web Vital that measures loading performance. LCP marks when the largest content element becomes visible in the viewport.
+
+**Script:** `scripts/LCP.js`
+
+**Thresholds:**
+
+| Rating | Time | Meaning |
+|--------|------|---------|
+| 🟢 Good | ≤ 2.5s | Fast, content appears quickly |
+| 🟡 Needs Improvement | ≤ 4s | Moderate delay |
+| 🔴 Poor | > 4s | Slow, users may abandon |

.claude/skills/webperf-core-web-vitals/scripts/CLS.js

@@ -0,0 +1,56 @@
+// CLS Quick Check
+// https://webperf-snippets.nucliweb.net
+
+(() => {
+  let cls = 0;
+
+  const valueToRating = (score) =>
+    score <= 0.1 ? "good" : score <= 0.25 ? "needs-improvement" : "poor";
+
+  const RATING = {
+    good: { icon: "🟢", color: "#0CCE6A" },
+    "needs-improvement": { icon: "🟡", color: "#FFA400" },
+    poor: { icon: "🔴", color: "#FF4E42" },
+  };
+
+  const logCLS = () => {
+    const rating = valueToRating(cls);
+    const { icon, color } = RATING[rating];
+    console.log(
+      `%cCLS: ${icon} ${cls.toFixed(4)} (${rating})`,
+      `color: ${color}; font-weight: bold; font-size: 14px;`
+    );
+  };
+
+  const observer = new PerformanceObserver((list) => {
+    for (const entry of list.getEntries()) {
+      if (!entry.hadRecentInput) {
+        cls += entry.value;
+      }
+    }
+    logCLS();
+  });
+
+  observer.observe({ type: "layout-shift", buffered: true });
+
+  // Update on visibility change (final CLS)
+  document.addEventListener("visibilitychange", () => {
+    if (document.visibilityState === "hidden") {
+      observer.takeRecords();
+      console.log("%c📊 Final CLS (on page hide):", "font-weight: bold;");
+      logCLS();
+    }
+  });
+
+  // Expose function for manual check
+  window.getCLS = () => {
+    logCLS();
+    return cls;
+  };
+
+  console.log(
+    "   Call %cgetCLS()%c anytime to check current value.",
+    "font-family: monospace; background: #f3f4f6; padding: 2px 4px;",
+    ""
+  );
+})();