Source: addyosmani/web-quality-skills · Maintainer: community: Addy Osmani · License: MIT · Checked: 24 October 2026
What is the web quality audit skill?
The web quality audit skill has a coding agent review a website across five areas, Performance, Accessibility, SEO, Best Practices and Agentic Browsing, using live browser evidence first and source code second. It returns a prioritized list of issues with the evidence behind each one. It works with Claude Code, Codex, Cursor and other agents that read the SKILL.md format.
It is the umbrella skill in addyosmani/web-quality-skills, a six-skill collection that Addy Osmani describes as "(unofficial)" and "measurement-first." The README calls it "The comprehensive skill that orchestrates all other skills."
The skill's description reads: "Run an evidence-led web quality audit covering performance, accessibility, SEO, best practices, and agentic browsing. Use when asked to "audit my site", "review web quality", "run lighthouse audit", "check page quality", or "optimize my website"."
As of 24 October 2026, its skills.sh page listed 32.5K installs (snapshot, 24 October 2026).
What does it do?
The SKILL.md runs five steps:
- Set the audit target: representative URLs, key states and journeys, public or signed-in access, and mobile or desktop scope.
- If a page can run, read the performance skill's measurement guide and collect a small live baseline before searching the codebase.
- Use runtime failures to decide which source files to inspect, and keep measured findings apart from code-only hypotheses.
- Sort issues by user impact and confidence, then fix or recommend specific changes.
- Re-run the same checks and affected manual flows, and say what is verified and what still needs field or human validation.
Tool routing. The skill picks the best tool already available instead of blocking on setup:
| Need | Preferred route | Fallback |
|---|---|---|
| Performance and Core Web Vitals | Browser trace, with performance_start_trace and performance_analyze_insight in Chrome DevTools MCP |
Lighthouse CLI or PageSpeed Insights lab data |
| Real-user performance | CrUX values in DevTools trace summaries | PageSpeed Insights or CrUX Vis |
| Accessibility, SEO, Best Practices, Agentic Browsing | lighthouse_audit in Chrome DevTools MCP |
Lighthouse CLI plus manual checks |
| Rendered semantics | Accessibility tree snapshot and UI testing | Manual browser testing |
| Source smoke test | scripts/analyze.sh <path> |
Direct source inspection |
Checklists by category. Performance covers the three Core Web Vitals thresholds (LCP under 2.5 s, INP under 200 ms, CLS under 0.1) plus images, JavaScript, CSS, fonts and caching. Accessibility follows the four WCAG principles, such as 4.5:1 text contrast, visible focus and labelled inputs. SEO covers robots.txt, sitemaps, canonicals, titles and structured data. Best Practices covers HTTPS, CSP, vulnerable libraries, exposed source maps and deprecated APIs.
Agentic Browsing. This newer category checks whether the rendered page gives assistants a usable accessibility tree, whether any WebMCP tools are valid, and whether an llms.txt file is valid. The skill says llms.txt "is optional" and tells the agent to "Keep this category separate from SEO claims."
Output. Findings come back in a fixed shape: an evidence table (signal, scope, result, source), issues grouped as Critical, High, Medium or Low with file, impact, evidence and fix, a summary per category, a fix order and a verification list.
The script. scripts/analyze.sh is a read-only HTML scanner. It flags a missing doctype, UTF-8 charset, viewport tag, lang attribute or <title>, images without alt, and http:// URLs, and prints JSON capped at 100 findings. It needs jq.
How do you install it?
All six skills, recommended. The skill links to the other five and to ../performance/references/MEASUREMENT.md, so it works best with the whole set. The skills CLI takes --skill '*' for every skill in a repo:
npx skills add addyosmani/web-quality-skills --skill '*' -a claude-code
Just this skill. The skills.sh command:
npx skills add https://github.com/addyosmani/web-quality-skills --skill web-quality-audit
Add -g for all projects. In Claude Code the folders land in .claude/skills/, or ~/.claude/skills/ with -g, the standard Claude Code skill locations.
Claude Code plugin. From the README:
/plugin marketplace add addyosmani/web-quality-skills
/plugin install web-quality-skills@addy-web-quality-skills
It then appears as /web-quality-skills:web-quality-audit.
Codex and Gemini CLI. The README gives codex plugin marketplace add addyosmani/web-quality-skills for Codex CLI v0.122 or later and gemini extensions install https://github.com/addyosmani/web-quality-skills. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills.
Recommended: Chrome DevTools MCP. The Chrome DevTools MCP client guide gives this Claude Code command:
claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest
How do you use it?
Point it at a page it can load and tell it what matters most.
Example prompts (suggestions, not quotes from the repo):
Audit http://localhost:3000 for web quality on mobile. Give me the evidence table and a fix order.Run a lighthouse audit on the signup flow without reloading the page, since I'm already signed in.We launch Friday. Review the marketing site and list only Critical and High issues.Run analyze.sh on ./dist and then check the rendered pages for anything it can't see.
Requirements: a runnable page for measured results, Chrome DevTools MCP or the Lighthouse CLI, and jq for the script. With source only, expect hypotheses rather than measured failures.
Tips and limits
- Scores are not proof. The README says scores "do not prove accessibility, security, SEO ranking, or user experience." The skill reports metric values and manual checks alongside them.
- Lighthouse audits can reload the page. The skill notes that navigation mode reloads, and says to use snapshot mode when you need to keep a signed-in or user-created state.
- Performance is separate. Chrome DevTools MCP's
lighthouse_audit"intentionally excludes performance," so the skill uses a trace for that category. - The script is shallow. It uses grep on raw HTML, so it can't see client-rendered markup. The skill calls it "a fast smoke test."
- Lighthouse 13 changes. The skill tells the agent to follow current Performance Insights names and not to require removed audit IDs.
- Security audit. On 24 October 2026 its skills.sh page showed Gen Agent Trust Hub: Pass, Socket: Pass, Snyk: Pass.
The skill is MIT licensed, so you can copy and adapt it if you keep the copyright notice.
Save it in your Kipt library
In Kipt, open Skills and paste the repo link into the import box. Because the repo holds six skills, Kipt shows a list to pick from, so you can take web-quality-audit with the five skills it calls. Kipt reads each SKILL.md and its files, including scripts/analyze.sh. Your skills live in your own private GitHub repo and install into Claude Code or Codex with one command:
npx skills add https://github.com/<you>/<repo>.git --all -g
Kipt is not affiliated with Addy Osmani or addyosmani/web-quality-skills.
Similar skills
- Performance skill: the repo's deep dive on loading and runtime speed.
- Core Web Vitals skill: focused LCP, INP and CLS work.
- Accessibility skill: the full WCAG 2.2 audit behind this skill's accessibility checks.
- SEO skill: crawlability, metadata and structured data in depth.
- Web best practices skill: security headers and modern standards from the same repo.