{
  "markdown": "# CWV Superpowers\n\nCore Web Vitals diagnosis and fixing skills for AI coding agents — powered by [CoreDash](https://coredash.app) real user monitoring.\n\n**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.\n\n## What You Get\n\n| Capability | What it does |\n|---|---|\n| **Automated discovery** | Finds your worst pages and metrics across millions of real page loads |\n| **Phase breakdown** | Splits LCP into TTFB / Load Delay / Load Time / Render Delay — names the bottleneck |\n| **INP attribution** | Identifies the slow interaction element, the responsible script (LOAF), and the load state |\n| **CLS cause matching** | Detects images without dimensions, font swaps, injected content, late-loading resources |\n| **Chrome tracing** | Visits the page with mobile emulation and traces the exact bottleneck identified by RUM |\n| **Code fixes** | Makes the minimal code change — names the file, the line, the element |\n| **HTML reports** | Generates interactive reports with filmstrip, waterfall, breakdown charts, root cause analysis |\n\n## Requirements\n\n- **[CoreDash](https://coredash.app) account** with real user data flowing (free tier works)\n- **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)\n- **Claude Code** — `npm install -g @anthropic-ai/claude-code`\n- **Chrome** (optional but recommended) — run Claude Code with `claude --chrome` for full tracing\n\n## Installation\n\n### Claude Code\n\n```bash\n# Add the marketplace\n/plugin marketplace add corewebvitals/cwv-superpowers\n\n# Install the plugin\n/plugin install cwv-superpowers@cwv-superpowers\n```\n\nThen set up CoreDash MCP if you haven't already. Two ways to authenticate:\n\n**Browser login (OAuth) — recommended for interactive Claude Code, no API key:**\n\n```bash\nclaude mcp add --transport http coredash https://app.coredash.app/api/mcp\n```\n\nThen 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`.)\n\n**API key — for headless/CI/automation or agency multi-project setups:**\n\n```bash\nclaude mcp add --transport http coredash https://app.coredash.app/api/mcp \\\n  --header \"Authorization: Bearer cdk_YOUR_API_KEY\"\n```\n\nReplace `cdk_YOUR_API_KEY` with your key from CoreDash → Project Settings → API Keys (MCP).\n\nRestart Claude Code after installing so the SessionStart hook fires on a fresh conversation.\n\n### Cursor\n\nThe 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.\n\n### Gemini CLI\n\nThe repo ships a Gemini extension at `gemini-extension.json` with `GEMINI.md` auto-loading the orchestrator skill. Install via:\n\n```bash\ngemini extensions install https://github.com/corewebvitals/cwv-superpowers\n```\n\n### Other MCP-compatible clients\n\nThe CoreDash MCP server works with any client that supports HTTP MCP servers:\n\n| Setting | Value |\n|---|---|\n| Endpoint | `https://app.coredash.app/api/mcp` |\n| Auth (interactive native/CLI clients) | Browser login (OAuth) — no key |\n| Auth (config-file / headless clients) | Header `Authorization: Bearer cdk_YOUR_API_KEY` |\n\nAsk the agent to \"set up CoreDash\" — the `setting-up-coredash` skill walks through detailed per-client setup (Claude Desktop, Windsurf, Gemini CLI, etc.).\n\n### Verify installation\n\nAsk your agent: **\"What are my Core Web Vitals?\"**\n\nIf CoreDash is connected, it will return your real LCP, INP, CLS, FCP, and TTFB data.\n\n### Permission prompts\n\nThe 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.\n\n## Usage\n\nStart Claude Code (with Chrome for full analysis):\n\n```bash\nclaude --chrome\n```\n\nThen just ask:\n\n- **\"Find my biggest CWV issue and fix it\"** — automated discovery + diagnosis + fix\n- **\"My product pages are slow\"** — targeted diagnosis on a page section\n- **\"LCP on /product/shoes-42 is bad\"** — drill into a specific URL\n- **\"Generate a report\"** — get an interactive HTML report with all findings\n\nThe skill handles capability detection automatically. It works with:\n\n| Chrome | CoreDash | What you get |\n|---|---|---|\n| Yes | Yes | Full analysis — RUM finds the issue, Chrome explains why, code fix + visual report |\n| No | Yes | RUM diagnosis — element, bottleneck phase, trend, code fix (no Chrome visuals) |\n| Yes | No | Lab-only audit — Chrome trace without real user context (setup guide offered) |\n| No | No | Setup wizard — guides you through installing both |\n\n## How It Works\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│  1. Discovery                                               │\n│     CoreDash → worst pages, worst metrics, distributions    │\n├─────────────────────────────────────────────────────────────┤\n│  2. Diagnosis                                               │\n│     LCP: TTFB / LOADDELAY / LOADTIME / RENDERDELAY         │\n│     INP: INPUTDELAY / PROCESSING / PRESENTATION             │\n│     CLS: 5 cause patterns (images, fonts, injected, ...)   │\n├─────────────────────────────────────────────────────────────┤\n│  3. Chrome Trace                                            │\n│     Mobile emulation (Fast 3G, 4x CPU slowdown)            │\n│     Investigates ONLY the bottleneck phase from step 2     │\n├─────────────────────────────────────────────────────────────┤\n│  4. Root Cause                                              │\n│     Names the element, the cause, both evidence sources     │\n├─────────────────────────────────────────────────────────────┤\n│  5. Output                                                  │\n│     Code fix  /  HTML report  /  Both                       │\n└─────────────────────────────────────────────────────────────┘\n```\n\n## Skill Structure\n\nSix peer skills: one orchestrator + five specialist skills. The orchestrator runs the full multi-step flow; the specialists can also be invoked directly.\n\n```\ncwv-superpowers/                        ← Repo root (git repo)\n├── .claude-plugin/marketplace.json     ← Claude Code marketplace listing\n├── .cursor-plugin/plugin.json          ← Cursor manifest\n├── gemini-extension.json               ← Gemini CLI extension manifest\n├── GEMINI.md                           ← Gemini auto-loaded context\n├── .version-bump.json                  ← Single source of truth for version\n├── scripts/bump-version.sh             ← Keeps all 10 version fields in sync\n└── plugins/cwv-superpowers/\n    ├── .claude-plugin/plugin.json      ← Claude Code plugin metadata\n    ├── hooks/\n    │   ├── hooks.json                  ← SessionStart hook config\n    │   ├── hooks-cursor.json           ← Cursor hook config\n    │   └── session-start               ← Inlines orchestrator SKILL.md into context\n    └── skills/\n        ├── cwv-superpower/             ← Orchestrator (Step 0–5 flow)\n        │   ├── SKILL.md\n        │   └── templates/\n        │       ├── report-rum.html     ← RUM-only report template\n        │       └── report-full.html    ← Full report (filmstrip, waterfall)\n        ├── diagnosing-lcp/SKILL.md     ← LCP diagnosis (phases + attribution)\n        ├── diagnosing-inp/SKILL.md     ← INP diagnosis (phases + LOAF scripts)\n        ├── diagnosing-cls/SKILL.md     ← CLS diagnosis (cause pattern matching)\n        ├── tracing-with-chrome/SKILL.md ← Chrome tracing (per-phase investigation)\n        └── setting-up-coredash/SKILL.md ← CoreDash MCP installation guide\n```\n\n**When each skill activates:**\n\n- `cwv-superpower` — \"find my biggest CWV issue\", \"audit this site\", multi-metric analysis.\n- `diagnosing-lcp` / `diagnosing-inp` / `diagnosing-cls` — the user names one specific metric.\n- `tracing-with-chrome` — the user has a URL + metric + suspected cause and wants a lab trace.\n- `setting-up-coredash` — connecting CoreDash MCP from scratch.\n\n## Example Output\n\n**Root cause statement:**\n\n> **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\"`.\n>\n> **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.\n>\n> **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>`.\n\n**Code fix:**\n\n```html\n<!-- Add to <head> -->\n<link rel=\"preload\" href=\"/images/hero.jpg\" as=\"image\" fetchpriority=\"high\">\n\n<!-- Change the img element -->\n<img src=\"/images/hero.jpg\" alt=\"Hero\" fetchpriority=\"high\">\n```\n\n## Updating\n\n```bash\n/plugin marketplace update cwv-superpowers\n/plugin install cwv-superpowers@cwv-superpowers\n```\n\nRestart Claude Code after updating.\n\n## Contributing\n\nIssues and PRs welcome at [github.com/corewebvitals/cwv-superpowers](https://github.com/corewebvitals/cwv-superpowers).\n\n### For maintainers\n\nVersions across all 10 manifests (Claude Code, Cursor, Gemini CLI, plugin.json, and all 6 SKILL.md files) are kept in sync via one script:\n\n```bash\n./scripts/bump-version.sh --check      # show current versions + detect drift\n./scripts/bump-version.sh --audit      # check + scan repo for stray version strings\n./scripts/bump-version.sh 2.1.0        # bump every declared file to 2.1.0\n```\n\nThe 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).\n\n## License\n\nMIT\n",
  "bytes": 10539,
  "sha": "8217bf9159c3351b0a34ef5cef064c8513633c0cd5bc15c9c067da11ae08b8eb",
  "repo_slug": "corewebvitals/cwv-superpowers",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_corewebvitals_cwv_superpowers_38f9ecf3/readme"
}