Skip to content
BranchesTags

Repository files navigation

Google PageSpeed & Core Web Vitals Optimization Toolkit

License: MIT Core Web Vitals Lighthouse 13.x Maintained by ApexionSoft

The definitive, production-ready engineering toolkit and AI Agent Skill for achieving 90–100 (Green) scores on Google PageSpeed Insights, passing Core Web Vitals, and mastering Mobile-First Indexing.

Overview • Core Metrics • Audit Guide (API & CLI) • AI Agent Integration • Repository Structure • Recipes • About ApexionSoft

⚡ Overview

Achieving top-tier performance on Google PageSpeed Insights (PSI) is no longer just about minifying scripts—it is a rigorous, mathematical discipline governed by Core Web Vitals (CWVs), Mobile-First Indexing, Lighthouse 13.x scoring algorithms, and field user experience telemetry (Chrome UX Report / CrUX).

This repository provides an enterprise-grade optimization suite engineered by ApexionSoft. It includes:

  1. Universal AI Agent Skill (SKILL.md): Drop-in intelligence for AI coding agents (Google Antigravity, Claude Code, Cursor, Windsurf, Copilot, ChatGPT) to autonomously audit codebases, diagnose bottlenecks, and generate mathematically validated remediation patches.
  2. Automated Audit Tools: Production-ready Python and PowerShell CLI tools to run Google PageSpeed Insights API audits and local headless Lighthouse audits.
  3. Production Code Recipes: Battle-tested configurations for Nginx, Apache, Cloudflare, Next.js, Astro, and modern JavaScript environments.
  4. Engineering Checklists: Step-by-step checklists for Core Web Vitals, WCAG 2.2 Accessibility, and Technical SEO.
  5. Technical References: Complete source-extracted guides on all Lighthouse audits, 46 PageSpeed SDK C++ rules, scoring formulas, Long Animation Frames (LoAF), Speculation Rules API, and bfcache integrity.

📊 Core Web Vitals Reference

Google evaluates websites at the 75th percentile of real-world user visits (28-day CrUX dataset):

Metric Full Name Type 🟢 Good (Pass) 🟡 Needs Improvement 🔴 Poor (Fail) Lighthouse Weight
LCP Largest Contentful Paint Core Web Vital ≤ 2.5s 2.5s – 4.0s > 4.0s 25%
INP Interaction to Next Paint Core Web Vital ≤ 200ms 200ms – 500ms > 500ms (Field Only)
CLS Cumulative Layout Shift Core Web Vital ≤ 0.1 0.1 – 0.25 > 0.25 25%
FCP First Contentful Paint Diagnostic ≤ 1.8s 1.8s – 3.0s > 3.0s 10%
TTFB Time to First Byte Diagnostic ≤ 800ms 800ms – 1800ms > 1800ms —
TBT Total Blocking Time Lab Metric ≤ 200ms 200ms – 600ms > 600ms 30%
SI Speed Index Diagnostic ≤ 3.4s 3.4s – 5.8s > 5.8s 10% 
┌────────────────────────────────────────────────────────┐
│             Lighthouse Performance Weighting           │
├────────────────────────────────────┬───────────────────┤
│ Total Blocking Time (TBT)          │ 30%               │
│ Largest Contentful Paint (LCP)     │ 25%               │
│ Cumulative Layout Shift (CLS)      │ 25%               │
│ First Contentful Paint (FCP)       │ 10%               │
│ Speed Index (SI)                   │ 10%               │
└────────────────────────────────────┴───────────────────┘

Target Priority: Resolving TBT + LCP + CLS addresses 80% of total performance score deductions instantly.

🔍 PageSpeed Audit Guide & CLI Tools

This toolkit includes standalone, production-ready CLI tools to test your web applications without manual browser clicking.

Method 1: Google PageSpeed Insights API Auditor (scripts/psi-audit.py)

Calls Google's official REST API to test live, publicly accessible websites and returns real-time scores for Performance, Accessibility, Best Practices, and SEO, along with all Core Web Vitals.

1. Quick Audit (Mobile - Zero Config)

python scripts/psi-audit.py --url https://your-site.com

2. Desktop Audit

python scripts/psi-audit.py --url https://your-site.com --strategy desktop

3. Using an API Key (Recommended for CI/CD & Batch Runs)

Google allows anonymous requests with public rate limits. To avoid HTTP 429 rate limit errors, get a free API key from Google Cloud Console.

Option A: Pass via CLI argument

python scripts/psi-audit.py --url https://your-site.com --key YOUR_API_KEY

Option B: Set environment variable (Persistent)

# Linux / macOS
export PAGESPEED_API_KEY="your_api_key_here"

# Windows PowerShell
$env:PAGESPEED_API_KEY="your_api_key_here"

# Windows Command Prompt
set PAGESPEED_API_KEY=your_api_key_here

4. Export Audit Report as Markdown

python scripts/psi-audit.py --url https://your-site.com --strategy mobile --output audit-report.md

Method 2: Local Headless Lighthouse Runner (scripts/run-audit.ps1)

For local development environments (localhost, staging servers) or CI runners where the URL is not publicly accessible via the Google API.

Requires Node.js and Google Chrome installed.

# Run mobile audit on localhost or staging
powershell -ExecutionPolicy Bypass -File .\scripts\run-audit.ps1 -Url "http://localhost:3000"

# Custom report output path
powershell -ExecutionPolicy Bypass -File .\scripts\run-audit.ps1 -Url "https://staging.example.com" -OutputPath "./reports/staging-audit.json"

Method 3: Automated Image Conversion (scripts/convert-images-webp.py)

Recursively compresses directories of legacy JPG/PNG images into modern responsive WebP and AVIF assets:

python scripts/convert-images-webp.py --input ./public/images --quality 82 --generate-avif

🤖 AI Agent Skill Integration

This repository contains SKILL.md, an 80+ KB (1,950+ lines), 36-section universal agent skill definition compatible with modern AI development environments.

Supported Platforms:

  • Google Antigravity: Place in ~/.gemini/config/skills/google-pagespeed/SKILL.md or .agents/skills/google-pagespeed/SKILL.md.
  • Claude Code: Place in your .claude/skills/google-pagespeed/SKILL.md directory.
  • Cursor / Windsurf / Copilot: Link inside your workspace .cursorrules or .windsurfrules.

What the AI Agent Automatically Enforces:

  • Enforces explicit width, height, and fetchpriority="high" on LCP hero media.
  • Refuses to lazy-load above-the-fold content.
  • Restructures event handlers and long tasks using scheduler.yield().
  • Validates WCAG 2.2 accessibility touch target sizes ($\ge 48\times 48\text{px}$).
  • Automatically inlines critical path CSS (< 14 KiB) and configures 1-year immutable asset caching.
  • Enforces strict security headers: CSP, COOP, COEP, HSTS, and X-Content-Type-Options.

📁 Repository Structure

.
├── .github/
│   └── ISSUE_TEMPLATE/
│       ├── bug_report.md
│       └── feature_request.md
├── assets/                               # Architecture diagrams and benchmark assets
├── checklists/
│   ├── budget.json                       # Lighthouse performance budget definition
│   ├── core-web-vitals-audit-checklist.md # 35-point performance audit checklist
│   ├── wcag-2.2-accessibility-checklist.md # Accessibility & a11y compliance
│   └── technical-seo-checklist.md        # Crawlability, indexing, and meta standards
├── examples/
│   ├── lighthouse-ci.yml                 # GitHub Actions performance regression workflow
│   ├── nginx.conf                        # Enterprise Nginx caching, Brotli & security headers
│   ├── apache.htaccess                   # Optimized Apache .htaccess configuration
│   ├── next.config.js                    # Next.js performance and bundle optimization
│   ├── astro.config.mjs                  # Astro island architecture & image setup
│   ├── speculation-rules.html            # 0-second instant page prerendering
│   ├── responsive-picture-pattern.html   # AVIF/WebP responsive image implementation
│   ├── critical-css-pattern.html         # Critical CSS inlining and async stylesheets
│   └── web-worker-task-splitting.js      # Main-thread unblocking with scheduler.yield
├── references/
│   ├── core-web-vitals-encyclopedia.md   # Deep architectural guide & rendering internals
│   ├── lighthouse-audits-full.md         # Source-extracted index of all Lighthouse audits
│   ├── lighthouse-scoring-weights.md     # Mathematical breakdown of scoring algorithms
│   ├── pagespeed-rules-full.md           # All 46 Google PageSpeed SDK C++ rules & constants
│   └── scoring-methodology.md            # In-depth scoring curves, log-normal math & throttling
├── scripts/
│   ├── psi-audit.py                      # Google PageSpeed API CLI audit tool (Python)
│   ├── run-audit.ps1                     # Local headless Lighthouse audit runner (PowerShell)
│   └── convert-images-webp.py            # Batch image converter to WebP/AVIF (Python)
├── CONTRIBUTING.md                       # Contribution guidelines
├── LICENSE                               # MIT License
├── package.json                          # Project metadata and npm scripts
├── README.md                             # Repository homepage documentation
├── SECURITY.md                           # Security policy and vulnerability reporting
└── SKILL.md                              # Universal AI Agent Skill specification (36 Sections)

🛠️ Production Recipes

1. Instant Navigation with Speculation Rules API

Load pages in 0.0 seconds by prerendering probable next navigations during user hover:

<script type="speculationrules">
{
  "prerender": [
    {
      "source": "list",
      "urls": ["/products", "/services", "/about"],
      "eagerness": "moderate"
    }
  ]
}
</script>

2. Main-Thread Yielding for Zero INP Latency

Break up computational JavaScript execution into micro-tasks:

async function yieldToMain() {
  if ('scheduler' in window && 'yield' in window.scheduler) {
    await window.scheduler.yield();
  } else {
    await new Promise(resolve => setTimeout(resolve, 0));
  }
}

3. Bulletproof Responsive Images

Serve next-gen formats with zero layout shifting (CLS < 0.01):

<picture>
  <source srcset="/img/hero-400.avif 400w, /img/hero-800.avif 800w, /img/hero-1200.avif 1200w"
          sizes="(max-width: 600px) 100vw, (max-width: 1024px) 800px, 1200px"
          type="image/avif" />
  <source srcset="/img/hero-400.webp 400w, /img/hero-800.webp 800w, /img/hero-1200.webp 1200w"
          sizes="(max-width: 600px) 100vw, (max-width: 1024px) 800px, 1200px"
          type="image/webp" />
  <img src="/img/hero-800.webp"
       width="1200" height="675"
       alt="Enterprise performance dashboard"
       loading="eager"
       fetchpriority="high"
       decoding="async"
       style="width: 100%; height: auto; aspect-ratio: 16/9; object-fit: cover;" />
</picture>

🚀 Continuous Integration (Lighthouse CI)

Enforce performance budgets on every pull request using GitHub Actions. See examples/lighthouse-ci.yml:

name: Performance Audit Gate
on: [push, pull_request]
jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Audit URL with Lighthouse CI
        uses: treosh/lighthouse-ci-action@v12
        with:
          urls: |
            https://staging.example.com/
          budgetPath: ./checklists/budget.json
          uploadArtifacts: true

🏢 Maintained & Engineered by ApexionSoft

ApexionSoft

(formerly Pearl IT)

Premier Digital Agency in Bangladesh

We specialize in Web & App Development, Enterprise Cloud Architecture, Performance Engineering, SEO, and Digital Growth Strategy.

🌐 Website: https://www.apexionsoft.com/
🐙 GitHub: https://github.com/ApexionSoft
📧 Inquiries & Commercial Consulting: contact@apexionsoft.com / info@apexionsoft.com

Need Enterprise Performance Optimization?

ApexionSoft provides bespoke web performance engineering, Core Web Vitals remediation, and cloud scaling services for enterprise clients worldwide. Contact our engineering team to schedule an audit.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.
Copyright © 2026 ApexionSoft. All rights reserved.

About

Universal AI Agent Skill, production recipes, audit checklists, and automation tools for Google PageSpeed Insights & Core Web Vitals optimization by ApexionSoft.

www.apexionsoft.com/

Topics

ai-agent-skillantigravity-skillapexionsoftclaude-skillclscore-web-vitalsinplcplighthousepagespeedperformance-optimizationseoweb-performance

Resources

Readme
MIT license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

1 star

Watchers

1 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages