web-quality-skills: Make Your Agent Measure Before It Optimizes

Web performance advice from an LLM sounds authoritative until you measure it: generic lazy-loading tips, guesses about your LCP, accessibility fixes that ignore what screen readers actually hit. addyosmani/web-quality-skills (2.7k stars, from Addy Osmani) is a measurement-first collection that makes the agent gather evidence — Lighthouse audits, Core Web Vitals, CrUX field data, WCAG 2.2 — before it touches your code.

Why This Skill Matters

Six skills split the domain cleanly: web-quality-audit runs an evidence-led review across Lighthouse and source categories; performance handles field/lab measurement, traces, and loading and runtime fixes; core-web-vitals targets LCP, INP, and CLS specifically; accessibility covers WCAG compliance, screen reader support, and keyboard navigation; plus seo and best-practices. The collection is stack-agnostic — React, Vue, Angular, Svelte, Next.js, Nuxt, Astro, or plain HTML.

The differentiator is the measurement model. The skills keep four evidence types explicit: CrUX field data (how real Chrome users experienced the URL), first-party RUM, a DevTools trace or Lighthouse lab run (what happened in one controlled session), and static source inspection (what might be a problem when the page cannot run). The README's discipline — "field data determines user impact, lab traces reproduce and diagnose it" — is exactly the habit generic LLM advice skips.

Installation

The standard installer:

npx skills add addyosmani/web-quality-skills

Or the Claude Code plugin, which namespaces the skills and adds versioned updates:

/plugin marketplace add addyosmani/web-quality-skills
/plugin install web-quality-skills@addy-web-quality-skills

Namespaced invocations look like /web-quality-skills:performance, and /plugin update picks up new versions. Codex CLI v0.122+ has its own marketplace path, and Gemini CLI installs it as an extension — setup docs are linked in the README.

Real Workflow: An Evidence-Led Performance Pass

1. Install the collection and open a session in your project.
2. Prompt the audit skill:

Audit my site for quality and performance issues

3. web-quality-audit gathers Lighthouse results (live audits for agents run when Chrome DevTools MCP is available) and source-level findings, then the performance and core-web-vitals skills diagnose what the numbers mean for LCP, INP, and CLS.
4. Fix what the evidence supports, then re-run the audit to confirm the delta — the README's own loop, not a one-shot rewrite.

The skill descriptions double as triggers: "optimize performance", "fix LCP", "improve accessibility", or "audit my site" route to the right skill without ceremony.

Real Workflow: Separate Field Truth From Lab Noise

Before chasing a synthetic score, ask the field-data side: the skills are written to check CrUX eligibility and real-user context first. The README draws the line sharply — a PerformanceObserver snippet run once in your browser is a lab observation, not real-user data. That framing prevents the classic mistake of optimizing a problem your users do not have.

Tips

• Prefer the plugin install for Claude Code — namespacing keeps the six skills from colliding with other quality tools you may have installed.
• Accessibility work is scoped to WCAG 2.2, screen readers, and keyboard navigation — real audit coverage, not just alt-text reminders.
• Manual install is one copy: cp -r skills/* ~/.claude/skills/ reads the same directory the plugin uses.

When Not to Use This

The skills audit and advise; for continuous performance regression gates in CI you still want Lighthouse CI or similar running the numbers. And if your project already has a mature performance culture, the value here is the evidence-first workflow, not new knowledge.

See the leaderboard for more skills.