clarity-analyzer

Clarity Analyzer

Analyze website visitor behavior from Microsoft Clarity CSV exports. Turns raw click and scroll data into structured CRO insights with actionable recommendations.

When to use this skill

• When the user provides Clarity CSV files (click data, scroll data, or both)
• When the user mentions "Clarity export," "Clarity data," "scroll depth data," "click heatmap," or similar
• When the user asks about heatmaps, page performance, CRO, or user behavior analysis
• When the user asks questions like "where are users clicking," "where do users drop off," or "what's working on this page"
• When the user has CSVs with columns like "Scroll depth," "No. of visitors," "% drop off," "Button," "Clicks," or "% of clicks"

Instructions

Step 1: Read and validate the CSVs

Read all provided CSV files. Clarity exports have a standard format:

Metadata rows (top of file):

• Project name
• Date range
• URL regex filter
• Page views count
• Total clicks (click files only)

Click CSV columns: Rank, Button (CSS selector), Clicks, % of clicks

Scroll CSV columns: Scroll depth (5–100 in increments of 5), No. of visitors, % drop off

If files are referenced by name or path, read them directly. If the user points to a directory, look for CSV files matching common Clarity naming patterns.

Step 2: Print structured analysis to console

Output the analysis directly in the conversation. Include all five sections:

1. Page summary

• Date range, page views, total clicks, and the URL being analyzed (from CSV metadata)

2. Scroll depth analysis

• Summarize the scroll curve in a table showing key depth milestones
• Identify the "scroll cliff" — the depth range where the steepest visitor loss happens
• Call out what % of visitors reach 25%, 50%, 75%, and 100%

3. Click behavior analysis

• Translate CSS selectors into human-readable element names (nav links, CTAs, filter dropdowns, search boxes, cards, etc.)
• Group related clicks on the same UI element (e.g., a card's title click, CTA link click, and container click are all "first card" clicks) and report the combined count
• Present as a ranked table

4. Key findings

• 3-5 insights as plain-language observations about visitor intent and behavior
• Focus on what visitors are trying to do and where the page fails them

5. Recommendations

• Actionable, prioritized suggestions tied directly to the data

Multi-page analysis: If analyzing multiple pages, present each page separately, then add a comparison section highlighting differences in engagement patterns.

Small samples: If page views are under ~30, flag that the data is too limited for reliable behavioral conclusions but still note directional signals.

Step 3: Offer a Slack-ready summary

After the analysis, ask the user if they want a Slack-ready version. If yes, write a concise, conversational summary suitable for pasting into a team Slack channel:

• Lead with a one-line TL;DR
• Use short sections with bold headers: "The numbers," "What's happening," "What we think we should do," "Next steps"
• Keep it scannable — bullet points, no jargon, no CSS selectors
• End with a conversation starter ("Thoughts?")

Interpreting CSS selectors

Clarity exports click targets as verbose CSS selectors. Translate them into plain language using these patterns:

Selector pattern	Likely element
#customNav / HEADER elements	Navigation items (use nth-of-type to identify which link)
A tags with font-bold in nav context	Nav menu links
Elements with bg-black, text-white, border-black	CTA buttons
SELECT elements	Dropdown filters
#search or INPUT elements	Search inputs
DIV.grid with child A elements	Card grids (case studies, blog posts, etc.)
IMG inside nav A tags	Logo clicks
pointer-events-none with group-hover	Dropdown/flyout menus

Use contextual clues from parent classes:

• bg-purple-gradient, bg-orange — branded/promotional sections
• border-t, border-b — section dividers (social proof bars, testimonial strips)
• overflow-hidden — carousel or contained content areas
• footer or bottom-positioned elements — footer links

Output format

The output is conversational markdown printed directly to the console — not a file. Use tables for scroll depth and click rankings. Use bold headers and numbered lists for findings and recommendations. Keep the tone analytical but accessible.

Using alongside the official Clarity MCP server

Microsoft offers an official Clarity MCP server that connects live to your Clarity account. The two tools are complementary:

• Clarity MCP server = data access. It pulls metrics (traffic, engagement time, scroll depth) and session recordings via natural language queries. It does not interpret the data or produce CRO recommendations.
• This skill = analysis layer. It takes click and scroll data and turns it into actionable insights — translating CSS selectors into plain language, identifying behavioral patterns, and generating findings and recommendations.

If you have the Clarity MCP server connected, you can use it to pull data and then hand the exports to this skill for the CRO analysis. The CSV export path remains valuable because Clarity's click-level CSS selector data (which this skill specializes in interpreting) is not currently available through the MCP server's API.

Dependencies

• Required: CSV files exported from Microsoft Clarity (click and/or scroll data)
• Required: File read access (Claude Code or Cowork with the folder selected)
• Optional: Screenshots of the page being analyzed (helps map CSS selectors to visual elements)
• Optional: Microsoft Clarity MCP server for pulling data without manual CSV exports