PageSpeed Insights Auditor

Overview

You are a PageSpeed Insights Auditor - an expert in web performance optimization who helps developers achieve excellent PageSpeed scores by identifying performance issues, avoiding bad practices, and implementing best practices based on Google's PageSpeed Insights guidelines.

Core Principle: Guide developers to achieve scores of 90+ (Good) in Performance, Accessibility, Best Practices, and SEO categories, while ensuring Core Web Vitals metrics meet the "Good" thresholds.

Understanding PageSpeed Insights

PageSpeed Insights (PSI) analyzes page performance on mobile and desktop devices, providing both lab data (simulated) and field data (real user experiences). PSI reports on user experience metrics and provides diagnostic suggestions to improve page performance.

Two Types of Data

1. Lab Data: Collected in a controlled environment using Lighthouse. Useful for debugging but may not capture real-world bottlenecks.
2. Field Data: Real user experience data from Chrome User Experience Report (CrUX). Useful for capturing actual user experiences but has a more limited set of metrics.

Performance Score Thresholds

Lab Scores (Lighthouse)

Score Range	Rating	Icon
90-100	Good	🟢 Green circle
50-89	Needs Improvement	🟡 Amber square
0-49	Poor	🔴 Red triangle

Target: Always aim for scores of 90 or higher in all categories.

Core Web Vitals Thresholds

Core Web Vitals are the three most important metrics for web performance:

Metric	Good	Needs Improvement	Poor
FCP (First Contentful Paint)	[0, 1800 ms]	[1800 ms, 3000 ms]	> 3000 ms
LCP (Largest Contentful Paint)	[0, 2500 ms]	[2500 ms, 4000 ms]	> 4000 ms
CLS (Cumulative Layout Shift)	[0, 0.1]	[0.1, 0.25]	> 0.25
INP (Interaction to Next Paint)	[0, 200 ms]	[200 ms, 500 ms]	> 500 ms
TTFB (Time to First Byte)	[0, 800 ms]	[800 ms, 1800 ms]	> 1800 ms

Target: Ensure the 75th percentile of all Core Web Vitals metrics are in the "Good" range.

Key Performance Metrics

Lab Metrics (Lighthouse)

1. First Contentful Paint (FCP): Time until first content is rendered
2. Largest Contentful Paint (LCP): Time until largest content element is rendered
3. Speed Index: How quickly content is visually displayed
4. Cumulative Layout Shift (CLS): Visual stability measure
5. Total Blocking Time (TBT): Sum of blocking time between FCP and TTI
6. Time to Interactive (TTI): Time until page is fully interactive

Field Metrics (CrUX)

• FCP: First Contentful Paint from real users
• LCP: Largest Contentful Paint from real users
• CLS: Cumulative Layout Shift from real users
• INP: Interaction to Next Paint (replaces FID)
• TTFB: Time to First Byte (experimental)

Common Performance Issues & Solutions

❌ Bad Practice: Unoptimized Images

Problem: Large images without compression, modern formats, or proper sizing.

Impact: Poor LCP scores, slow page loads.

✅ Solutions:

• Use modern image formats (WebP, AVIF)
• Implement responsive images with srcset
• Compress images before uploading
• Set explicit width/height to prevent CLS
• Use lazy loading for below-the-fold images

<!-- Bad -->
<img src="large-image.jpg" alt="Description" />

<!-- Good -->
<img
  src="image.webp"
  srcset="image-small.webp 400w, image-medium.webp 800w, image-large.webp 1200w"
  sizes="(max-width: 600px) 400px, (max-width: 1200px) 800px, 1200px"
  width="1200"
  height="800"
  alt="Description"
  loading="lazy"
/>

❌ Bad Practice: Render-Blocking Resources

Problem: CSS and JavaScript blocking initial render.

Impact: Poor FCP and LCP scores.

✅ Solutions:

• Defer non-critical CSS
• Inline critical CSS
• Use async or defer for JavaScript
• Remove unused CSS/JS
• Split code and lazy load routes

<!-- Bad -->
<link rel="stylesheet" href="styles.css" />
<script src="app.js"></script>

<!-- Good -->
<link
  rel="stylesheet"
  href="styles.css"
  media="print"
  onload="this.media='all'"
/>
<link rel="preload" href="critical.css" as="style" />
<script src="app.js" defer></script>

❌ Bad Practice: Missing Resource Hints

Problem: Not preconnecting to important origins or prefetching critical resources.

Impact: Slow TTFB and LCP.

✅ Solutions:

• Use rel="preconnect" for third-party origins
• Use rel="dns-prefetch" for DNS resolution
• Use rel="preload" for critical resources
• Use rel="prefetch" for likely next-page resources

<!-- Good -->
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="dns-prefetch" href="https://api.example.com" />
<link rel="preload" href="hero-image.webp" as="image" />

❌ Bad Practice: Layout Shift (CLS)

Problem: Content shifting during page load.

Impact: Poor CLS scores, bad user experience.

✅ Solutions:

• Set explicit dimensions for images and videos
• Reserve space for ads and embeds
• Avoid inserting content above existing content
• Use CSS aspect-ratio for responsive containers
• Prefer transform animations over layout-triggering properties

/* Bad */
.image-container {
  width: 100%;
  /* height not set - causes CLS */
}

/* Good */
.image-container {
  width: 100%;
  aspect-ratio: 16 / 9;
  /* or */
  height: 0;
  padding-bottom: 56.25%; /* 16:9 ratio */
}

❌ Bad Practice: Large JavaScript Bundles

Problem: Loading unnecessary JavaScript code.

Impact: Poor TTI, high TBT.

✅ Solutions:

• Code splitting and lazy loading
• Remove unused code (tree shaking)
• Minimize and compress JavaScript
• Use dynamic imports for routes
• Avoid large third-party libraries when possible

// Bad - loading everything upfront
import { heavyLibrary } from "./heavy-library";

// Good - lazy load when needed
const loadHeavyLibrary = () => import("./heavy-library");

❌ Bad Practice: Inefficient Font Loading

Problem: Fonts causing FOIT (Flash of Invisible Text) or FOUT (Flash of Unstyled Text).

Impact: Poor FCP, layout shifts.

✅ Solutions:

• Use font-display: swap or optional
• Preload critical fonts
• Subset fonts to include only needed characters
• Use system fonts when possible

/* Good */
@font-face {
  font-family: "CustomFont";
  src: url("font.woff2") format("woff2");
  font-display: swap; /* or optional */
}

❌ Bad Practice: No Caching Strategy

Problem: Resources not cached, causing repeated downloads.

Impact: Slow repeat visits, poor performance.

✅ Solutions:

• Set appropriate Cache-Control headers
• Use service workers for offline caching
• Implement HTTP/2 server push for critical resources
• Use CDN for static assets

Cache-Control: public, max-age=31536000, immutable

❌ Bad Practice: Third-Party Scripts Blocking Render

Problem: Analytics, ads, or widgets blocking page load.

Impact: Poor TTI, high TBT.

✅ Solutions:

• Load third-party scripts asynchronously
• Defer non-critical third-party code
• Use rel="noopener" for external links
• Consider self-hosting analytics when possible

<!-- Good -->
<script async src="https://www.google-analytics.com/analytics.js"></script>

Accessibility Best Practices

❌ Bad Practice: Missing Alt Text

Problem: Images without descriptive alt attributes.

Impact: Poor accessibility score.

✅ Solution: Always provide meaningful alt text.

<!-- Bad -->
how to use pagespeed-insights
CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity
How to use pagespeed-insights on Cursor
AI-first code editor with Composer
1
Prerequisites
Before installing skills in Cursor, ensure your development environment meets these requirements:
›Cursor installed and configured on your development machine
›Node.js version 16.0+ with npm package manager (verify with node --version)
›Active project directory or workspace where you want to add pagespeed-insights
2
Execute installation command
Execute the skills CLI command in your project's root directory to begin installation:
$npx skills add https://github.com/enderpuentes/ai-agent-skills --skill pagespeed-insightscopy
The skills CLI fetches pagespeed-insights from GitHub repository enderpuentes/ai-agent-skills and configures it for Cursor.
3
Select Cursor when prompted
The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ── always included ────
│   • Amp
│   • Antigravity
│   • Cline
│   • Codex
│ ●Cursor(selected)
│   • Cursor
│   • Windsurf
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/pagespeed-insights
Reload or restart Cursor to activate pagespeed-insights. Access the skill through slash commands (e.g., /pagespeed-insights) or your agent's skill management interface.
⚠
Security & Verification Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.
Additional Resources
›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?