CWV Superpowers

Core Web Vitals diagnosis and fixing skills for AI coding agents — powered by CoreDash real user monitoring.

What it does: Connects your real user data (LCP, INP, CLS) to your AI coding agent. The agent finds the worst-performing pages, identifies the exact element and bottleneck phase causing the issue, traces the root cause in Chrome, and either fixes the code or generates a detailed HTML report — all from a single conversation.

What You Get

| Capability | What it does | |---|---| | Automated discovery | Finds your worst pages and metrics across millions of real page loads | | Phase breakdown | Splits LCP into TTFB / Load Delay / Load Time / Render Delay — names the bottleneck | | INP attribution | Identifies the slow interaction element, the responsible script (LOAF), and the load state | | CLS cause matching | Detects images without dimensions, font swaps, injected content, late-loading resources | | Chrome tracing | Visits the page with mobile emulation and traces the exact bottleneck identified by RUM | | Code fixes | Makes the minimal code change — names the file, the line, the element | | HTML reports | Generates interactive reports with filmstrip, waterfall, breakdown charts, root cause analysis |

Requirements

CoreDash account with real user data flowing (free tier works)
A way to authenticate — either a browser login (OAuth, no key needed in Claude Code) or a CoreDash API key (generated in Project Settings → API Keys, for headless/CI/multi-project use)
Claude Code — npm install -g @anthropic-ai/claude-code
Chrome (optional but recommended) — run Claude Code with claude --chrome for full tracing

Installation

Claude Code

# Add the marketplace
/plugin marketplace add corewebvitals/cwv-superpowers

# Install the plugin
/plugin install cwv-superpowers@cwv-superpowers

Then set up CoreDash MCP if you haven't already. Two ways to authenticate:

Browser login (OAuth) — recommended for interactive Claude Code, no API key:

claude mcp add --transport http coredash https://app.coredash.app/api/mcp

Then run /mcp, select coredash, and choose Authenticate — your browser opens the CoreDash login, you pick a project, and approve. Claude Code stores a short-lived token that auto-refreshes (1-hour access, 30-day refresh) and is revocable. (claude mcp list is only a health check and will show the server as failing until you authenticate via /mcp.)

API key — for headless/CI/automation or agency multi-project setups:

claude mcp add --transport http coredash https://app.coredash.app/api/mcp \
  --header "Authorization: Bearer cdk_YOUR_API_KEY"

Replace cdk_YOUR_API_KEY with your key from CoreDash → Project Settings → API Keys (MCP).

Restart Claude Code after installing so the SessionStart hook fires on a fresh conversation.

Cursor

The repo ships a Cursor plugin manifest at .cursor-plugin/plugin.json pointing at the same skill set. Install via Cursor's plugin UI from the GitHub repo URL.

Gemini CLI

The repo ships a Gemini extension at gemini-extension.json with GEMINI.md auto-loading the orchestrator skill. Install via:

gemini extensions install https://github.com/corewebvitals/cwv-superpowers

Other MCP-compatible clients

The CoreDash MCP server works with any client that supports HTTP MCP servers:

| Setting | Value | |---|---| | Endpoint | https://app.coredash.app/api/mcp | | Auth (interactive native/CLI clients) | Browser login (OAuth) — no key | | Auth (config-file / headless clients) | Header Authorization: Bearer cdk_YOUR_API_KEY |

Ask the agent to "set up CoreDash" — the setting-up-coredash skill walks through detailed per-client setup (Claude Desktop, Windsurf, Gemini CLI, etc.).

Verify installation

Ask your agent: "What are my Core Web Vitals?"

If CoreDash is connected, it will return your real LCP, INP, CLS, FCP, and TTFB data.

Permission prompts

The orchestrator skill is inlined into the session by a SessionStart hook, so the agent doesn't need to Read it (which would prompt). Peer skills are loaded internally via the Skill tool, also without a prompt. CoreDash MCP queries, Write/Edit/Bash (code fixes), and Chrome DevTools tools stay behind permission prompts by design — approve them once and they're remembered for the session.

Usage

Start Claude Code (with Chrome for full analysis):

claude --chrome

Then just ask:

"Find my biggest CWV issue and fix it" — automated discovery + diagnosis + fix
"My product pages are slow" — targeted diagnosis on a page section
"LCP on /product/shoes-42 is bad" — drill into a specific URL
"Generate a report" — get an interactive HTML report with all findings

The skill handles capability detection automatically. It works with:

| Chrome | CoreDash | What you get | |---|---|---| | Yes | Yes | Full analysis — RUM finds the issue, Chrome explains why, code fix + visual report | | No | Yes | RUM diagnosis — element, bottleneck phase, trend, code fix (no Chrome visuals) | | Yes | No | Lab-only audit — Chrome trace without real user context (setup guide offered) | | No | No | Setup wizard — guides you through installing both |

How It Works

┌─────────────────────────────────────────────────────────────┐
│  1. Discovery                                               │
│     CoreDash → worst pages, worst metrics, distributions    │
├─────────────────────────────────────────────────────────────┤
│  2. Diagnosis                                               │
│     LCP: TTFB / LOADDELAY / LOADTIME / RENDERDELAY         │
│     INP: INPUTDELAY / PROCESSING / PRESENTATION             │
│     CLS: 5 cause patterns (images, fonts, injected, ...)   │
├─────────────────────────────────────────────────────────────┤
│  3. Chrome Trace                                            │
│     Mobile emulation (Fast 3G, 4x CPU slowdown)            │
│     Investigates ONLY the bottleneck phase from step 2     │
├─────────────────────────────────────────────────────────────┤
│  4. Root Cause                                              │
│     Names the element, the cause, both evidence sources     │
├─────────────────────────────────────────────────────────────┤
│  5. Output                                                  │
│     Code fix  /  HTML report  /  Both                       │
└─────────────────────────────────────────────────────────────┘

Skill Structure

Six peer skills: one orchestrator + five specialist skills. The orchestrator runs the full multi-step flow; the specialists can also be invoked directly.

cwv-superpowers/                        ← Repo root (git repo)
├── .claude-plugin/marketplace.json     ← Claude Code marketplace listing
├── .cursor-plugin/plugin.json          ← Cursor manifest
├── gemini-extension.json               ← Gemini CLI extension manifest
├── GEMINI.md                           ← Gemini auto-loaded context
├── .version-bump.json                  ← Single source of truth for version
├── scripts/bump-version.sh             ← Keeps all 10 version fields in sync
└── plugins/cwv-superpowers/
    ├── .claude-plugin/plugin.json      ← Claude Code plugin metadata
    ├── hooks/
    │   ├── hooks.json                  ← SessionStart hook config
    │   ├── hooks-cursor.json           ← Cursor hook config
    │   └── session-start               ← Inlines orchestrator SKILL.md into context
    └── skills/
        ├── cwv-superpower/             ← Orchestrator (Step 0–5 flow)
        │   ├── SKILL.md
        │   └── templates/
        │       ├── report-rum.html     ← RUM-only report template
        │       └── report-full.html    ← Full report (filmstrip, waterfall)
        ├── diagnosing-lcp/SKILL.md     ← LCP diagnosis (phases + attribution)
        ├── diagnosing-inp/SKILL.md     ← INP diagnosis (phases + LOAF scripts)
        ├── diagnosing-cls/SKILL.md     ← CLS diagnosis (cause pattern matching)
        ├── tracing-with-chrome/SKILL.md ← Chrome tracing (per-phase investigation)
        └── setting-up-coredash/SKILL.md ← CoreDash MCP installation guide

When each skill activates:

cwv-superpower — "find my biggest CWV issue", "audit this site", multi-metric analysis.
diagnosing-lcp / diagnosing-inp / diagnosing-cls — the user names one specific metric.
tracing-with-chrome — the user has a URL + metric + suspected cause and wants a lab trace.
setting-up-coredash — connecting CoreDash MCP from scratch.

Example Output

Root cause statement:

Root cause: The LCP image div.hero-banner > img.product-main on /product/running-shoes-42 is discovered 1,980ms late because it lacks a preload hint and has no fetchpriority="high". Evidence from real users (CoreDash): LCP is 3,820ms (poor) on mobile, p75. LOADDELAY is the bottleneck at 1,980ms (52% of total LCP). The image priority state is 3 (not preloaded). LCP has worsened by 340ms over 7 days. Evidence from lab trace (Chrome): The network waterfall shows a 1,940ms gap between HTML first byte and the hero image request. The image is referenced only in CSS background-image, invisible to the preload scanner. No <link rel="preload"> exists in <head>.

Code fix:

<!-- Add to <head> -->
<link rel="preload" href="/images/hero.jpg" as="image" fetchpriority="high">

<!-- Change the img element -->
<img src="/images/hero.jpg" alt="Hero" fetchpriority="high">

Updating

/plugin marketplace update cwv-superpowers
/plugin install cwv-superpowers@cwv-superpowers

Restart Claude Code after updating.

Contributing

Issues and PRs welcome at github.com/corewebvitals/cwv-superpowers.

For maintainers

Versions across all 10 manifests (Claude Code, Cursor, Gemini CLI, plugin.json, and all 6 SKILL.md files) are kept in sync via one script:

./scripts/bump-version.sh --check      # show current versions + detect drift
./scripts/bump-version.sh --audit      # check + scan repo for stray version strings
./scripts/bump-version.sh 2.1.0        # bump every declared file to 2.1.0

The declared file list lives in .version-bump.json. To add a new version-bearing file, add its path + JSON field (or "format": "yaml-frontmatter" for SKILL.md frontmatter).

License

MIT

cwv-superpowers