# Web Quality Skills An (unofficial) measurement-first collection of [Agent Skills](https://agentskills.io/) for optimizing web projects with [Google Lighthouse](https://developer.chrome.com/docs/lighthouse/overview/), Chrome DevTools for agents, Core Web Vitals, WCAG, and search guidance. **Stack-agnostic.** Works with any framework: React, Vue, Angular, Svelte, Next.js, Nuxt, Astro, plain HTML, and more. ## Why web quality skills? While interface guidelines tell you *what* to build, Web Quality Skills tell you *how* to build it performantly, accessibly, and optimally for search engines. These skills combine: - **Live Lighthouse audits for agents** across Accessibility, SEO, Best Practices, and Agentic Browsing when Chrome DevTools MCP is available - **Performance traces and Insights** for diagnosing LCP, INP, CLS, network, and main-thread bottlenecks - **Field plus lab measurement** using CrUX for real-user context and controlled browser runs for repeatable diagnosis - **Core Web Vitals** optimization patterns for LCP, INP, and CLS - **WCAG 2.2** accessibility standards - **Modern SEO** requirements ## Available skills | Skill | Description | Use when | |-------|-------------|----------| | **[web-quality-audit](#web-quality-audit)** | Evidence-led review across Lighthouse and source categories | "Audit my site", "Review this for quality", "Check web quality" | | **[performance](#performance)** | Field/lab measurement, traces, loading and runtime fixes | "Optimize performance", "Speed up my site", "Fix slow loading" | | **[core-web-vitals](#core-web-vitals)** | Measured LCP, INP, and CLS diagnosis and optimization | "Improve Core Web Vitals", "Fix LCP", "Reduce CLS" | | **[accessibility](#accessibility)** | WCAG compliance, screen reader support, keyboard navigation | "Improve accessibility", "WCAG audit", "a11y review" | | **[seo](#seo)** | Search engine optimization, crawlability, structured data | "Optimize for SEO", "Improve search ranking", "Fix meta tags" | | **[best-practices](#best-practices)** | Security, modern APIs, code quality patterns | "Apply best practices", "Security audit", "Code quality review" | ## Measurement model The performance skills keep four evidence types explicit: | Evidence | Answers | |----------|---------| | CrUX field data | How eligible real Chrome users experienced the URL or origin over the recent aggregation window | | First-party RUM | How the site's own users experience routes, releases, devices, and interactions | | DevTools trace or Lighthouse lab run | What happened in one controlled browser session and why | | Static source inspection | What might be a problem when the page cannot run | Field data determines user impact. Lab traces reproduce and diagnose it. A `PerformanceObserver` snippet run in one browser is a lab observation, not real-user data by itself. ## Quick start ### Installation add-skill is a powerful CLI tool that lets you install agent skills onto your coding agents from git repositories. Whether you're using OpenCode, Claude Code, Codex, or Cursor, the add-skill tool makes it simple to extend your agent's capabilities with specialized instruction sets. Use add-skill to automate release notes, create pull requests, integrate with external tools, and more. Simply run npx add-skill to get started. ```bash npx skills add addyosmani/web-quality-skills ``` or ``` npx add-skill addyosmani/web-quality-skills ``` Or manually: ```bash cp -r skills/* ~/.claude/skills/ ``` #### Claude Code (plugin) Install as a versioned, namespaced plugin from inside Claude Code: ```text /plugin marketplace add addyosmani/web-quality-skills /plugin install web-quality-skills@addy-web-quality-skills ``` Skills are then namespaced (e.g. `/web-quality-skills:performance`) and update with `/plugin update`. The plugin reads the same `skills/` directory as the manual copy above — no duplication. #### Codex Install directly via the Codex plugin marketplace (Codex CLI v0.122+): ```bash codex plugin marketplace add addyosmani/web-quality-skills ``` Once installed, invoke skills in chat using `@` (e.g. `@performance`, `@accessibility`). See [docs/codex-setup.md](docs/codex-setup.md) for local installation and troubleshooting. #### Gemini CLI Install directly via Gemini CLI extensions: ```bash gemini extensions install https://github.com/addyosmani/web-quality-skills ``` Skills are auto-discovered by Gemini and activate when prompts match their description. See [docs/gemini-setup.md](docs/gemini-setup.md) for workspace mode and troubleshooting. #### claude.ai Add skills to your project knowledge or paste the SKILL.md contents into your conversation. ### Usage Skills activate automatically when your request matches their description. Examples: ``` Audit this page for web quality issues ``` ``` Optimize performance and fix Core Web Vitals ``` ``` Review accessibility and suggest improvements ``` ``` Make this SEO-ready ``` ### Optional Chrome DevTools integration When the agent exposes equivalent live-browser capabilities, the skills prefer them. With [Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp), the current tool names are: - `performance_start_trace` and focused Performance Insights for performance work, including CrUX context when eligible field data exists - `lighthouse_audit` for Accessibility, SEO, Best Practices, and Agentic Browsing - rendered accessibility snapshots, console messages, and network requests for issue-level diagnosis This integration is optional. Without it, the skills fall back to Lighthouse CLI, PageSpeed Insights/CrUX tools, manual browser checks, and static inspection rather than stopping the task. ## Skill details ### web-quality-audit The comprehensive skill that orchestrates all other skills. It starts with live evidence when a page is runnable and keeps measured failures separate from source-code hypotheses. **Trigger phrases:** "audit my site", "quality review", "lighthouse audit", "check web quality" **What it checks:** - All Core Web Vitals metrics - Performance Insights, network delivery, and runtime bottlenecks - Automated and manual accessibility signals - Crawl, index, metadata, and structured-data requirements - Security, compatibility, and browser best-practice patterns - Agentic Browsing signals such as agent-facing semantics and optional WebMCP/`llms.txt` checks ### performance Deep-dive into loading and runtime performance optimization, using CrUX or first-party RUM to prioritize user impact and DevTools traces to diagnose causes. **Trigger phrases:** "speed up", "optimize performance", "reduce load time", "fix slow" **Key optimizations:** - Critical rendering path - JavaScript bundling and code splitting - Image optimization (formats, sizing, lazy loading) - Font loading strategies - Caching and preloading - Server response optimization ### core-web-vitals Specialized skill for the three Core Web Vitals that describe loading, responsiveness, and visual stability. Google uses Core Web Vitals in its page-experience systems, but a passing score does not promise a ranking change. **Trigger phrases:** "Core Web Vitals", "LCP", "INP", "CLS", "page experience" **Metrics covered:** - **LCP** (Largest Contentful Paint) < 2.5s - **INP** (Interaction to Next Paint) < 200ms - **CLS** (Cumulative Layout Shift) < 0.1 ### accessibility Comprehensive accessibility audit following WCAG 2.2 guidelines. **Trigger phrases:** "accessibility", "a11y", "WCAG", "screen reader", "keyboard navigation" **Categories:** - Perceivable (text alternatives, captions, contrast) - Operable (keyboard, timing, seizures, navigation) - Understandable (readable, predictable, input assistance) - Robust (compatible with assistive technologies) ### seo Search engine optimization for better visibility and ranking. **Trigger phrases:** "SEO", "search optimization", "meta tags", "structured data", "sitemap" **What it covers:** - Technical SEO (crawlability, indexability) - On-page SEO (meta tags, headings, content structure) - Structured data (JSON-LD, schema.org) - Mobile-friendliness - Performance signals ### best-practices Modern web development standards and security practices. **Trigger phrases:** "best practices", "security audit", "modern standards", "code quality" **Areas covered:** - HTTPS and security headers - Modern JavaScript APIs - Browser compatibility - Error handling - Console cleanliness ## Thresholds reference ### Core Web Vitals | Metric | Good | Needs improvement | Poor | |--------|------|-------------------|------| | LCP | ≤ 2.5s | 2.5s – 4.0s | > 4.0s | | INP | ≤ 200ms | 200ms – 500ms | > 500ms | | CLS | ≤ 0.1 | 0.1 – 0.25 | > 0.25 | Field Core Web Vitals are assessed at the 75th percentile; these thresholds are not a claim about a single lab run. ### Starting performance budget recommendations These are initial guardrails, not universal thresholds. Set budgets from the product's target devices, networks, page types, and user journeys. | Resource type | Budget | |---------------|--------| | Total page weight | < 1.5 MB | | JavaScript | < 300 KB (compressed) | | CSS | < 100 KB (compressed) | | Images | < 500 KB total above-fold | | Fonts | < 100 KB | | Third-party | < 200 KB | ### Example automated audit guardrails Scores help catch regressions but do not prove accessibility, security, SEO ranking, or user experience. Preserve project-specific targets and compare runs made with the same tool version and conditions. | Category | Example guardrail | |----------|-------------------| | Performance | ≥ 90 | | Accessibility | Aim for 100 automated coverage; complete manual checks | | Best Practices | ≥ 95 | | SEO | ≥ 95 | ## Framework-specific notes These skills are framework-agnostic, but some common patterns: **React/Next.js:** Use `next/image`, `React.lazy()`, `Suspense`, `useCallback`/`useMemo` for INP **Vue/Nuxt:** Use `nuxt/image`, async components, `v-once`, computed properties **Svelte/SvelteKit:** Use `{#await}`, `svelte:image`, reactive statements **Astro:** Use ``, partial hydration, view transitions **Static HTML:** Use native lazy loading, ``, preconnect hints ## Contributing Contributions welcome! Please follow the [Agent Skills specification](https://agentskills.io/specification). 1. Fork the repository 2. Create your skill in `skills/{skill-name}/SKILL.md` 3. Keep SKILL.md under 500 lines (use `references/` for details) 4. Include practical examples and patterns 5. Submit a pull request ## Resources - [Google Lighthouse Documentation](https://developer.chrome.com/docs/lighthouse/) - [Lighthouse audits with AI agents](https://developer.chrome.com/docs/devtools/agents/use-cases/lighthouse-audit) - [Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp) - [Chrome UX Report](https://developer.chrome.com/docs/crux/) - [web.dev Learn Performance](https://web.dev/learn/performance/) - [Core Web Vitals](https://web.dev/articles/vitals) - [WCAG 2.2 Guidelines](https://www.w3.org/WAI/WCAG22/quickref/) - [Agent Skills Specification](https://agentskills.io/specification) ## License MIT License - see [LICENSE](LICENSE) for details. --- Built with insights from the Chrome DevTools team, web performance experts, and accessibility advocates to help developers create high-quality web experiences.