Web Quality Skills: Measurement-First Agent Skills for Lighthouse and Core Web Vitals

What Web Quality Skills Solves and Who It Is For

Interface guidelines tell developers what to build. Web Quality Skills is aimed at telling AI coding agents how to build it in a way that performs well, passes accessibility audits, and ranks in search engines. The collection is stack-agnostic: the README lists React, Vue, Angular, Svelte, Next.js, Nuxt, Astro, and plain HTML as supported frameworks.

The target user is a developer who already works with an AI coding agent and finds themselves repeatedly prompting the agent to check performance or accessibility without a consistent, structured approach. The skills encode that consistency: each one defines what evidence to gather first, how to distinguish real-user impact from lab observations, and which fixes to prioritise.

The project is published as an unofficial collection by Addy Osmani. It is not an official Google or framework release, and the README makes no claim to that effect.

The Six Available Skills and What Each Checks

The repository provides six skills, each focused on a distinct quality dimension.

The web-quality-audit skill orchestrates all others. It begins with live evidence when a page is runnable, separates measured failures from source-code hypotheses, and checks Core Web Vitals, performance bottlenecks, accessibility signals, crawlability, security, and compatibility in a single pass. It also checks for agentic browsing signals such as agent-facing semantics and optional WebMCP or llms.txt presence.

The performance skill covers field and lab measurement, loading and runtime fixes, critical rendering path, JavaScript bundling and code splitting, image optimisation including format selection and lazy loading, font loading strategies, caching, preloading, and server response time.

The core-web-vitals skill focuses specifically on Largest Contentful Paint, Interaction to Next Paint, and Cumulative Layout Shift. It uses CrUX field data for real-user context and DevTools traces to diagnose causes.

The accessibility skill covers WCAG 2.2 compliance, screen reader support, and keyboard navigation.

The seo skill addresses crawlability, metadata, and structured data.

The best-practices skill covers security patterns, modern API usage, and code quality.

Installing Web Quality Skills into Coding Agents

The quickest installation path uses the add-skill CLI:

npx skills add addyosmani/web-quality-skills

An alternative CLI name also works:

npx add-skill addyosmani/web-quality-skills

For a manual install that does not require npx:

cp -r skills/* ~/.claude/skills/

Inside Claude Code, the skills are available as a versioned, namespaced plugin from the official Anthropic marketplace:

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

After installation, skills are namespaced (for example, /web-quality-skills:performance) and update with /plugin update.

For Codex (version 0.122 or later):

codex plugin marketplace add addyosmani/web-quality-skills

Once installed in Codex, invoke skills in chat using the @ prefix (for example, @performance or @accessibility).

For Gemini CLI:

gemini extensions install https://github.com/addyosmani/web-quality-skills

For Cursor, add the repository as a team marketplace from Settings, then install the aws-core plugin from the Plugins panel. Skills activate automatically when the agent matches a prompt to a skill description.

The Measurement Model: Four Evidence Types

The performance skills distinguish four types of evidence explicitly, and the README states the distinction clearly.

CrUX field data answers how real Chrome users experienced a URL or origin over a recent aggregation window. It reflects actual user conditions: different devices, network speeds, and geographic locations. It does not reflect a single controlled session.

First-party RUM (Real User Monitoring) answers how the site's own users experience routes, releases, devices, and interactions. It requires the site to have its own RUM instrumentation.

DevTools traces or Lighthouse lab runs answer what happened in one controlled browser session and why. They are reproducible and diagnosable, but they reflect one environment.

Static source inspection answers what might be a problem when the page cannot run at all.

The README is explicit that a PerformanceObserver snippet run in one browser is a lab observation, not real-user data by itself. Field data determines user impact. Lab traces reproduce and diagnose it. This distinction matters because optimising for lab scores without field data context can produce misleading results for end users on slower networks or lower-end devices.

Optional Chrome DevTools MCP Integration

When the agent has access to Chrome DevTools MCP, the skills prefer live-browser tools over static analysis. The README lists the current tool names: performance_start_trace and focused Performance Insights for performance work (with CrUX context when eligible field data exists), and lighthouse_audit for accessibility, SEO, best practices, and agentic browsing.

This integration is described as optional. Without it, the skills fall back to Lighthouse CLI, PageSpeed Insights and CrUX tools, manual browser checks, and static inspection. The README states they do not stop the task when Chrome DevTools MCP is unavailable.

The agentic browsing checks, which include agent-facing semantics and optional WebMCP or llms.txt presence, are specific to this skill collection and reflect the growing practice of making web content machine-readable for AI agents as well as human browsers.

Repository Layout and How to Contribute

The repository uses a structured layout. The skills/ directory contains the skill files used by all supported agents. The .claude-plugin/ directory holds the Claude Code plugin manifest. The .cursor-plugin/ directory holds the Cursor plugin configuration. The .agents/ directory holds agent-agnostic skill files. The .gemini/ directory holds Gemini CLI extension metadata. The docs/ directory contains per-agent setup guides, including docs/codex-setup.md and docs/gemini-setup.md.

The AGENTS.md and CLAUDE.md files at the root provide contributor guidance specific to each agent environment. The CHANGELOG.md tracks version history. The licence is MIT.

The repository itself has no runtime dependencies. Each skill is a Markdown file that the agent reads as a set of instructions. Adding a new skill means writing a SKILL.md file and optionally a references/ subdirectory with additional context files that the agent reads from the local filesystem when the skill is active.

Limitations: Where These Skills Cannot Help

The skills can guide an AI agent through a quality review, but they cannot substitute for a human expert in edge cases. WCAG 2.2 compliance involves subjective judgement calls that automated tools do not resolve, such as whether a complex interactive widget is operable with sufficient context for a screen reader user.

CrUX data is only available for URLs with sufficient real-user traffic. New or low-traffic pages have no CrUX field data, which means the measurement model degrades to lab-only evidence. The skills do not document a minimum traffic threshold.

The collection is unofficial. It does not carry formal support from Google, Anthropic, or any framework vendor. Skill files describe instructions for AI agents; if the agent version changes its skill parsing behaviour, a skill that worked before may produce different results. The README does not document a minimum agent version requirement for any of the supported tools except Codex (version 0.122+).

A built-in alternative for Lighthouse audits is running the Lighthouse CLI directly without an AI agent. The Lighthouse CLI gives the same audit results independently of agent interpretation, and the Chrome DevTools performance panel provides raw traces. Those tools require more manual interpretation but have no dependency on a skill file format.

Editorial conclusion

Web Quality Skills is a practical addition for developers who already use AI coding agents and want structured, measurement-first guidance on Lighthouse scores, Core Web Vitals, WCAG compliance, and SEO. It works across any JavaScript framework and installs in a single command into Claude Code, Codex, Cursor, or Gemini CLI. The collection is unofficial and carries no SLA from Google or any framework vendor. Before adopting it on a production workflow, verify that the skill files in the skills/ directory match your agent version's expected format, and confirm that the Chrome DevTools MCP integration is available in your environment if you want live-browser audits rather than static analysis. The last push was on 2026-08-24.

Frequently asked questions

Official sources

1. addyosmani/web-quality-skills on GitHub
2. Issues
3. License: MIT
4. README