clarity-skill

clarity-skill

Point Claude Code at your Microsoft Clarity project and get back ranked, actionable UX/performance/UI fixes — not just a metrics dump.

It pulls aggregated metrics from the official Data Export API (rage clicks, dead clicks, script errors, excessive scroll, quickback, scroll depth, engagement time), optionally merges per-session/event exports, ranks the findings by traffic-weighted severity, and — when run inside your codebase — proposes or applies the actual fix.

If this is useful, a ⭐ on the repo helps other people find it.

What it does

1. Fetches aggregated metrics from the Clarity Data Export API (RageClickCount, DeadClickCount, ScriptErrorCount, ExcessiveScroll, QuickbackClick, ScrollDepth, EngagementTime, Traffic), broken down by URL, device, browser, etc. Caches responses locally to stay under Clarity's 10-requests/day/project limit.
2. Optionally ingests per-session/event data if you have it (Clarity itself doesn't expose raw session recordings via a public API — only the dashboard UI has that).
3. Ranks findings by traffic-weighted severity against your project baseline (see references/metrics-guide.md for the heuristics).
4. Produces a written report, an HTML dashboard artifact, and — when run inside a codebase — proposed or applied code fixes for the flagged pages.

Install

Option A — copy or clone into your skills folder

Project-scoped (only this project):

git clone https://github.com/VincenzoManto/clarity-skill "<project>\.claude\skills\clarity-skill"

User-scoped (all your projects):

git clone https://github.com/VincenzoManto/clarity-skill "$env:USERPROFILE\.claude\skills\clarity-skill"

Or symlink instead of cloning, if you want local edits to apply everywhere:

New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.claude\skills\clarity-skill" -Target "C:\path\to\your\local\clarity-skill"

Option B — install as a Claude Code plugin

/plugin marketplace add VincenzoManto/clarity-skill
/plugin install clarity-skill

Setup

Generate a Clarity API token: Clarity dashboard → Settings → Data Export → API tokens (max 5 active tokens per project), then set it before using the skill:

$env:CLARITY_API_TOKEN = "your-token-here"

Usage

Just ask Claude Code something like:

"Analize Clarity data of the last week and propose UX fixes"

"Use clarity-skill to understand why the checkout page has rage click"

Claude will run the scripts, analyze the results, and walk you through findings + fixes. You can also run the scripts directly:

node scripts/fetch-clarity.js --days 3 --dim1 URL --dim2 Device
node scripts/analyze.js > analysis.json
node scripts/generate-dashboard.js --input analysis.json --open

The last command opens a self-contained, offline HTML dashboard in your default browser — top findings, severity-ranked bars per segment, and (if you supplied a session/event export) a per-page rage/dead-click/error table.

Files

• SKILL.md — the skill definition Claude Code reads.
• scripts/fetch-clarity.js — calls the Clarity Data Export API, caches responses to .clarity-cache/.
• scripts/analyze.js — merges cached data (+ optional session/event export) into ranked findings.
• references/clarity-api.md — API endpoint, auth, params, rate limits.
• references/metrics-guide.md — what each metric means and the thresholds used to flag issues.
• references/session-event-format.md — expected shape for optional per-session/event export files.

Reading individual session recordings

Microsoft Clarity's public API only exposes aggregated metrics for the last 1–3 days, rate-limited to 10 requests/day/project — it does not expose individual session recordings or raw event streams. To read those, this skill can drive a real browser against your own Clarity dashboard:

npm install playwright
npx playwright install chromium
node scripts/clarity-login.js                 # one-time, log in manually
node scripts/scrape-sessions.js --project <projectId> --limit 30 --out sessions.json
node scripts/analyze.js --events sessions.json

This is DOM automation against an undocumented, changeable UI — it captures session metadata and rage/dead-click/error markers, not raw mouse-movement replay data, and the CSS selectors it relies on will break whenever Microsoft changes the dashboard markup (see the header of scripts/scrape-sessions.js). It's your responsibility to confirm this use stays within Clarity's Terms of Service for your account. Alternatively, skip the automation entirely and pass in any session/event export you already have — see references/session-event-format.md.

License

MIT