How addyosmani/web-quality-skills works
Project type & purpose (what you’re diagramming)
This repo is not an executable web app. It’s a content/instruction pack: a curated set of Agent Skills (Markdown-based skill definitions) for performing web quality audits and optimizations aligned with Google Lighthouse, Core Web Vitals, WCAG 2.1, SEO, and best practices.
• how skills are installed (via npx add-skill / npx skills or manual copy),
• how they’re loaded by an agent environment (Claude Code / Cursor / etc.),
• how the “web-quality-audit” skill orchestrates other skills,
• how these skills apply to a target web project (the thing being audited), often via Lighthouse guidance and (optionally) scripts.
From the file tree, the core components are:
Skill packages (primary artifacts)
Located under:
• skills/accessibility/SKILL.md
• skills/best-practices/SKILL.md
• skills/core-web-vitals/SKILL.md
• skills/performance/SKILL.md
• skills/seo/SKILL.md
• skills/web-quality-audit/SKILL.md
These are the “modules” of the system.
References (supporting artifacts)
• skills/accessibility/references/WCAG.md
• skills/core-web-vitals/references/LCP.md
These are “knowledge dependencies” referenced by skills (don’t execute; they inform).
Helper script(s) (optional automation)
• skills/web-quality-audit/scripts/analyze.sh
Repo metadata / contributor guidance
• README.md, LICENSE, AGENTS.md, CLAUDE.md
Shows how the skill pack is used in the real world:
• User (developer) issues request like “Audit my site”
• Agent runtime (Claude Code/Cursor/etc.) loads installed skills
• Skills apply guidance to a Target Web Project (any framework)
• Optionally invokes tooling / scripts / Lighthouse runs (conceptual or explicit)
Shows the internal modularity:
• web-quality-audit as an orchestrator that routes to:
• performance
• core-web-vitals
• accessibility
• seo
• best-practices
• Each skill optionally depends on reference docs
• analyze.sh attaches to web-quality-audit as an optional execution path
This mirrors the README: “web-quality-audit orchestrates all other skills.”
Agent Host (e.g., Claude Code, Cursor, Codex)
• Loads “skills” from a local directory or project knowledge
Target Web Project (audited system)
• Any stack: Next.js, React, Vue, static HTML, etc.
Installer CLI
• npx add-skill ... or npx skills add ...
Local Skill Store
• e.g., ~/.claude/skills/ (explicitly mentioned)
Reference docs (WCAG, LCP notes, etc.)
• Lighthouse guidance
• Core Web Vitals thresholds
• WCAG 2.1
• Modern SEO requirements
Orchestrator pattern
• web-quality-audit coordinates specialized sub-skills.
Plugin/module library
• Skills are independent modules with clear scopes.
Content-as-code
• Primary “execution” is agent interpretation of Markdown skill specs.
Stack-agnostic targeting
• The “Target Web Project” is an external system; skills adapt guidance per framework.
Distribution/Packaging
• Repo, installer CLI, local skill directory
Agent Runtime
• Agent host + loaded skills
Audited System
• Target web app/project + outputs (issues, recommendations)
Examples:
• “install”
• “load skills”
• “match trigger phrase”
• “orchestrate”
• “audit / recommend fixes”
• “optionally run script”