addyosmani/web-quality-skills: Lighthouse and Core Web Vitals as Agent Skills
Agent Skills for optimizing web quality based on Lighthouse and Core Web Vitals.
At a glance
- What is it?
- A measurement-first set of Agent Skills that give coding agents Lighthouse audits, CrUX field data and WCAG 2.2 checks. Useful if your agent already edits front-end code and you want it to measure before it rewrites.
- Who is it for?
- Adopt it if your team already runs a coding agent against a front-end repository and you want audits, Core Web Vitals diagnosis and accessibility checks to come from the same instructions the agent follows while editing. Skip it if you need a CI regression gate or a hosted dashboard; this repository ships skill definitions, not a service, and its measurement model depends on Chrome DevTools MCP or Lighthouse CLI being reachable.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 30 days ago.
- What is it written in?
- Mainly Shell, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 20, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap web-quality-skills fills between interface guidelines and measured audits
Most agent skill collections tell a model how to structure a component: naming, file layout, prop conventions. They rarely tell it what to measure afterwards. This repository, described in its README as an unofficial collection, targets that second half of the job. The stated purpose is to tell an agent how to build performantly, accessibly and optimally for search engines, rather than what to build.
The intended user is someone whose coding agent already touches front-end code and who wants the same agent to run Lighthouse, read a performance trace or check a page against WCAG 2.2. The README claims stack agnosticism, listing React, Vue, Angular, Svelte, Next.js, Nuxt, Astro and plain HTML, which matters because the skills are instruction files rather than framework plugins. Nothing in the repository is bound to a build tool.
One design decision stands out. The README separates web-quality-audit, the orchestrating skill, from five narrower skills: performance, core-web-vitals, accessibility, seo and best-practices. Each narrower skill lists trigger phrases such as "speed up" or "WCAG audit" that map a user request to the right instruction set. That is a deliberate choice to avoid one enormous prompt, and it also means the quality of the result depends on the agent matching your phrasing to the right skill.
Four evidence types and why the skills refuse to blend them
The measurement model is the most opinionated part of the project. Four evidence types are kept explicit: CrUX field data, first-party RUM, a DevTools trace or Lighthouse lab run, and static source inspection. The README assigns each a question. CrUX answers how eligible real Chrome users experienced the URL or origin over the recent aggregation window. RUM answers how the site's own users experienced routes, releases, devices and interactions. A trace or lab run answers what happened in one controlled browser session. Static inspection answers what might be a problem when the page cannot run at all.
Field data determines user impact; lab traces reproduce and diagnose it. The README is explicit that a PerformanceObserver snippet run in one browser counts as a lab observation, not real-user data. That distinction is the reason to prefer this collection over a generic performance prompt: an agent that treats a single local trace as proof of a user-facing regression will send you chasing noise.
The orchestration reflects the same discipline. web-quality-audit starts with live evidence when a page is runnable and keeps measured failures separate from source-code hypotheses. In practice that means the agent should report a failing LCP with a trace behind it differently from a suspected render-blocking script it found by reading the source.
Installing the skills into Claude Code, Codex or Gemini CLI
The README gives several installation paths. The shortest uses the add-skill CLI, which the README describes as a tool for installing agent skills onto coding agents from git repositories. Run this from a shell and the skills are copied into your agent's skill directory:
npx skills add addyosmani/web-quality-skillsThe README also lists an alternative invocation with a hyphenated package name:
npx add-skill addyosmani/web-quality-skillsIf you would rather not use a CLI, the manual route copies the skills directory into Claude Code's skills folder:
cp -r skills/* ~/.claude/skills/Inside Claude Code, the repository can be installed as a versioned plugin from its own marketplace. This namespaces the skills, so a performance request becomes a slash command rather than a plain prompt:
/plugin marketplace add addyosmani/web-quality-skills
/plugin install web-quality-skills@addy-web-quality-skillsThe README notes that the plugin reads the same skills directory as the manual copy, so the two routes do not duplicate content, and that updates arrive through /plugin update. Codex users install through the Codex plugin marketplace and then invoke skills with an @ prefix such as @performance or @accessibility. Gemini CLI users run an extensions install against the repository URL, after which the README says skills are auto-discovered and activate when prompts match their description. For claude.ai there is no installer: add the skills to project knowledge or paste the SKILL.md contents into the conversation.
A first real use is a prompt, not a command. The README's examples include "Audit this page for web quality issues" and "Optimize performance and fix Core Web Vitals". What you should see is the agent selecting the matching skill and, if a browser tool is available, running an audit before proposing edits.
Chrome DevTools MCP: the optional dependency that changes the answer
Live auditing depends on the agent having browser capabilities. With Chrome DevTools MCP, the README names the tools the skills prefer: 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; and rendered accessibility snapshots, console messages and network requests for issue-level diagnosis.
The integration is optional, and this is where expectations need calibrating. Without it the skills fall back to Lighthouse CLI, PageSpeed Insights and CrUX tools, manual browser checks and static inspection rather than stopping the task. That fallback is sensible, but the output is weaker: an agent inspecting source can tell you an image lacks explicit dimensions; it cannot tell you the element shifted during load. If your agent has no browser tool and no Lighthouse CLI available, you are reading the static-inspection column of the measurement table and should treat the findings as hypotheses.
The README also mentions Agentic Browsing signals in the audit skill, including agent-facing semantics and optional WebMCP or llms.txt checks. That is an unusual inclusion for a web quality collection and reflects how the audit scope has widened beyond the classic Lighthouse categories.
What the repository does not give you
There is no CI integration, no score threshold, no regression gate and no hosted report. The repository is a set of skill definitions plus setup documentation; the top-level entries are .agents/, .claude-plugin/, .gemini/, codex/, docs/, skills/ and a gemini-extension.json, alongside AGENTS.md, CLAUDE.md, CHANGELOG.md, LICENSE and README.md. Nothing in that layout runs on a schedule or fails a build.
That matters for teams who want to stop performance regressions. An agent-invoked audit is a conversation, and conversations are not gates. If your requirement is that every pull request must not raise LCP above a budget, this project does not provide that mechanism, and the README does not document one.
The second limitation is variability. Because activation depends on the agent matching your prompt to a skill description, two engineers phrasing the same request differently can get different scopes of work. The trigger phrase lists reduce that risk but do not remove it. The third is that the skills are instructions, so their output quality inherits whatever model is executing them; the repository cannot enforce that the agent actually ran the trace it claims to have run. Verify claims against the tool output rather than the summary.
One more boundary: there are no releases retrieved for this repository, so versioning is through the git history and, for Claude Code users, the plugin update path. Pin a commit if reproducibility matters to you.
How this differs from a CI performance tool such as Lighthouse CI
The closest conventional alternative is Lighthouse CI, which runs audits in a pipeline and asserts budgets on the results. The difference is architectural rather than feature-level. Lighthouse CI is a runner: you configure URLs, it executes audits on every build and fails when a threshold is crossed. web-quality-skills is an instruction layer: it shapes what your coding agent does during a session, including reading source, proposing edits and re-measuring.
That means the two are complementary rather than substitutes. If you want a regression gate, Lighthouse CI answers a question this repository does not attempt. If you want the agent that is already rewriting your component to understand the difference between CrUX field data and a single lab trace before it changes image loading, this repository addresses something a CI threshold cannot: the reasoning that happens before the edit.
The README's own framing supports that reading. It positions the skills against interface guidelines, not against audit runners, and the measurement model is written for an agent deciding what evidence to trust mid-task. Choose based on where your problem sits: enforcement after the fact, or judgement during the change.
Licence, maintenance and the cost of keeping skills current
The repository is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is the most permissive common option and imposes no copyleft obligation on your own code. This is a description of the licence text, not legal advice; check the LICENSE file for the exact terms before relying on it.
The repository is not archived, and the last push was on 2026-08-24. Upgrade cost depends on your installation route. Claude Code plugin users get updates through /plugin update and the skills are namespaced, so an upstream change does not collide with your own skills. Manual copiers under ~/.claude/skills/ have no update path at all and will silently drift from upstream; if you chose that route, re-copy periodically or switch to the plugin.
The maintenance burden that does not disappear is tool-name drift. The README names Chrome DevTools MCP tools such as performance_start_trace and lighthouse_audit as the current names, which implies they can change. When a browser tool is renamed, the skills' instructions point at a tool that no longer exists and the agent falls back or fails. Budget a review of the skills directory whenever you upgrade your agent or its MCP server, and check CHANGELOG.md for what changed between the commit you pinned and the one you are moving to.
Editorial conclusion
Adopt it if your team already runs a coding agent against a front-end repository and you want audits, Core Web Vitals diagnosis and accessibility checks to come from the same instructions the agent follows while editing. Skip it if you need a CI regression gate or a hosted dashboard; this repository ships skill definitions, not a service, and its measurement model depends on Chrome DevTools MCP or Lighthouse CLI being reachable. Before rolling it out, read skills/web-quality-audit/SKILL.md and confirm which commands your agent can actually execute, then run one audit prompt on a staging URL and check whether the agent reports CrUX field data or only a lab trace.
Frequently asked questions
What are addyosmani/web-quality-skills?
They are an unofficial collection of Agent Skills for optimizing web projects with Google Lighthouse, Chrome DevTools, Core Web Vitals, WCAG and search guidance. The README describes them as stack-agnostic and says they work with any framework, from React and Vue to plain HTML.
How do I install web-quality-skills?
The README gives several routes: npx skills add addyosmani/web-quality-skills, a manual copy of skills/* into ~/.claude/skills/, a Claude Code plugin marketplace install, a Codex plugin marketplace install, and a Gemini CLI extensions install. For claude.ai there is no installer and you add the skills to project knowledge instead.
Does web-quality-skills require Chrome DevTools MCP?
No. The README states the integration is optional, and without it the skills fall back to Lighthouse CLI, PageSpeed Insights and CrUX tools, manual browser checks and static inspection rather than stopping the task. With Chrome DevTools MCP, the skills prefer live tools such as performance_start_trace and lighthouse_audit.
Which skills are included in web-quality-skills?
The README lists web-quality-audit, performance, core-web-vitals, accessibility, seo and best-practices. The audit skill orchestrates the others, and each narrower skill documents trigger phrases that map a request to it.
Is web-quality-skills a CI regression gate?
No. The repository ships skill definitions and setup docs, with no CI integration, score threshold or hosted report described in the README. Its measurement model is written for an agent deciding what evidence to trust during a session, not for failing a build.
Community notes