Setting the issue. One moment.
Contents
Issue No. 84Addy Osmani
addyosmani /web-quality-skills
Agent Skills for optimizing web quality based on Lighthouse and Core Web Vitals.
6 chapters · 17 minutes · 3,766 words
Install and provenance
npx skills add addyosmani/web-quality-skills/plugin marketplace add addyosmani/web-quality-skills- Owner
- addyosmani · User
- Licence
- MIT
- Last updated
- Published from
- github.com/
addyosmani/ web-quality-skills
| Week | Installs |
|---|---|
| Week 1 | 3,779 |
| Week 2 | 3,310 |
| Week 3 | 3,309 |
| Week 4 | 3,233 |
| Week 5 | 3,162 |
| Week 6 | 3,089 |
| Week 7 | 3,561 |
| Week 8 | 3,462 |
Front matter
From the READMEAn (unofficial) comprehensive collection of Agent Skills (opens in a new tab) for optimizing web projects based on Google Lighthouse (opens in a new tab) guidelines and Core Web Vitals best practices.
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 encode the collective wisdom from:
- 150+ Lighthouse audits across Performance, Accessibility, SEO, and Best Practices
- Core Web Vitals optimization patterns (LCP, INP, CLS)
- Real-world performance engineering experience
- WCAG 2.2 accessibility standards
- Modern SEO requirements
Available skills
| Skill | Description | Use when |
|---|---|---|
| web-quality-audit | Comprehensive quality review across all categories | “Audit my site”, “Review this for quality”, “Check web quality” |
| performance | Loading speed, runtime efficiency, resource optimization | “Optimize performance”, “Speed up my site”, “Fix slow loading” |
| core-web-vitals | LCP, INP, CLS specific optimizations | “Improve Core Web Vitals”, “Fix LCP”, “Reduce CLS” |
| accessibility | WCAG compliance, screen reader support, keyboard navigation | “Improve accessibility”, “WCAG audit”, “a11y review” |
| seo | Search engine optimization, crawlability, structured data | “Optimize for SEO”, “Improve search ranking”, “Fix meta tags” |
| best-practices | Security, modern APIs, code quality patterns | “Apply best practices”, “Security audit”, “Code quality review” |
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.
npx skills add addyosmani/web-quality-skillsor
npx add-skill addyosmani/web-quality-skillsOr 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-skillsSkills 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-skillsOnce installed, invoke skills in chat using @ (e.g. @performance, @accessibility). See docs/codex-setup.md (opens in a new tab) for local installation and troubleshooting.
Gemini CLI
Install directly via Gemini CLI extensions:
gemini extensions install https://github.com/addyosmani/web-quality-skillsSkills are auto-discovered by Gemini and activate when prompts match their description. See docs/gemini-setup.md (opens in a new tab) 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 issuesOptimize performance and fix Core Web VitalsReview accessibility and suggest improvementsMake this SEO-readySkill details
web-quality-audit
The comprehensive skill that orchestrates all other skills. Use this for full-site audits or when you’re unsure which specific area needs attention.
Trigger phrases: “audit my site”, “quality review”, “lighthouse audit”, “check web quality”
What it checks:
- All Core Web Vitals metrics
- 50+ performance patterns
- 40+ accessibility rules
- 30+ SEO requirements
- 20+ security/best practice patterns
performance
Deep-dive into loading and runtime performance optimization.
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 affect Google Search ranking.
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 |
Performance budget recommendations
| 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 |
Lighthouse score targets
| Category | Target score |
|---|---|
| Performance | ≥ 90 |
| Accessibility | 100 |
| 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 <Image>, partial hydration, view transitions
Static HTML: Use native lazy loading, <picture>, preconnect hints
Contributing
Contributions welcome! Please follow the Agent Skills specification (opens in a new tab).
- Fork the repository
- Create your skill in
skills/{skill-name}/SKILL.md - Keep SKILL.md under 500 lines (use
references/for details) - Include practical examples and patterns
- Submit a pull request
Resources
- Google Lighthouse Documentation (opens in a new tab)
- web.dev Learn Performance (opens in a new tab)
- Core Web Vitals (opens in a new tab)
- WCAG 2.2 Guidelines (opens in a new tab)
- Agent Skills Specification (opens in a new tab)
License
MIT License - see LICENSE (opens in a new tab) for details.
Built with insights from the Chrome DevTools team, web performance experts, and accessibility advocates to help developers create high-quality web experiences.
Colophon
How this issue was made- Source
- github.com/addyosmani/web-quality-skills, branch
main, last pushed 14 June 2026. - Licence
- MIT — the text of every chapter is reproduced unmodified, frontmatter included, under the upstream licence.
- Discovery
- 6 chapters found by walking the repository tree for
SKILL.md, not by matching a directory convention. One layout observed:skills/*/SKILL.md. - Issue colours
- Resolved from a deterministic hash of the owner name. Two accent tones are generated per issue and each is proven against its own ground before it ships: a single accent that passes AA on both light and dark paper is arithmetically impossible.
- Heading repairs
- 1 repair applied to the front matter so the document has one
h1and no skipped levels:- Removed “Web Quality Skills”, a leading h1 that duplicated the chapter title.
- Spec compliance
- Every chapter satisfies the Agent Skills specification’s frontmatter rules.
- Images
- Images inside a chapter come from the upstream repository. Where the author gave no alternative text we mark the image decorative rather than inventing a description — a plausible caption we made up is worse than none for the reader who depends on it.
- Marketplace
- A plugin manifest is published at
.claude-plugin/marketplace.jsonby Addy Osmani, declaring 1 plugin. It is read for editorial metadata only — never as the skill index, which is always the repository tree. - Signal
- Install counts come from skills.sh. They measure downloads, not quality, and an unranked repository is not an unread one.
- Agent surfaces
- The whole issue is available as one markdown document at
/addyosmani/web-quality-skills.md, and each chapter at its own.mdURL. - Publication
- Set by Skills Docs from the source repository. Body text is Literata at the reader’s chosen size and measure; code is Geist Mono. Nothing on this page was written by us except this paragraph.