best-practices
Apply modern web development best practices for security, compatibility, and code quality. Use when asked to "apply best practices", "securi
Open source Repository Open in the app JSON README (API)
About
Apply modern web development best practices for security, compatibility, and code quality. Use when asked to "apply best practices", "security audit", "modernize code", "code quality review", or "check for vulnerabilities".
Details
- Kind
- Agent skills
- Topic
- Developer tools
- Publisher
- addyosmani
- Origin
- skillssh
- Category
- ferramentas
- Stars
- 2,783
- Forks
- 247
- Open pull requests
- 1
- Last push
- 2026-08-24T21:07:36Z
- Repository state
- ativo
- Language
- Shell
- License
- MIT
- Added
- 2026-08-30 15:21:09
- Updated
- 2026-09-09 18:03:12
- Origin id
addyosmani/web-quality-skills/best-practices
README
# 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 `<Image>`, partial hydration, view transitions
**Static HTML:** Use native lazy loading, `<picture>`, 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.