PageSpeed Optimization Skill

Standalone repository for the pagespeed-optimization Codex skill.

This skill is built to improve real web performance without sacrificing the visual quality, motion, hierarchy, or conversion flow of the page.

What It Does

• Audits pages with PageSpeed Insights and Lighthouse signals in mind.
• Treats field data and lab data separately.
• Prioritizes Core Web Vitals: LCP, INP, and CLS.
• Handles performance work in HTML, Next.js, React, and TypeScript.
• Keeps the UI premium instead of flattening it into a generic low-density layout.

When To Use It

Use this skill when you need to:

• reduce LCP on a real page;
• reduce INP caused by heavy interaction work;
• reduce CLS caused by late-loading UI;
• improve mobile and desktop PageSpeed results;
• implement performance fixes in HTML, Next.js, React, or TypeScript;
• preserve design quality while optimizing speed.

Official Basis

The skill is aligned with the official PageSpeed / Web Vitals guidance and current framework docs:

• PageSpeed Insights
• Web Vitals
• Optimize LCP
• Optimize INP
• Optimize CLS
• Next.js Image docs
• React useTransition
• React useDeferredValue
• TypeScript docs

Included Files

• SKILL.md
• agents/openai.yaml
• references/pagespeed-insights-official-notes.md
• references/optimization-playbook.md
• references/stack-implementations.md
• docs/official-alignment.md

Main Design Rules

• Optimize the actual page experience, not just the score.
• Keep the hero and above-the-fold content intentional.
• Preload only what is truly critical.
• Reserve space for late-loading media and widgets.
• Keep client-side interaction small and isolated.
• Validate mobile and desktop separately.

Validation

The repository is considered healthy when:

• the skill metadata is valid;
• the references match the behavior in SKILL.md;
• the stack examples reflect official guidance;
• no extra skills or unrelated repo noise are added.

Next Step

Publish this repository as the canonical single-skill source and keep Codex installed from this repo if you want a one-skill workspace.