heatmap-analyst

name	heatmap-analyst
description	Click-engagement analyst that pulls element-level click data, a page-level scroll proxy, and bounce/exit signals from Humblytics to surface UX friction and ignored CTAs. Generates prioritized, data-backed optimization recommendations. NOTE: the Humblytics public API does NOT provide pixel-level click heatmaps, scroll-depth distributions, or rage-click detection — those need a dedicated heatmap tool. Use when auditing element-level click patterns, finding ignored CTAs, gauging scroll engagement, or diagnosing on-page friction. Triggers: click analysis, element clicks, ignored CTA, click engagement, scroll engagement, UX friction, interaction audit.
metadata	{"version":"1.0.0","author":"Humblytics"}

Heatmap Analyst

Purpose

Analyze Humblytics click-engagement data (element/target-level clicks, a single page-level scroll proxy, and bounce/exit signals) to diagnose UX friction and generate prioritized design recommendations. This skill turns the interaction data the API actually exposes into specific, ranked improvements for layout, CTAs, and content hierarchy.

Scope note — what the Humblytics public API does and does not give you. The API provides element/target-level click counts (with UTM breakdown), a single average scroll percentage per page, and bounce/exit signals. It does NOT provide pixel-level click heatmaps (x/y coordinates), a 25/50/75/100 scroll-depth distribution, rage-click detection, dead-zone maps, or per-device click segmentation. Anything in that second list requires a dedicated heatmap tool (e.g. Hotjar, Microsoft Clarity) — do not promise it from Humblytics. See "NOT available via Humblytics API" below.

When to Use

• A page has a high bounce rate and you need to understand why
• CTAs are present but click-through rate is below benchmark
• You want to verify that the important content is actually being seen
• Users are reporting confusion or friction on a specific page
• You're auditing a page before a redesign or A/B test
• Investigating whether traffic from a specific source behaves differently on-page

Credentials

This skill reads a Humblytics API key from the environment. Never paste API keys directly into chat — they persist in transcripts and logs.

Setup (one time):

1. cp .env.example .env at the repo root (the .env.example lives at the repo root, not in this skill dir) and fill in HUMBLYTICS_API_KEY
2. source .env in your shell before running the agent (or use direnv, or add the exports to your shell profile)
3. Get the key from Humblytics Dashboard > Settings > API
4. The skill will ask for your Property ID (also in Dashboard > Settings > API)

• Base URL: https://app.humblytics.com/api/external/v1
• Auth header: Authorization: Bearer $HUMBLYTICS_API_KEY
• Docs: https://docs.humblytics.com/

If HUMBLYTICS_API_KEY is not in the environment, stop and point the user at .env.example (at the repo root) — do not accept the key in chat.

Before You Start

1. Confirm the property ID — Ask which Humblytics property to analyze
2. Identify the target page(s) — Which URL(s) are in scope
3. Time range — Default to last 30 days; shorter windows are noisier
4. Sample size check — Pages below ~500 sessions in the window produce unreliable heatmaps
5. Context — Pull product/persona context if available so recommendations match the audience

Core Workflow

Step 1: Pull the Interaction Data

For each target page, fetch what the API actually returns:

• Element-level clicks — clicks grouped by element target (and secondary), with clicks, unique_sessions, most_recent, a per-element trend, and a utm_breakdown (clicks + share by UTM source/medium/campaign). This is element-level, not an x/y coordinate map.
• Scroll proxy — a single avg_scroll_percent for the page (one number, e.g. 23.7), plus bounce_rate, page_views, unique_visitors, avg_session_length. This is not a 25/50/75/100 depth distribution.
• Cross-page click comparison — per-page total_clicks, unique_sessions, and top_targets[]{target, clicks, share}.
• Entry/exit friction — entry and exit pages as a friction proxy.

Click CTR is not a field in the API — derive an engagement rate yourself as clicks / unique_sessions (or per-page top_target.share) when you need a CTR-like proxy.

Relevant Humblytics endpoints (all require Authorization: Bearer $HUMBLYTICS_API_KEY; pass start, end as ISO8601 and a timezone IANA name — there is no ?period= shorthand):

• GET /properties/{propertyId}/clicks/details?page=/path&start=…&end=…&timezone=… — element/target-level clicks + UTM breakdown
• GET /properties/{propertyId}/clicks/breakdown?start=…&end=…&timezone=… — cross-page top targets
• GET /properties/{propertyId}/pages/details?page=/path&start=…&end=…&timezone=… — avg_scroll_percent (scroll proxy) + bounce_rate
• GET /properties/{propertyId}/pages/breakdown?start=…&end=…&timezone=… — page-level views/bounce across pages
• GET /properties/{propertyId}/traffic/entry-exit-pages?start=…&end=…&timezone=… — entry/exit friction proxy

NOT available via Humblytics API (needs a dedicated heatmap tool): pixel-level click coordinate heatmaps, scroll-depth distribution (25/50/75/100%), rage-click detection, dead-zone maps, and per-device click segmentation. If the user needs any of these, tell them Humblytics does not return them and point to a purpose-built heatmap tool (Hotjar, Microsoft Clarity, etc.).

Step 2: The Three Diagnostic Questions

Run each page through these three questions, using only data the API returns:

Q1 — Are visitors clicking what you want them to click?

• Primary CTA click share: is the CTA target a meaningful fraction of total_clicks (use its share from clicks/breakdown or clicks from clicks/details)?
• Secondary CTA click share: proportional to its importance?
• Which target dominates clicks, and is it a high-value action or a low-value/navigation element?

Q2 — Are visitors engaging deeply enough to see the important content?

• avg_scroll_percent: a low average (e.g. ~24%) suggests most visitors never reach below-fold content. This is a single average, not a depth distribution — do not claim "X% reached 50%".
• Is the primary CTA likely above or below where that average scroll lands?
• Cross-reference with bounce_rate from pages/details.

Q3 — Where is the friction?

• High bounce_rate / exit share (from pages/details and traffic/entry-exit-pages) on a page that should convert = friction proxy.
• Low scroll engagement on a long page where the CTA sits deep.
• A CTA target that gets almost no clicks despite high page views = ignored CTA.

Frustration signals like rage clicks and clicks on non-interactive elements are not available from Humblytics — use the friction proxies above, and recommend a dedicated heatmap/session-replay tool if true rage-click detection is needed.

Step 3: Identify the Top 3 Issues

Rank all issues by expected conversion impact:

1. Blocker — Primary CTA gets a negligible share of clicks, or low avg_scroll_percent suggests core content is rarely reached
2. Friction — High bounce_rate / exit share on a page meant to convert; confusing affordances
3. Waste — High click share on low-value elements (e.g., a Link/nav target dominating clicks instead of the CTA)

Always state the evidence: "avg_scroll_percent on the homepage is 24% and bounce_rate is 0.89, while the signup CTA hero-try-free took only 1.2% of clicks."

Step 4: Generate Recommendations

For each issue, provide:

• Specific change — "Move CTA from below the pricing table to above the hero fold"
• Expected lift — Estimate based on traffic volume and issue severity
• Implementation difficulty — Copy change / layout change / redesign
• How to verify — Which metric to watch; which follow-up A/B test validates the fix

Step 5: Output Format

Write a clean report with:

PAGE: [/path]
DATE RANGE: [window]
PAGE VIEWS / UNIQUE VISITORS: [page_views] / [unique_visitors]

HEADLINE FINDING:
[1 sentence capturing the biggest insight]

CLICK PATTERN SUMMARY (from clicks/details + clicks/breakdown):
- Primary CTA target + click share: [target] ([share]% of clicks)
- Highest-click element: [target] ([share]% of clicks)
- Total clicks / unique sessions: [total_clicks] / [unique_sessions]
- Notable UTM skew (if any): [utm_source/medium] drives [share]% of a target's clicks

SCROLL ENGAGEMENT (from pages/details — single average, not a distribution):
- avg_scroll_percent: [N]%
- Implication: [most visitors likely do / do not reach below-fold content]

FRICTION PROXIES:
- bounce_rate: [N]
- Top exit pages (entry-exit-pages): [pages]

TOP 3 RECOMMENDATIONS (prioritized):
1. [Change] — Expected impact: [X] — Difficulty: [level]
2. [Change] — Expected impact: [X] — Difficulty: [level]
3. [Change] — Expected impact: [X] — Difficulty: [level]

SUGGESTED A/B TESTS:
- [Test hypothesis with clear control vs variant]

Interpretation Cheatsheet

Based only on Humblytics-available signals (element-level click shares, single avg_scroll_percent, bounce_rate/exit):

Pattern	Likely Cause	Action
A generic Link/nav target dominates clicks, CTA target near zero	CTA invisible, weak, or out-competed by navigation	Strengthen CTA prominence; reduce competing links
Low avg_scroll_percent on a long page	Weak hook, above-fold doesn't earn attention	Rewrite headline or move proof/CTA above the fold
CTA clicks concentrated on one variant	Other CTAs are invisible or redundant	Remove redundant CTAs; test single CTA variant
High bounce_rate + low scroll on a convert-intent page	Above-fold fails to engage	Audit hero copy/offer; move value prop up
Click share spread thinly across many targets	No clear visual hierarchy	Add hierarchy: emphasize primary action
One UTM source's clicks skew heavily to a low-value target	Mismatched intent from that channel	Align landing experience to that source's intent

Patterns that require pixel coordinates, rage-click detection, or per-device click maps (e.g. "rage clicks on image", "desktop clicks ≠ mobile clicks") are not diagnosable from Humblytics — use a dedicated heatmap tool.

Related Skills

• cro-optimizer — Combines heatmap findings with funnel data for holistic CRO
• page-cro — Full 10-point page audit; heatmap analysis is one dimension
• ab-test-generator — Takes heatmap recommendations and launches them as tests

Shared Frameworks (REQUIRED reading)

Heatmap interpretation is highly context-dependent. The shared primitives in skills/_shared/ keep recommendations grounded.

• _shared/frameworks/preflight-checklist.md — confirm minimum 500 sessions per page-period combo before drawing conclusions. Heatmap patterns on smaller samples are noise.
• _shared/frameworks/anti-patterns.md — heatmap-relevant counter-evidence:
  • Mobile hamburger menu: NN/g says it hurts discoverability on task-oriented SaaS (Spotify hamburger → bottom-tab = +30% menu interactions). BUT Amazon's hamburger beat dropdown for browse-heavy ecom. Site_type is load-bearing — don't recommend bottom-tab universally.
  • Mobile exit-intent: architecturally broken (no cursor → no mouseleave event). If heatmap shows users leaving on mobile, the answer is not an exit modal.
  • Progress-bar velocity: NIH RCT shows slow-to-fast progress bars nearly double form abandonment. If your heatmap shows form-step drop-off, audit progress bar acceleration before redesigning fields.
• _shared/benchmarks/patterns.json — when heatmap data confirms a problem (e.g., low scroll past 30%, CTA clicks dominated by a single variant), match to a pattern_id and quote the evidence-backed lift range for the fix. Most relevant categories: cta, navigation, above_fold.