Skip to content
Back to search

addy-web-quality-skills

MarketplaceWorks with Claude CodeGitHub

Agent Skills for optimizing web quality based on Lighthouse and Core Web Vitals.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/addyosmani-web-quality-skills/badge.svg)](/listings/addyosmani-web-quality-skills)

HTML

<a href="/listings/addyosmani-web-quality-skills"><img src="/api/listings/addyosmani-web-quality-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

npx skills add addyosmani/web-quality-skills

or

npx add-skill addyosmani/web-quality-skills

Or manually:

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

Claude Code (plugin)

Install as a versioned, namespaced plugin from inside Claude Code:

/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+):

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:

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 16 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "addy-web-quality-skills",
  3. "owner": {
  4. "name": "Addy Osmani"
  5. },
  6. "metadata": {
  7. "description": "Measurement-first Agent Skills for Lighthouse, Chrome DevTools, Core Web Vitals, WCAG 2.2, SEO, and agentic browsing."
  8. },
  9. "plugins": [
  10. {
  11. "name": "web-quality-skills",
  12. "source": "./",
  13. "description": "Measured performance, Core Web Vitals, accessibility, SEO, best-practices, and agentic browsing skills for any web stack."
  14. }
  15. ]
  16. }
README.md · README · 281 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Web Quality Skills
  2. 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.
  3. **Stack-agnostic.** Works with any framework: React, Vue, Angular, Svelte, Next.js, Nuxt, Astro, plain HTML, and more.
  4. ## Why web quality skills?
  5. 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:
  6. - **Live Lighthouse audits for agents** across Accessibility, SEO, Best Practices, and Agentic Browsing when Chrome DevTools MCP is available
  7. - **Performance traces and Insights** for diagnosing LCP, INP, CLS, network, and main-thread bottlenecks
  8. - **Field plus lab measurement** using CrUX for real-user context and controlled browser runs for repeatable diagnosis
  9. - **Core Web Vitals** optimization patterns for LCP, INP, and CLS
  10. - **WCAG 2.2** accessibility standards
  11. - **Modern SEO** requirements
  12. ## Available skills
  13. | Skill | Description | Use when |
  14. |-------|-------------|----------|
  15. | **[web-quality-audit](#web-quality-audit)** | Evidence-led review across Lighthouse and source categories | "Audit my site", "Review this for quality", "Check web quality" |
  16. | **[performance](#performance)** | Field/lab measurement, traces, loading and runtime fixes | "Optimize performance", "Speed up my site", "Fix slow loading" |
  17. | **[core-web-vitals](#core-web-vitals)** | Measured LCP, INP, and CLS diagnosis and optimization | "Improve Core Web Vitals", "Fix LCP", "Reduce CLS" |
  18. | **[accessibility](#accessibility)** | WCAG compliance, screen reader support, keyboard navigation | "Improve accessibility", "WCAG audit", "a11y review" |
  19. | **[seo](#seo)** | Search engine optimization, crawlability, structured data | "Optimize for SEO", "Improve search ranking", "Fix meta tags" |
  20. | **[best-practices](#best-practices)** | Security, modern APIs, code quality patterns | "Apply best practices", "Security audit", "Code quality review" |
  21. ## Measurement model
  22. The performance skills keep four evidence types explicit:
  23. | Evidence | Answers |
  24. |----------|---------|
  25. | CrUX field data | How eligible real Chrome users experienced the URL or origin over the recent aggregation window |
  26. | First-party RUM | How the site's own users experience routes, releases, devices, and interactions |
  27. | DevTools trace or Lighthouse lab run | What happened in one controlled browser session and why |
  28. | Static source inspection | What might be a problem when the page cannot run |
  29. 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.
  30. ## Quick start
  31. ### Installation
  32. 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.
  33. ```bash
  34. npx skills add addyosmani/web-quality-skills
  35. ```
  36. or
  37. ```
  38. npx add-skill addyosmani/web-quality-skills
  39. ```
  40. Or manually:
  41. ```bash
  42. cp -r skills/* ~/.claude/skills/
  43. ```
  44. #### Claude Code (plugin)
  45. Install as a versioned, namespaced plugin from inside Claude Code:
  46. ```text
  47. /plugin marketplace add addyosmani/web-quality-skills
  48. /plugin install web-quality-skills@addy-web-quality-skills
  49. ```
  50. 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.
  51. #### Codex
  52. Install directly via the Codex plugin marketplace (Codex CLI v0.122+):
  53. ```bash
  54. codex plugin marketplace add addyosmani/web-quality-skills
  55. ```
  56. 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.
  57. #### Gemini CLI
  58. Install directly via Gemini CLI extensions:
  59. ```bash
  60. gemini extensions install https://github.com/addyosmani/web-quality-skills
  61. ```
  62. 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.
  63. #### claude.ai
  64. Add skills to your project knowledge or paste the SKILL.md contents into your conversation.
  65. ### Usage
  66. Skills activate automatically when your request matches their description. Examples:
  67. ```
  68. Audit this page for web quality issues
  69. ```
  70. ```
  71. Optimize performance and fix Core Web Vitals
  72. ```
  73. ```
  74. Review accessibility and suggest improvements
  75. ```
  76. ```
  77. Make this SEO-ready
  78. ```
  79. ### Optional Chrome DevTools integration
  80. 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:
  81. - `performance_start_trace` and focused Performance Insights for performance work, including CrUX context when eligible field data exists
  82. - `lighthouse_audit` for Accessibility, SEO, Best Practices, and Agentic Browsing
  83. - rendered accessibility snapshots, console messages, and network requests for issue-level diagnosis
  84. 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.
  85. ## Skill details
  86. ### web-quality-audit
  87. 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.
  88. **Trigger phrases:** "audit my site", "quality review", "lighthouse audit", "check web quality"
  89. **What it checks:**
  90. - All Core Web Vitals metrics
  91. - Performance Insights, network delivery, and runtime bottlenecks
  92. - Automated and manual accessibility signals
  93. - Crawl, index, metadata, and structured-data requirements
  94. - Security, compatibility, and browser best-practice patterns
  95. - Agentic Browsing signals such as agent-facing semantics and optional WebMCP/`llms.txt` checks
  96. ### performance
  97. Deep-dive into loading and runtime performance optimization, using CrUX or first-party RUM to prioritize user impact and DevTools traces to diagnose causes.
  98. **Trigger phrases:** "speed up", "optimize performance", "reduce load time", "fix slow"
  99. **Key optimizations:**
  100. - Critical rendering path
  101. - JavaScript bundling and code splitting
  102. - Image optimization (formats, sizing, lazy loading)
  103. - Font loading strategies
  104. - Caching and preloading
  105. - Server response optimization
  106. ### core-web-vitals
  107. 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.
  108. **Trigger phrases:** "Core Web Vitals", "LCP", "INP", "CLS", "page experience"
  109. **Metrics covered:**
  110. - **LCP** (Largest Contentful Paint) < 2.5s
  111. - **INP** (Interaction to Next Paint) < 200ms
  112. - **CLS** (Cumulative Layout Shift) < 0.1
  113. ### accessibility
  114. Comprehensive accessibility audit following WCAG 2.2 guidelines.
  115. **Trigger phrases:** "accessibility", "a11y", "WCAG", "screen reader", "keyboard navigation"
  116. **Categories:**
  117. - Perceivable (text alternatives, captions, contrast)
  118. - Operable (keyboard, timing, seizures, navigation)
  119. - Understandable (readable, predictable, input assistance)
  120. - Robust (compatible with assistive technologies)
  121. ### seo
  122. Search engine optimization for better visibility and ranking.
  123. **Trigger phrases:** "SEO", "search optimization", "meta tags", "structured data", "sitemap"
  124. **What it covers:**
  125. - Technical SEO (crawlability, indexability)
  126. - On-page SEO (meta tags, headings, content structure)
  127. - Structured data (JSON-LD, schema.org)
  128. - Mobile-friendliness
  129. - Performance signals
  130. ### best-practices
  131. Modern web development standards and security practices.
  132. **Trigger phrases:** "best practices", "security audit", "modern standards", "code quality"
  133. **Areas covered:**
  134. - HTTPS and security headers
  135. - Modern JavaScript APIs
  136. - Browser compatibility
  137. - Error handling
  138. - Console cleanliness
  139. ## Thresholds reference
  140. ### Core Web Vitals
  141. | Metric | Good | Needs improvement | Poor |
  142. |--------|------|-------------------|------|
  143. | LCP | ≤ 2.5s | 2.5s – 4.0s | > 4.0s |
  144. | INP | ≤ 200ms | 200ms – 500ms | > 500ms |
  145. | CLS | ≤ 0.1 | 0.1 – 0.25 | > 0.25 |
  146. Field Core Web Vitals are assessed at the 75th percentile; these thresholds are not a claim about a single lab run.
  147. ### Starting performance budget recommendations
  148. These are initial guardrails, not universal thresholds. Set budgets from the product's target devices, networks, page types, and user journeys.
  149. | Resource type | Budget |
  150. |---------------|--------|
  151. | Total page weight | < 1.5 MB |
  152. | JavaScript | < 300 KB (compressed) |
  153. | CSS | < 100 KB (compressed) |
  154. | Images | < 500 KB total above-fold |
  155. | Fonts | < 100 KB |
  156. | Third-party | < 200 KB |
  157. ### Example automated audit guardrails
  158. 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.
  159. | Category | Example guardrail |
  160. |----------|-------------------|
  161. | Performance | ≥ 90 |
  162. | Accessibility | Aim for 100 automated coverage; complete manual checks |
  163. | Best Practices | ≥ 95 |
  164. | SEO | ≥ 95 |
  165. ## Framework-specific notes
  166. These skills are framework-agnostic, but some common patterns:
  167. **React/Next.js:** Use `next/image`, `React.lazy()`, `Suspense`, `useCallback`/`useMemo` for INP
  168. **Vue/Nuxt:** Use `nuxt/image`, async components, `v-once`, computed properties
  169. **Svelte/SvelteKit:** Use `{#await}`, `svelte:image`, reactive statements
  170. **Astro:** Use `<Image>`, partial hydration, view transitions
  171. **Static HTML:** Use native lazy loading, `<picture>`, preconnect hints
  172. ## Contributing
  173. Contributions welcome! Please follow the [Agent Skills specification](https://agentskills.io/specification).
  174. 1. Fork the repository
  175. 2. Create your skill in `skills/{skill-name}/SKILL.md`
  176. 3. Keep SKILL.md under 500 lines (use `references/` for details)
  177. 4. Include practical examples and patterns
  178. 5. Submit a pull request
  179. ## Resources
  180. - [Google Lighthouse Documentation](https://developer.chrome.com/docs/lighthouse/)
  181. - [Lighthouse audits with AI agents](https://developer.chrome.com/docs/devtools/agents/use-cases/lighthouse-audit)
  182. - [Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp)
  183. - [Chrome UX Report](https://developer.chrome.com/docs/crux/)
  184. - [web.dev Learn Performance](https://web.dev/learn/performance/)
  185. - [Core Web Vitals](https://web.dev/articles/vitals)
  186. - [WCAG 2.2 Guidelines](https://www.w3.org/WAI/WCAG22/quickref/)
  187. - [Agent Skills Specification](https://agentskills.io/specification)
  188. ## License
  189. MIT License - see [LICENSE](LICENSE) for details.
  190. ---
  191. Built with insights from the Chrome DevTools team, web performance experts, and accessibility advocates to help developers create high-quality web experiences.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.