# addyosmani/web-quality-skills architecture

> Architecture diagram of the GitHub repository addyosmani/web-quality-skills, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/addyosmani/web-quality-skills
- Repository: https://github.com/addyosmani/web-quality-skills

## Overview

##### 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”

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Diagram 1 — System Context / Usage Flow
  %% =========================
  subgraph "Diagram 1 — System Context / Usage Flow"
    direction TB

    subgraph "Actors"
      direction TB
      User(["Developer / User"]):::actor
    end

    subgraph "Distribution / Packaging"
      direction TB
      Repo[("Skill Repository\n(content-as-code)")]:::repo
      MetaDocs["Repo Docs & Guidance\n(README / LICENSE / AGENTS / CLAUDE)"]:::docs
      Installer{{"Installer CLI\nnpx add-skill / npx skills"}}:::tool
      LocalStore[("Local Skill Store\n~/.claude/skills/")]:::store
    end

    subgraph "Agent Runtime"
      direction TB
      Agent(["Agent Host\n(Claude Code / Cursor / Codex)"]):::runtime
      Loaded["Loaded Skills\n(Markdown SKILL.md interpreted by agent)"]:::runtime
      Output["Audit Output\n(report / recommendations / PR guidance)"]:::artifact
      Lighthouse["Lighthouse Run\n(optional tooling)"]:::tool
      Script["analyze.sh\n(optional automation hook)"]:::tool
    end

    subgraph "Audited System"
      direction TB
      Target["Target Web Project\n(Next.js / React / Vue / static HTML / etc.)"]:::target
    end

    %% Installation paths
    Repo -->|"install via CLI"| Installer
    Installer -->|"install skills"| LocalStore
    Repo -->|"manual copy\ncp -r skills/*"| LocalStore
    LocalStore -->|"load skills"| Agent
    Agent -->|"register / interpret"| Loaded

    %% Usage flow
    User -->|"prompt: audit my site"| Agent
    Agent -->|"audit / recommend fixes"| Target
    Agent -->|"deliver findings"| Output
    Output -->|"review / apply changes"| User

    %% Optional tooling
    Agent -.->|"optionally run"| Lighthouse
    Agent -.->|"optionally invoke"| Script

    %% Repo guidance (maintainer view)
    MetaDocs -.->|"usage / contribution guidance"| User
    MetaDocs -.->|"setup / conventions"| Agent
  end

  %% =========================
  %% Diagram 2 — Internal Skill Composition (Repo Component Model)
  %% =========================
  subgraph "Diagram 2 — Internal Skill Composition (Repo Component Model)"
    direction TB

    subgraph "Skill Modules (Primary Artifacts)"
      direction TB
      WQA["web-quality-audit\n(orchestrator SKILL.md)"]:::skillOrch
      Perf["performance\n(SKILL.md)"]:::skill
      CWV["core-web-vitals\n(SKILL.md)"]:::skill
      A11y["accessibility\n(SKILL.md)"]:::skill
      SEO["seo\n(SKILL.md)"]:::skill
      BP["best-practices\n(SKILL.md)"]:::skill
    end

    subgraph "Supporting Artifacts (Non-executable)"
      direction TB
      RefDir["Reference Docs\n(skills/**/references/)"]:::ref
      WCAG["WCAG.md\n(WCAG 2.1 notes)"]:::ref
      LCP["LCP.md\n(LCP guidance)"]:::ref
    end

    subgraph "External Standards / Sources (Knowledge Influence)"
      direction TB
      LHStd["Google Lighthouse guidance"]:::standard
      CWVStd["Core Web Vitals thresholds"]:::standard
      WCAGStd["WCAG 2.1 standard"]:::standard
      SEOStd["Modern SEO requirements"]:::standard
    end

    subgraph "Optional Automation"
      direction TB
      Analyze["analyze.sh"]:::tool
    end

    %% Orchestrator fan-out
    WQA -->|"orchestrate"| Perf
    WQA -->|"orchestrate"| CWV
    WQA -->|"orchestrate"| A11y
    WQA -->|"orchestrate"| SEO
    WQA -->|"orchestrate"| BP

    %% References
    RefDir -->|"contains"| WCAG
    RefDir -->|"contains"| LCP
    A11y -->|"consults"| WCAG
    CWV -->|"consults"| LCP

    %% Optional script hook
    WQA -.->|"optionally run"| Analyze

    %% Knowledge influence (dotted)
    LHStd -.->|"informs"| WQA
    LHStd -.->|"informs"| Perf
    LHStd -.->|"informs"| BP

    CWVStd -.->|"informs"| CWV
    WCAGStd -.->|"informs"| A11y
    SEOStd -.->|"informs"| SEO
  end

  %% =========================
  %% Cross-diagram linkage (conceptual)
  %% =========================
  Loaded -->|"includes"| WQA

  %% =========================
  %% Click Events (from component_mapping)
  %% =========================
  click Repo "https://github.com/addyosmani/web-quality-skills/tree/main/./"
  click MetaDocs "https://github.com/addyosmani/web-quality-skills/blob/main/README.md"
  click LocalStore "https://github.com/addyosmani/web-quality-skills/tree/main/skills/"
  click A11y "https://github.com/addyosmani/web-quality-skills/blob/main/skills/accessibility/SKILL.md"
  click BP "https://github.com/addyosmani/web-quality-skills/blob/main/skills/best-practices/SKILL.md"
  click CWV "https://github.com/addyosmani/web-quality-skills/blob/main/skills/core-web-vitals/SKILL.md"
  click Perf "https://github.com/addyosmani/web-quality-skills/blob/main/skills/performance/SKILL.md"
  click SEO "https://github.com/addyosmani/web-quality-skills/blob/main/skills/seo/SKILL.md"
  click WQA "https://github.com/addyosmani/web-quality-skills/blob/main/skills/web-quality-audit/SKILL.md"
  click RefDir "https://github.com/addyosmani/web-quality-skills/tree/main/skills/**/references/"
  click WCAG "https://github.com/addyosmani/web-quality-skills/blob/main/skills/accessibility/references/WCAG.md"
  click LCP "https://github.com/addyosmani/web-quality-skills/blob/main/skills/core-web-vitals/references/LCP.md"
  click Analyze "https://github.com/addyosmani/web-quality-skills/blob/main/skills/web-quality-audit/scripts/analyze.sh"
  click MetaDocs "https://github.com/addyosmani/web-quality-skills/blob/main/README.md"
  click MetaDocs "https://github.com/addyosmani/web-quality-skills/tree/main/LICENSE"
  click MetaDocs "https://github.com/addyosmani/web-quality-skills/blob/main/AGENTS.md"
  click MetaDocs "https://github.com/addyosmani/web-quality-skills/blob/main/CLAUDE.md"

  %% =========================
  %% Styles
  %% =========================
  classDef actor fill:#E8F0FE,stroke:#1A73E8,stroke-width:2px,color:#0B1F3B;
  classDef runtime fill:#E6F4EA,stroke:#137333,stroke-width:2px,color:#0D2A14;
  classDef repo fill:#FFF4E5,stroke:#EA8600,stroke-width:2px,color:#3A2200;
  classDef docs fill:#FFF4E5,stroke:#EA8600,stroke-width:1.5px,color:#3A2200;
  classDef tool fill:#F3E8FF,stroke:#7E22CE,stroke-width:2px,color:#2A0A4A;
  classDef store fill:#E0F2FE,stroke:#0284C7,stroke-width:2px,color:#04283A;
  classDef target fill:#FCE7F3,stroke:#BE185D,stroke-width:2px,color:#3B0A1E;
  classDef artifact fill:#F1F5F9,stroke:#334155,stroke-width:2px,color:#0F172A;

  classDef skillOrch fill:#FFEDD5,stroke:#C2410C,stroke-width:2.5px,color:#3B1607;
  classDef skill fill:#FFE4E6,stroke:#9F1239,stroke-width:2px,color:#3A0713;

  classDef ref fill:#F8FAFC,stroke:#64748B,stroke-width:1.5px,stroke-dasharray:4 3,color:#0F172A;
  classDef standard fill:#F8FAFC,stroke:#475569,stroke-width:1.5px,stroke-dasharray:4 3,color:#0F172A;
```
