---
name: microsoft-clarity
description: "Read a site's live Microsoft Clarity data, find the single worst leak in the money path, and hand back placement-specific fixes (where to put a CTA, what's broken, what to test next) ranked by expected impact. Use when the founder says 'run my Clarity', 'check my Clarity', 'where are people dropping off', 'where should I put my CTA', or 'what should I fix on my site'. Requires a live Microsoft Clarity MCP connection, does not work from pasted numbers."
user_invokable: true
tested_date: 2026-07-31
tested_with: claude-code v2.x
---

# Microsoft Clarity Lens

Turns a live Microsoft Clarity connection into a diagnosis, not a symptom list. Clarity shows where
visitors struggle, where they click, and how far they get. This skill segments that data, locates
the one stage of the funnel leaking hardest, and prescribes the specific fix at the specific spot,
each one shippable as a test with a metric attached.

Read `references/reading-framework.md` before starting. The whole point of this skill is that it
reasons the same way every time about heat maps, funnel stages, and cause, not that it improvises
a top-three list from whatever numbers are loudest.

Built by DNA (Daily Needs Association).

## Before you start

1. **Confirm the Clarity MCP is live.** Attempt one lightweight `query-analytics-dashboard` read.
   If it fails or the tools are not available, stop. Do not ask the founder to paste numbers instead
   and do not reason on memory of what a Clarity dashboard usually shows. Print this setup path and
   wait:
   - Open the Clarity dashboard for this site, go to Settings > Data Export, generate a new API
     token (a Data Export scoped token, theirs alone, one token per Clarity project).
   - Add the Microsoft Clarity MCP server to their own Claude Code config with that token.
   - Come back and run this skill again.
2. **Ask for the two things Clarity cannot tell you.** What counts as a conversion on this site
   (purchase, signup, booking, whatever the real goal is), and which pages are the money pages
   (product, cart, checkout, booking form, pricing). If the founder does not know, use the
   highest-traffic pages with an on-page action as a working assumption and say plainly that it is
   an assumption, not a confirmed fact.
3. **Look for a prior run.** If `./clarity-output/<site>/baseline.md` exists from an earlier run,
   read it first. This run opens by checking whether the experiments it shipped last time actually
   moved their metric, per the compounding principle in the reading framework.

## Run

1. **Segment before reading anything else.** Pull the dashboard sliced by device (mobile vs
   desktop), traffic source (paid, organic, social, direct), landing page, and new vs returning.
   Never reason from a site-wide average; state plainly that an average this broad can hide a single
   segment burning money while looking unremarkable in the headline number.

2. **Map pages to funnel stages.** Assign every page with meaningful traffic to one of: entry,
   browse, offer, intent, checkout. For each transition, compute the relative drop (not the raw
   count). The stage with the largest relative drop is the bottleneck. Every fix in this run aims
   at that stage first; a fix on a healthy stage is a lower priority than a fix on the bottleneck,
   regardless of how bad that other page's raw numbers look.

3. **Diagnose each signal in context.** For every rage click, dead click, quick back, excessive
   scroll, or JS error on or near the bottleneck stage, work out what it means using the
   signal-to-cause table in `references/reading-framework.md`, cross-checked against which device
   and which stage it happened on. A signal alone is not a finding; a signal plus a stage plus a
   device is.

4. **Run the placement pass.** This is the heat map logic, applied as a rule, not a guess:
   - Compare click concentration against scroll depth on the same page. If most visitors never
     scroll past the point where an existing CTA sits, the CTA is below the attention line. State
     the fix as: move it up to before the drop-off point, not just "add more CTAs."
   - A click cluster on something that is not clickable is a pure intent signal. That is where a
     button belongs; the visitor already tried to act there.
   - A dead zone around an existing CTA means the CTA is invisible, mislabelled, or not trusted,
     not that the page needs another one. Say which of the three it most likely is and why.
   Apply this pass specifically to the bottleneck stage's pages first, then note anything equally
   clear-cut elsewhere.

5. **Confirm with recordings.** Pull `list-session-recordings` filtered to the bottleneck page,
   sorted by highest click count and longest duration, favouring sessions that did not convert.
   Watch for the why behind the where: what the visitor was actually trying to do when the friction
   signal fired. If recordings contradict the quantitative read, trust the recordings and say so.

6. **Rank and prescribe.** Score each candidate fix by rough expected impact: traffic to that page
   multiplied by the drop rate at that step. A small lift on a high-traffic checkout outranks a
   large lift on a page almost nobody sees. For each of the top three to five, write it as a
   testable experiment: the hypothesis, the specific change (what, and exactly where on the page),
   the one metric that should move, and roughly how long to wait before reading the result.

7. **Write the baseline.** Save the segment figures, the bottleneck stage, and the shipped
   experiments to `./clarity-output/<site>/baseline.md` with an ISO 8601 timestamp supplied by the
   caller, never invented. This is what the next run reads first.

8. **End on the one move.** Close the chat response (not the file) with the single highest-leverage
   fix: the change, the mechanism (why it should move the number), and the first concrete step to
   make it happen this week.

## Output format

```
# Clarity Lens: [site] — [date]

## The bottleneck
[which funnel stage is leaking hardest, the relative drop, and the segment(s) it's worst in]

## What's causing it
[2-4 diagnoses: signal + stage + device -> most likely cause]

## Where to put things (heat map read)
[specific placement calls: move X above the scroll line, a button belongs at Y, Z is a dead CTA]

## Ranked experiments
1. [hypothesis] — change: [specific action] — watch: [metric] — read result after: [timeframe]
2. ...
3. ...

## Confirmed by recordings
[what watching non-converters on the bottleneck page showed]

## This week's one move
[the single highest-leverage change: the move, the mechanism, the first step]
```

## Guardrails

Never promise a revenue, order, or traffic outcome from any fix. State the mechanism and the
expected direction (why this should reduce a specific leak), never a projected number. The honest
frame is a clearer path for the visitor; the founder still owns every call and every result.

Never edit the live site. This is a detect-and-recommend skill. Stage any resulting change, show
it, ship it only on the founder's own go.

Never invent a number that was not read from Clarity in this run. If a segment, a signal, or a
recording cannot be pulled, say so plainly and mark that part Unknown with a one-line reason rather
than filling the gap with a plausible-sounding guess.

## Style

No dashes. Plain, direct language, no jargon the founder has to look up. Say what the data shows,
what it most likely means, and what to do about it, in that order, every time.
