our-claude-skills/custom-skills/15-seo-core-web-vitals/code/CLAUDE.md

CLAUDE.md

Overview

Core Web Vitals analyzer using Google PageSpeed Insights API: LCP, FID, CLS, INP, TTFB, FCP measurement and recommendations.

Quick Start

pip install -r scripts/requirements.txt

# Requires API key
export PAGESPEED_API_KEY=your_api_key

python scripts/pagespeed_client.py --url https://example.com

Scripts

Script	Purpose
pagespeed_client.py	PageSpeed Insights API client
base_client.py	Shared utilities

Usage

# Mobile analysis (default)
python scripts/pagespeed_client.py --url https://example.com

# Desktop analysis
python scripts/pagespeed_client.py --url https://example.com --strategy desktop

# Both strategies
python scripts/pagespeed_client.py --url https://example.com --strategy both

# JSON output
python scripts/pagespeed_client.py --url https://example.com --json

# Batch analysis
python scripts/pagespeed_client.py --urls urls.txt --output results.json

Core Web Vitals Metrics

Metric	Good	Needs Improvement	Poor
LCP (Largest Contentful Paint)	≤2.5s	2.5s-4s	>4s
FID (First Input Delay)	≤100ms	100ms-300ms	>300ms
CLS (Cumulative Layout Shift)	≤0.1	0.1-0.25	>0.25
INP (Interaction to Next Paint)	≤200ms	200ms-500ms	>500ms

Additional Metrics

Metric	Description
TTFB	Time to First Byte
FCP	First Contentful Paint
SI	Speed Index
TBT	Total Blocking Time

Output

{
  "url": "https://example.com",
  "strategy": "mobile",
  "score": 85,
  "core_web_vitals": {
    "lcp": {"value": 2.1, "rating": "good"},
    "fid": {"value": 50, "rating": "good"},
    "cls": {"value": 0.05, "rating": "good"},
    "inp": {"value": 180, "rating": "good"}
  },
  "opportunities": [
    {
      "id": "render-blocking-resources",
      "title": "Eliminate render-blocking resources",
      "savings_ms": 1200
    }
  ],
  "diagnostics": []
}

Configuration

Environment variables:

PAGESPEED_API_KEY=AIza...  # Required for higher quotas
GOOGLE_API_KEY=AIza...     # Alternative key name

Rate Limits

Tier	Limit
No API key	25 queries/day
With API key	25,000 queries/day

Common Recommendations

Issue	Fix
Large LCP	Optimize images, preload critical resources
High CLS	Set image dimensions, avoid injected content
Poor INP	Reduce JavaScript, optimize event handlers
Slow TTFB	Improve server response, use CDN

Dependencies

google-api-python-client>=2.100.0
requests>=2.31.0
python-dotenv>=1.0.0
rich>=13.7.0