From b6f3215160982f2d7b2a911b08459abc87474ee8 Mon Sep 17 00:00:00 2001 From: Naitik Soni <91239827+naitik-mixpanel@users.noreply.github.com> Date: Tue, 9 Jun 2026 23:17:20 +0530 Subject: [PATCH 1/2] new skill: analyze-report --- .../skills/analyze-report/SKILL.md | 254 ++++++++++++++++++ .../analyze-report/references/read-flows.md | 116 ++++++++ .../analyze-report/references/read-funnels.md | 117 ++++++++ .../references/read-insights.md | 111 ++++++++ .../references/read-retention.md | 124 +++++++++ .../skills/analyze-report/SKILL.md | 254 ++++++++++++++++++ .../analyze-report/references/read-flows.md | 116 ++++++++ .../analyze-report/references/read-funnels.md | 117 ++++++++ .../references/read-insights.md | 111 ++++++++ .../references/read-retention.md | 124 +++++++++ .../skills/analyze-report/SKILL.md | 254 ++++++++++++++++++ .../analyze-report/references/read-flows.md | 116 ++++++++ .../analyze-report/references/read-funnels.md | 117 ++++++++ .../references/read-insights.md | 111 ++++++++ .../references/read-retention.md | 124 +++++++++ 15 files changed, 2166 insertions(+) create mode 100644 plugins/mixpanel-mcp-eu/skills/analyze-report/SKILL.md create mode 100644 plugins/mixpanel-mcp-eu/skills/analyze-report/references/read-flows.md create mode 100644 plugins/mixpanel-mcp-eu/skills/analyze-report/references/read-funnels.md create mode 100644 plugins/mixpanel-mcp-eu/skills/analyze-report/references/read-insights.md create mode 100644 plugins/mixpanel-mcp-eu/skills/analyze-report/references/read-retention.md create mode 100644 plugins/mixpanel-mcp-in/skills/analyze-report/SKILL.md create mode 100644 plugins/mixpanel-mcp-in/skills/analyze-report/references/read-flows.md create mode 100644 plugins/mixpanel-mcp-in/skills/analyze-report/references/read-funnels.md create mode 100644 plugins/mixpanel-mcp-in/skills/analyze-report/references/read-insights.md create mode 100644 plugins/mixpanel-mcp-in/skills/analyze-report/references/read-retention.md create mode 100644 plugins/mixpanel-mcp/skills/analyze-report/SKILL.md create mode 100644 plugins/mixpanel-mcp/skills/analyze-report/references/read-flows.md create mode 100644 plugins/mixpanel-mcp/skills/analyze-report/references/read-funnels.md create mode 100644 plugins/mixpanel-mcp/skills/analyze-report/references/read-insights.md create mode 100644 plugins/mixpanel-mcp/skills/analyze-report/references/read-retention.md diff --git a/plugins/mixpanel-mcp-eu/skills/analyze-report/SKILL.md b/plugins/mixpanel-mcp-eu/skills/analyze-report/SKILL.md new file mode 100644 index 0000000..6716944 --- /dev/null +++ b/plugins/mixpanel-mcp-eu/skills/analyze-report/SKILL.md @@ -0,0 +1,254 @@ +--- +name: analyze-report +description: > + Read and explain a Mixpanel report or chart — what it shows, what's + notable, and what's worth a closer look. Use whenever the user asks to + interpret, explain, summarize, review, or break down an existing + chart, report, or saved query in Mixpanel. Trigger phrases: + "what does this chart show", "explain this report", "interpret this + chart", "summarize this for me", "what's notable here", "anything + weird in this chart", "tell me what's happening", "review this + insight", "walk me through this report", "what's the takeaway from + this". Also trigger when the user pastes a Mixpanel chart or report + URL and asks anything about it. Lean by default — surfaces what the + report shows and flags notable patterns, but does not chase root + causes. Do NOT trigger for building new charts, reviewing entire + dashboards, or full root-cause diagnostic workflows. Requires Mixpanel MCP. +compatibility: "Requires Mixpanel MCP. Works for any project the user has access to." +--- + +# Mixpanel Analyze Report + +Take a Mixpanel report or chart that already exists (or just got built) +and turn it into a one-screen summary the customer can act on. The skill +is **lean by default** — it explains what the report shows and flags +what's notable, but does not chase root causes unless the customer asks. + +If the customer's follow-up is "why is this happening" or anything +similar, treat that as a deeper root-cause investigation that is out of +scope here. Flag what you see and stop; don't attempt multi-step RCA +inline. This skill is built for fast interpretation. + +--- + +## When this skill runs, it does four things in order + +1. **Locate the report** — by URL, ID, or fresh build +2. **Pull the data** — re-run the query and parse the result +3. **Read the shape** — trend, anomalies, breakdown distribution +4. **Summarize for the customer** — what it shows, what's notable, what to do next + +--- + +## Step 1 — Locate the report + +Three input modes. Detect which one applies from the customer's message: + +### Mode A — Customer provides a URL or chart/report ID + +Most common. Mixpanel report URLs look like +`https://mixpanel.com/project//view//app/` +or include `report_id=`. Extract the ID(s). + +Use the relevant Mixpanel MCP tool to fetch the report's metadata and +configuration — this gives you the events, properties, filters, +breakdowns, date range, and chart type without having to ask the +customer. + +If you can't resolve the URL/ID (404, permission error, malformed URL), +say so plainly and ask if they meant a different report. + +### Mode B — Customer describes the report in natural language + +If the customer says "the DAU chart on my exec board" or "the funnel I +built last week," they're pointing at an existing report but haven't +given an ID. Use `Search-Entities` with `entity_types=['report']` to +find candidates. Show the top 3 matches with their titles and dates, +ask which one. + +If `Search-Entities` returns nothing useful, escalate to Mode C: + +> *"I can't find that report. Want to build it fresh and analyze that?"* + +### Mode C — Customer wants to analyze a report that doesn't exist yet + +The report has to be built before it can be analyzed. Build the chart +first (or ask the customer to point you at the configuration they want), +then come back to Step 2 and analyze the result. Once the chart is +built you'll have a `query_id` and a rendered widget; this skill picks +up from there. + +If the customer asks for both in one turn ("build me a DAU chart and +tell me what it shows"), do them as one workflow: build → analyze → +present together. + +--- + +## Step 2 — Pull the data + +For Mode A or B (existing report), call `Run-Query` with the same +configuration as the saved report to get fresh data. Don't trust cached +chart state — the customer may not have refreshed in days. + +For Mode C, you already have the `query_id` from the just-built chart. + +In both cases, you need: +- The query result data (time series, breakdown values, etc.) +- The chart configuration (events, properties, filters, date range, + chart type) + +Without configuration metadata, the analysis is shallow ("the line +goes up") instead of grounded ("checkout volume rose 18% WoW, isolated +to the iOS platform"). + +--- + +## Step 3 — Read the shape + +What to look for depends on chart type. Read the matching reference: + +- Insights → `references/read-insights.md` +- Funnels → `references/read-funnels.md` +- Retention → `references/read-retention.md` +- Flows → `references/read-flows.md` + +The references hold the **specific patterns** to look for in each +chart type. The high-level rules across all types: + +### What to surface (always) + +- **The current value** — what the metric is right now +- **Direction and magnitude of change** — is it up/down/flat, by how + much, vs. when +- **The biggest contributor** — if there's a breakdown, which segment + drives the volume + +### What to flag (only if present) + +- **Step-change anomalies** — a single point that breaks the pattern +- **Sustained drift** — the baseline has shifted (last 30 days look + different from prior 30 days) +- **Suspicious-looking segments** — one segment doing all the work, or + a segment that suddenly disappeared +- **Data quality cues** — a sudden jump that aligns with a deploy, an + event going to zero (looks like instrumentation broke) + +### What NOT to do + +- **Don't chase root cause.** If you spot a drop, flag it and stop. + Attributing the movement to a specific cause is a separate, deeper + workflow. +- **Don't speculate about external causes.** Saying "this might be + because of holiday traffic" without evidence is hallucination. +- **Don't recommend fixes.** The customer didn't ask for fixes. They + asked what the report shows. + +--- + +## Step 4 — Summarize for the customer + +Output structure (always this shape, length scales with content): + +``` +**What this shows** +[1–2 sentences: report subject, time window, current value] + +**The shape** +[1–3 sentences: trend direction, magnitude, key inflection points] + +**Worth noting** +[Bullet list — only items that meet the "flag" bar above. Skip if +nothing notable.] + +**Want to dig in?** +[Offer to either: (a) investigate why the movement happened, OR +(b) recut the report with a different breakdown, filter, or date range +if that would help] +``` + +Example output for a DAU chart that dipped: + +``` +**What this shows** +Daily Active Users over the last 30 days. Currently at 142K DAU. + +**The shape** +Flat through most of the month, with a clear step-down on March 18th +— DAU dropped from ~150K to ~135K and hasn't recovered. The post-drop +baseline is roughly 9% below the pre-drop average. + +**Worth noting** +- The drop is a step-change, not a gradual decline — typical of a + deploy, instrumentation change, or external event. +- Weekend dips are still present at the same magnitude — the issue + isn't a day-of-week shift. + +**Want to dig in?** +The shape suggests a single trigger event around March 18th. Want me +to dig into which segments are driving the drop? +``` + +Keep it tight. A customer reading this on a phone needs to get the +takeaway in the first paragraph. + +--- + +## Hybrid scope — when to stop + +Lean by default means: surface what's there, stop. The boundary is the +"why" question. If the customer asks any of: + +- "Why did this drop / spike / change?" +- "What's causing this?" +- "Where is it coming from?" +- "Is it specific users / regions / platforms?" + +…that's a root-cause investigation, which is a deeper, multi-step +workflow. Don't try to answer it inline here. Flag what the data shows +and offer the deeper dig as an explicit next step: + +> *"That's a root-cause question — it can take a few cuts to answer +> properly. Want me to dig into the segments driving this?"* + +Do not silently expand the analysis. An unbounded "why" question turns +a 30-second summary into a 10-minute investigation. Better to make the +boundary explicit and let the customer opt in. + +--- + +## Hard rules + +- **Always re-run the query.** Don't trust cached chart state. +- **Configuration metadata grounds the analysis.** Without knowing the + events/filters, you can't tell the customer what they're looking at. +- **Flag, don't diagnose.** Drift detection ≠ root cause. +- **One screen of output.** Long analyses lose the customer. +- **Make "why" an explicit next step.** Don't RCA inline. +- **No speculation about external causes.** Stick to what the data + shows. + +--- + +## Quick reference — MCP tools used + +| Step | Tool | +|---|---| +| 1 | `Get-Report` (for URL/ID), `Search-Entities` (for NL search) | +| 1, Mode C | build the chart first, then come back with the `query_id` | +| 2 | `Run-Query` | +| 3 | (no new tool calls — pure analysis on the data already pulled) | +| 4 | (output to user) | + +For chart-type-specific reading patterns, see `references/`. + +--- + +## When to stop and redirect + +- Customer asks "why" → that's a root-cause investigation; flag and + offer it as a deeper next step, don't do it inline +- Customer wants to modify or rebuild the chart → that's a build task, + out of scope for interpretation +- Customer wants to analyze the whole dashboard → out of scope; this + skill reads a single report +- Customer wants to clean up or manage old charts → out of scope diff --git a/plugins/mixpanel-mcp-eu/skills/analyze-report/references/read-flows.md b/plugins/mixpanel-mcp-eu/skills/analyze-report/references/read-flows.md new file mode 100644 index 0000000..a157cc0 --- /dev/null +++ b/plugins/mixpanel-mcp-eu/skills/analyze-report/references/read-flows.md @@ -0,0 +1,116 @@ +# Reading Flow charts — reference + +Use this reference when the chart being analyzed is a **Flow** (Sankey +showing event-to-event transitions before or after an anchor event). + +--- + +## What to read first + +1. **Anchor event volume** — how many users / events feed the anchor. + This is the denominator for everything downstream. + +2. **Top 1–3 paths** — what's the most common next event (or previous + event, for backward flows)? What % of users go that way? + +3. **Long tail** — how concentrated is the flow? If the top 3 paths + account for 80% of users, the flow has clear dominant patterns. If + the top 3 paths only account for 30%, the flow is fragmented. + +4. **Drop-off branch** — in forward flows, where do users *exit* the + product? In backward flows, where do they *enter* from? + +--- + +## Patterns to flag + +### Highly concentrated flow + +If one path accounts for >70% of post-anchor activity, that path is +the de facto product behavior. Flag it as the dominant pattern. + +> Flag as: *"After [anchor], [%] of users go to [next event] — that's +> the dominant path. Other branches are minor."* + +### Highly fragmented flow + +If the top 3 paths account for <40% combined, users do many different +things. This is either a power-user product (variety is healthy) or a +confusing UX (users don't know what to do next). + +> Flag as: *"Flow is fragmented — top 3 paths account for only [%] +> combined. Either deep variety in user behavior, or unclear next-step +> guidance."* + +### High drop-off branch in forward flow + +A "drop-off" or "session end" branch claiming a large share is the +flow chart's version of a funnel drop-off. Flag if it's a meaningful +share (e.g., >30% drop off immediately after the anchor). + +> Flag as: *"[%] of users drop off immediately after [anchor] — they +> don't proceed to any tracked event. Worth investigating where they +> go."* + +### Unexpected next event + +If the customer's mental model is "users do A → B" but the flow shows +"users do A → C", flag the surprise. The mental model and the data +disagree. + +> Flag as: *"Most users go to [unexpected event] after [anchor] — +> [expected event] is only [%]. The flow's not what you might +> intuitively expect."* + +### Backward flow showing unexpected sources + +If the customer is looking at "what leads to [event]" and the top +preceding event is a generic event (Page View, App Open) rather than +a meaningful action, the flow isn't very informative. Suggest a +deeper backward flow or filter out generic events. + +### Loops or repeating events + +If the flow shows the same event repeating (e.g., Page View → Page +View → Page View), the chart needs a filter on a property to +differentiate (which page?). Flag as a chart configuration issue. + +--- + +## Common reader pitfalls + +**Confusing share % with conversion %** +A flow showing "30% of users go to checkout after cart" is not the +same as "30% of cart-add events convert." The flow share is users who +did *that next event*, not conversion through a defined funnel. + +**Reading flows as session-bounded when they're not** +Mixpanel flows aren't strictly session-bounded — events from different +sessions hours or days apart can appear in the same flow. If the +customer is asking about within-session behavior, flag this caveat. + +**Treating the anchor as a starting point when it isn't** +Flows can be anchored anywhere, not just on entry events. If the +customer says "user journey from signup" and the chart anchors on a +mid-funnel event, the data isn't answering the question they asked. + +**Depth too shallow or too deep** +Depth-1 flows show only one next event — useful for "what's the +immediate next action" but not for path analysis. Depth-5+ flows are +visually noisy. If the chart depth doesn't match the question, surface +that. + +--- + +## Output focus + +Flow summary should answer: +- What's the dominant path? +- How concentrated is the behavior? +- What surprises (unexpected next/prior events, big drop-offs)? + +Skip: +- Speculating on UX changes ("maybe the checkout button is + hidden" — out of scope) +- Hypotheses on why users drop where they do (that's a root-cause + investigation, out of scope) diff --git a/plugins/mixpanel-mcp-eu/skills/analyze-report/references/read-funnels.md b/plugins/mixpanel-mcp-eu/skills/analyze-report/references/read-funnels.md new file mode 100644 index 0000000..115b83b --- /dev/null +++ b/plugins/mixpanel-mcp-eu/skills/analyze-report/references/read-funnels.md @@ -0,0 +1,117 @@ +# Reading Funnel charts — reference + +Use this reference when the chart being analyzed is a **Funnel**. + +--- + +## What to read first + +1. **Top-line conversion rate** — entry to final step. State as a %. + +2. **Where the biggest drop-off is** — identify the step with the + largest absolute % drop, not the largest absolute user drop. (A + step that loses 50% of 100 users matters more than one that loses + 5% of 1M users when you're talking about conversion quality.) + +3. **Trend over time** — if the funnel is shown as a time series + (conversion % over weeks/days), is it improving or degrading? + +4. **Cohort segments** — if the funnel has a breakdown (by source, + plan, platform), which segment converts best? Worst? + +--- + +## Patterns to flag + +### Surprising step where users drop + +Funnels are intuitive when drop-off is concentrated at known friction +points (e.g., payment step). Flag when it's not — when users drop at +an unexpected step. + +> Flag as: *"Most drop-off is at [step] — usually I'd expect [other +> step] to be the friction point. Worth checking if something changed +> on that page."* + +### Conversion rate collapse + +If the headline conversion rate dropped sharply over the time series, +identify which step caused it. The drop is rarely uniform — usually +one step regressed. + +> Flag as: *"Conversion fell from X% to Y% over the window — the +> regression is concentrated at the [step] step."* + +### Conversion rate looks too high or too low + +Some patterns are physically suspicious: +- Final-step conversion >95% is rarely real — usually means the funnel + steps are too lenient (each step almost guaranteed to fire after the + previous) +- Final-step conversion <1% might be a definitional issue — wrong + conversion window, wrong step ordering, or a step that genuinely + shouldn't be in the funnel + +> Flag as: *"Conversion of X% looks [implausibly high / implausibly +> low] — worth sanity-checking the funnel definition."* + +### Step ordering looks wrong + +If the absolute count at step 2 is *higher* than step 1, the funnel is +misconfigured (steps are out of order, or the user did the steps in a +different order than the funnel assumes). + +> Flag as: *"Step counts don't decrease monotonically — step ordering +> may be wrong. Cart should usually come before Checkout."* + +### Cohort divergence + +If a breakdown shows one cohort converting at 60% and another at 5% on +the same funnel, that's the headline finding. The funnel isn't really +"the funnel" — it's two different user experiences. + +> Flag as: *"[Cohort A] converts at X%, [Cohort B] at Y%. The headline +> rate hides a 10x gap between segments."* + +### Time-to-convert anomaly + +If the funnel chart includes time-to-convert distribution, flag if the +median time-to-convert is suspiciously fast (test traffic, bots) or +very slow (might mean conversion window is too generous and counting +unrelated activity). + +--- + +## Common reader pitfalls + +**Reading absolute numbers instead of conversion rates** +"100 users completed checkout" is a volume statement, not a funnel +performance statement. The funnel is about rates. + +**Confusing per-step % with cumulative %** +Each step's drop can be reported as % of previous step or % of entry. +Mixing these gives wrong answers. Always be explicit which one is +being summarized. + +**Mistaking volume change for conversion change** +A funnel can have flat conversion rates but lower entry volume — the +headline metric is the rate, not how many users entered. + +**Conversion window mismatch** +A funnel with a 1-hour window will show worse conversion than the +same funnel with a 7-day window. Make sure the window is appropriate +for the user behavior being measured before flagging the rate as low. + +--- + +## Output focus + +Funnel summary should answer: +- What's the headline conversion rate? +- Where's the biggest drop-off? +- Is the drop-off pattern consistent or has it shifted? + +Skip: +- Reorganizing the steps (that's a build task — out of scope) +- Hypothesis on causes ("the payment page might be slow" — that's a + root-cause investigation, out of scope) diff --git a/plugins/mixpanel-mcp-eu/skills/analyze-report/references/read-insights.md b/plugins/mixpanel-mcp-eu/skills/analyze-report/references/read-insights.md new file mode 100644 index 0000000..9b19407 --- /dev/null +++ b/plugins/mixpanel-mcp-eu/skills/analyze-report/references/read-insights.md @@ -0,0 +1,111 @@ +# Reading Insights charts — reference + +Use this reference when the chart being analyzed is an **Insights** +chart (event volume, trend over time, breakdown, ratio). + +--- + +## What to read first + +1. **Current value** — last point of the series, or total for the + period. State it in the customer's units (events, unique users, + conversion %). + +2. **Trend direction** — is the line up, down, flat, or oscillating? + Compare last 7 days to prior 7 days for short charts, last 30 to + prior 30 for medium charts. + +3. **Magnitude of change** — express as % change, not just direction. + "DAU is up" is weaker than "DAU is up 12% WoW." + +4. **Breakdown distribution** — if the chart has a breakdown, what's + the top segment's share? A breakdown where one segment is 80%+ of + volume is notable on its own (concentration risk or + instrumentation issue). + +--- + +## Patterns to flag + +### Step-change + +A single point where the line jumps or drops and stays at the new +level. Distinct from a gradual trend. Almost always indicates a +deploy, instrumentation change, or external trigger event. + +> Flag as: *"Step-change on [date] — value moved from X to Y and held."* + +### Spike then return + +A single point sharply different, then back to normal. Usually a +campaign, batch event, or test traffic. + +> Flag as: *"Single-day spike on [date], value returned to baseline +> next day. Looks like a one-off."* + +### Drift (trend-level shift) + +The last 30 days are running consistently above or below the prior 30, +without a single step-change point. Slower-moving than a step-change, +harder to spot at a glance. + +> Flag as: *"The last 30 days run ~X% [above/below] the prior period — +> looks like a baseline shift, not a single event."* + +### Going to zero + +A series that drops to zero and stays there is almost never a real +business signal — it's an instrumentation break. SDK update, event +rename, deploy that broke tracking. + +> Flag as: *"Series goes to zero on [date] and stays flat. This usually +> means tracking broke, not that the behavior actually stopped."* + +### Cyclic pattern (weekly seasonality) + +Most user-facing metrics show weekday/weekend cycles. If the chart +spans a few weeks, the cycle should be obvious. Two things to flag: +- Cycle disappears suddenly (something dampened weekend activity) +- Cycle inverts (weekends becoming higher than weekdays) + +### High-cardinality breakdown explosion + +If the breakdown shows hundreds of small segments, the chart is +probably misconfigured (e.g., breaking down by `user_id`). Surface +this as a chart quality issue, not a metric finding. + +--- + +## Common reader pitfalls + +**Mistaking weekend dips for drops** +If the customer is looking at a single recent low point, check if it's +a weekend. The chart isn't broken; it's Tuesday vs. Sunday. + +**Treating ratios like volumes** +A conversion ratio chart can change because the numerator moved OR the +denominator moved. Always state which. + +**Reading the legend wrong** +Multi-series charts: confirm which line the customer is asking about +before analyzing. "The blue one" might be a different segment from +what they think. + +**Comparing different time aggregations** +A chart switching from daily to weekly granularity creates an +artificial "drop" because weekly bins are smaller in the partial last +week. Verify granularity before flagging movement. + +--- + +## Output focus + +Insights summary should answer: +- What's the current level? +- What direction is it moving? +- Is anything unusual happening? + +Skip: +- Methodology ("this is unique users, not events" — only mention if + relevant to the finding) +- Hypothesis on why ("might be because of..." — that's a root-cause investigation, out of scope) diff --git a/plugins/mixpanel-mcp-eu/skills/analyze-report/references/read-retention.md b/plugins/mixpanel-mcp-eu/skills/analyze-report/references/read-retention.md new file mode 100644 index 0000000..a569849 --- /dev/null +++ b/plugins/mixpanel-mcp-eu/skills/analyze-report/references/read-retention.md @@ -0,0 +1,124 @@ +# Reading Retention charts — reference + +Use this reference when the chart being analyzed is a **Retention** +chart (cohort retention triangle, stickiness, DAU/MAU). + +--- + +## What to read first + +1. **Period-1 retention** — what % of cohort returns the period + immediately after birth. This is the steepest drop-off and the most + important number. + +2. **Long-tail retention** — where does the curve flatten? A retention + curve that flattens at 20% means roughly 1-in-5 users become + long-term active. A curve that goes to zero has no durable base. + +3. **Cohort comparison** — are recent cohorts retaining better, worse, + or similar to older cohorts? This is the trend signal — improving + onboarding shows up here. + +4. **Cohort sizes** — note if cohorts are very different sizes, + especially if recent cohorts are small. Small cohorts have noisy + retention. + +--- + +## Patterns to flag + +### Curve doesn't flatten + +A healthy retention curve flattens — losing fewer users each period +because the remaining users are increasingly engaged. If the curve +keeps declining linearly, the product has no "sticky" base. + +> Flag as: *"Curve continues to decline through period [N] without +> flattening — no sign of a durable retained user base."* + +### Flat curve after period 1 + +Sometimes the curve drops sharply in period 1 then is essentially flat +— a small core of users who keep coming back. The headline retention % +might look low, but the *shape* is healthy. + +> Flag as: *"Big drop in period 1, then nearly flat — small but +> durable retained cohort."* + +### Recent cohorts diverging from older cohorts + +If recent cohorts retain noticeably better or worse than older ones, +something changed — onboarding flow, acquisition source mix, or +product changes. Worth flagging clearly. + +> Flag as: *"Cohorts from [recent period] retain ~X% [better/worse] than +> cohorts from [earlier period] — the product or acquisition changed."* + +### Small cohort noise + +If recent cohorts are <100 users per period, retention numbers are +unreliable. Surface this so the customer doesn't read meaning into +noise. + +> Flag as: *"Recent cohorts are small (<100 users/period) — the +> percentages are noisy. Need a longer date range or larger acquisition +> volume for clean numbers."* + +### Impossible retention (>100% or 0%) + +If period-N retention shows >100%, the retention type is bounded vs. +unbounded mismatched, or the same user is being counted multiple times. +Surface as a chart configuration issue, not a finding. + +If period-1 retention is 0% across the board, the return event likely +is the same as the birth event (e.g., signup retention measured against +signup, which by definition only fires once per user). + +### Stickiness (DAU/MAU) anomalies + +For DAU/MAU charts: +- Healthy consumer products: 10–25% +- Healthy B2B products: 30–50% +- >70% almost always means MAU is artificially low (small user base or + short measurement window) +- <5% means daily engagement is rare — flag as low stickiness + +--- + +## Common reader pitfalls + +**Reading retention as engagement** +A user who returns once in week N counts as retained, even if their +engagement is shallow. High retention % doesn't mean high usage. + +**Comparing cohorts across product changes** +If the product changed materially mid-window, comparing pre-change +cohorts to post-change cohorts is comparing two different products. +Surface this if the customer's business context mentions a recent +launch or major change. + +**Confusing retention with churn** +Retention is the inverse of churn, but they're not always perfectly +complementary in Mixpanel. A user "not retained" in week N might +return in week N+1. Don't equate "not retained this week" with "lost +forever." + +**Cohort retention vs. rolling retention** +Mixpanel's native retention is cohort retention (% of birth-week users +who returned in week N). If the customer asks about "30-day retention" +and means rolling retention (% of users active today who were active +30 days ago), the chart might not be answering their question. + +--- + +## Output focus + +Retention summary should answer: +- What's period-1 retention? +- Does the curve flatten, and at what level? +- Are recent cohorts trending better or worse? + +Skip: +- Methodology lectures (only explain bounded vs. unbounded if relevant + to a finding) +- Hypotheses on why retention shifted (that's a root-cause investigation, out of scope) diff --git a/plugins/mixpanel-mcp-in/skills/analyze-report/SKILL.md b/plugins/mixpanel-mcp-in/skills/analyze-report/SKILL.md new file mode 100644 index 0000000..6716944 --- /dev/null +++ b/plugins/mixpanel-mcp-in/skills/analyze-report/SKILL.md @@ -0,0 +1,254 @@ +--- +name: analyze-report +description: > + Read and explain a Mixpanel report or chart — what it shows, what's + notable, and what's worth a closer look. Use whenever the user asks to + interpret, explain, summarize, review, or break down an existing + chart, report, or saved query in Mixpanel. Trigger phrases: + "what does this chart show", "explain this report", "interpret this + chart", "summarize this for me", "what's notable here", "anything + weird in this chart", "tell me what's happening", "review this + insight", "walk me through this report", "what's the takeaway from + this". Also trigger when the user pastes a Mixpanel chart or report + URL and asks anything about it. Lean by default — surfaces what the + report shows and flags notable patterns, but does not chase root + causes. Do NOT trigger for building new charts, reviewing entire + dashboards, or full root-cause diagnostic workflows. Requires Mixpanel MCP. +compatibility: "Requires Mixpanel MCP. Works for any project the user has access to." +--- + +# Mixpanel Analyze Report + +Take a Mixpanel report or chart that already exists (or just got built) +and turn it into a one-screen summary the customer can act on. The skill +is **lean by default** — it explains what the report shows and flags +what's notable, but does not chase root causes unless the customer asks. + +If the customer's follow-up is "why is this happening" or anything +similar, treat that as a deeper root-cause investigation that is out of +scope here. Flag what you see and stop; don't attempt multi-step RCA +inline. This skill is built for fast interpretation. + +--- + +## When this skill runs, it does four things in order + +1. **Locate the report** — by URL, ID, or fresh build +2. **Pull the data** — re-run the query and parse the result +3. **Read the shape** — trend, anomalies, breakdown distribution +4. **Summarize for the customer** — what it shows, what's notable, what to do next + +--- + +## Step 1 — Locate the report + +Three input modes. Detect which one applies from the customer's message: + +### Mode A — Customer provides a URL or chart/report ID + +Most common. Mixpanel report URLs look like +`https://mixpanel.com/project//view//app/` +or include `report_id=`. Extract the ID(s). + +Use the relevant Mixpanel MCP tool to fetch the report's metadata and +configuration — this gives you the events, properties, filters, +breakdowns, date range, and chart type without having to ask the +customer. + +If you can't resolve the URL/ID (404, permission error, malformed URL), +say so plainly and ask if they meant a different report. + +### Mode B — Customer describes the report in natural language + +If the customer says "the DAU chart on my exec board" or "the funnel I +built last week," they're pointing at an existing report but haven't +given an ID. Use `Search-Entities` with `entity_types=['report']` to +find candidates. Show the top 3 matches with their titles and dates, +ask which one. + +If `Search-Entities` returns nothing useful, escalate to Mode C: + +> *"I can't find that report. Want to build it fresh and analyze that?"* + +### Mode C — Customer wants to analyze a report that doesn't exist yet + +The report has to be built before it can be analyzed. Build the chart +first (or ask the customer to point you at the configuration they want), +then come back to Step 2 and analyze the result. Once the chart is +built you'll have a `query_id` and a rendered widget; this skill picks +up from there. + +If the customer asks for both in one turn ("build me a DAU chart and +tell me what it shows"), do them as one workflow: build → analyze → +present together. + +--- + +## Step 2 — Pull the data + +For Mode A or B (existing report), call `Run-Query` with the same +configuration as the saved report to get fresh data. Don't trust cached +chart state — the customer may not have refreshed in days. + +For Mode C, you already have the `query_id` from the just-built chart. + +In both cases, you need: +- The query result data (time series, breakdown values, etc.) +- The chart configuration (events, properties, filters, date range, + chart type) + +Without configuration metadata, the analysis is shallow ("the line +goes up") instead of grounded ("checkout volume rose 18% WoW, isolated +to the iOS platform"). + +--- + +## Step 3 — Read the shape + +What to look for depends on chart type. Read the matching reference: + +- Insights → `references/read-insights.md` +- Funnels → `references/read-funnels.md` +- Retention → `references/read-retention.md` +- Flows → `references/read-flows.md` + +The references hold the **specific patterns** to look for in each +chart type. The high-level rules across all types: + +### What to surface (always) + +- **The current value** — what the metric is right now +- **Direction and magnitude of change** — is it up/down/flat, by how + much, vs. when +- **The biggest contributor** — if there's a breakdown, which segment + drives the volume + +### What to flag (only if present) + +- **Step-change anomalies** — a single point that breaks the pattern +- **Sustained drift** — the baseline has shifted (last 30 days look + different from prior 30 days) +- **Suspicious-looking segments** — one segment doing all the work, or + a segment that suddenly disappeared +- **Data quality cues** — a sudden jump that aligns with a deploy, an + event going to zero (looks like instrumentation broke) + +### What NOT to do + +- **Don't chase root cause.** If you spot a drop, flag it and stop. + Attributing the movement to a specific cause is a separate, deeper + workflow. +- **Don't speculate about external causes.** Saying "this might be + because of holiday traffic" without evidence is hallucination. +- **Don't recommend fixes.** The customer didn't ask for fixes. They + asked what the report shows. + +--- + +## Step 4 — Summarize for the customer + +Output structure (always this shape, length scales with content): + +``` +**What this shows** +[1–2 sentences: report subject, time window, current value] + +**The shape** +[1–3 sentences: trend direction, magnitude, key inflection points] + +**Worth noting** +[Bullet list — only items that meet the "flag" bar above. Skip if +nothing notable.] + +**Want to dig in?** +[Offer to either: (a) investigate why the movement happened, OR +(b) recut the report with a different breakdown, filter, or date range +if that would help] +``` + +Example output for a DAU chart that dipped: + +``` +**What this shows** +Daily Active Users over the last 30 days. Currently at 142K DAU. + +**The shape** +Flat through most of the month, with a clear step-down on March 18th +— DAU dropped from ~150K to ~135K and hasn't recovered. The post-drop +baseline is roughly 9% below the pre-drop average. + +**Worth noting** +- The drop is a step-change, not a gradual decline — typical of a + deploy, instrumentation change, or external event. +- Weekend dips are still present at the same magnitude — the issue + isn't a day-of-week shift. + +**Want to dig in?** +The shape suggests a single trigger event around March 18th. Want me +to dig into which segments are driving the drop? +``` + +Keep it tight. A customer reading this on a phone needs to get the +takeaway in the first paragraph. + +--- + +## Hybrid scope — when to stop + +Lean by default means: surface what's there, stop. The boundary is the +"why" question. If the customer asks any of: + +- "Why did this drop / spike / change?" +- "What's causing this?" +- "Where is it coming from?" +- "Is it specific users / regions / platforms?" + +…that's a root-cause investigation, which is a deeper, multi-step +workflow. Don't try to answer it inline here. Flag what the data shows +and offer the deeper dig as an explicit next step: + +> *"That's a root-cause question — it can take a few cuts to answer +> properly. Want me to dig into the segments driving this?"* + +Do not silently expand the analysis. An unbounded "why" question turns +a 30-second summary into a 10-minute investigation. Better to make the +boundary explicit and let the customer opt in. + +--- + +## Hard rules + +- **Always re-run the query.** Don't trust cached chart state. +- **Configuration metadata grounds the analysis.** Without knowing the + events/filters, you can't tell the customer what they're looking at. +- **Flag, don't diagnose.** Drift detection ≠ root cause. +- **One screen of output.** Long analyses lose the customer. +- **Make "why" an explicit next step.** Don't RCA inline. +- **No speculation about external causes.** Stick to what the data + shows. + +--- + +## Quick reference — MCP tools used + +| Step | Tool | +|---|---| +| 1 | `Get-Report` (for URL/ID), `Search-Entities` (for NL search) | +| 1, Mode C | build the chart first, then come back with the `query_id` | +| 2 | `Run-Query` | +| 3 | (no new tool calls — pure analysis on the data already pulled) | +| 4 | (output to user) | + +For chart-type-specific reading patterns, see `references/`. + +--- + +## When to stop and redirect + +- Customer asks "why" → that's a root-cause investigation; flag and + offer it as a deeper next step, don't do it inline +- Customer wants to modify or rebuild the chart → that's a build task, + out of scope for interpretation +- Customer wants to analyze the whole dashboard → out of scope; this + skill reads a single report +- Customer wants to clean up or manage old charts → out of scope diff --git a/plugins/mixpanel-mcp-in/skills/analyze-report/references/read-flows.md b/plugins/mixpanel-mcp-in/skills/analyze-report/references/read-flows.md new file mode 100644 index 0000000..a157cc0 --- /dev/null +++ b/plugins/mixpanel-mcp-in/skills/analyze-report/references/read-flows.md @@ -0,0 +1,116 @@ +# Reading Flow charts — reference + +Use this reference when the chart being analyzed is a **Flow** (Sankey +showing event-to-event transitions before or after an anchor event). + +--- + +## What to read first + +1. **Anchor event volume** — how many users / events feed the anchor. + This is the denominator for everything downstream. + +2. **Top 1–3 paths** — what's the most common next event (or previous + event, for backward flows)? What % of users go that way? + +3. **Long tail** — how concentrated is the flow? If the top 3 paths + account for 80% of users, the flow has clear dominant patterns. If + the top 3 paths only account for 30%, the flow is fragmented. + +4. **Drop-off branch** — in forward flows, where do users *exit* the + product? In backward flows, where do they *enter* from? + +--- + +## Patterns to flag + +### Highly concentrated flow + +If one path accounts for >70% of post-anchor activity, that path is +the de facto product behavior. Flag it as the dominant pattern. + +> Flag as: *"After [anchor], [%] of users go to [next event] — that's +> the dominant path. Other branches are minor."* + +### Highly fragmented flow + +If the top 3 paths account for <40% combined, users do many different +things. This is either a power-user product (variety is healthy) or a +confusing UX (users don't know what to do next). + +> Flag as: *"Flow is fragmented — top 3 paths account for only [%] +> combined. Either deep variety in user behavior, or unclear next-step +> guidance."* + +### High drop-off branch in forward flow + +A "drop-off" or "session end" branch claiming a large share is the +flow chart's version of a funnel drop-off. Flag if it's a meaningful +share (e.g., >30% drop off immediately after the anchor). + +> Flag as: *"[%] of users drop off immediately after [anchor] — they +> don't proceed to any tracked event. Worth investigating where they +> go."* + +### Unexpected next event + +If the customer's mental model is "users do A → B" but the flow shows +"users do A → C", flag the surprise. The mental model and the data +disagree. + +> Flag as: *"Most users go to [unexpected event] after [anchor] — +> [expected event] is only [%]. The flow's not what you might +> intuitively expect."* + +### Backward flow showing unexpected sources + +If the customer is looking at "what leads to [event]" and the top +preceding event is a generic event (Page View, App Open) rather than +a meaningful action, the flow isn't very informative. Suggest a +deeper backward flow or filter out generic events. + +### Loops or repeating events + +If the flow shows the same event repeating (e.g., Page View → Page +View → Page View), the chart needs a filter on a property to +differentiate (which page?). Flag as a chart configuration issue. + +--- + +## Common reader pitfalls + +**Confusing share % with conversion %** +A flow showing "30% of users go to checkout after cart" is not the +same as "30% of cart-add events convert." The flow share is users who +did *that next event*, not conversion through a defined funnel. + +**Reading flows as session-bounded when they're not** +Mixpanel flows aren't strictly session-bounded — events from different +sessions hours or days apart can appear in the same flow. If the +customer is asking about within-session behavior, flag this caveat. + +**Treating the anchor as a starting point when it isn't** +Flows can be anchored anywhere, not just on entry events. If the +customer says "user journey from signup" and the chart anchors on a +mid-funnel event, the data isn't answering the question they asked. + +**Depth too shallow or too deep** +Depth-1 flows show only one next event — useful for "what's the +immediate next action" but not for path analysis. Depth-5+ flows are +visually noisy. If the chart depth doesn't match the question, surface +that. + +--- + +## Output focus + +Flow summary should answer: +- What's the dominant path? +- How concentrated is the behavior? +- What surprises (unexpected next/prior events, big drop-offs)? + +Skip: +- Speculating on UX changes ("maybe the checkout button is + hidden" — out of scope) +- Hypotheses on why users drop where they do (that's a root-cause + investigation, out of scope) diff --git a/plugins/mixpanel-mcp-in/skills/analyze-report/references/read-funnels.md b/plugins/mixpanel-mcp-in/skills/analyze-report/references/read-funnels.md new file mode 100644 index 0000000..115b83b --- /dev/null +++ b/plugins/mixpanel-mcp-in/skills/analyze-report/references/read-funnels.md @@ -0,0 +1,117 @@ +# Reading Funnel charts — reference + +Use this reference when the chart being analyzed is a **Funnel**. + +--- + +## What to read first + +1. **Top-line conversion rate** — entry to final step. State as a %. + +2. **Where the biggest drop-off is** — identify the step with the + largest absolute % drop, not the largest absolute user drop. (A + step that loses 50% of 100 users matters more than one that loses + 5% of 1M users when you're talking about conversion quality.) + +3. **Trend over time** — if the funnel is shown as a time series + (conversion % over weeks/days), is it improving or degrading? + +4. **Cohort segments** — if the funnel has a breakdown (by source, + plan, platform), which segment converts best? Worst? + +--- + +## Patterns to flag + +### Surprising step where users drop + +Funnels are intuitive when drop-off is concentrated at known friction +points (e.g., payment step). Flag when it's not — when users drop at +an unexpected step. + +> Flag as: *"Most drop-off is at [step] — usually I'd expect [other +> step] to be the friction point. Worth checking if something changed +> on that page."* + +### Conversion rate collapse + +If the headline conversion rate dropped sharply over the time series, +identify which step caused it. The drop is rarely uniform — usually +one step regressed. + +> Flag as: *"Conversion fell from X% to Y% over the window — the +> regression is concentrated at the [step] step."* + +### Conversion rate looks too high or too low + +Some patterns are physically suspicious: +- Final-step conversion >95% is rarely real — usually means the funnel + steps are too lenient (each step almost guaranteed to fire after the + previous) +- Final-step conversion <1% might be a definitional issue — wrong + conversion window, wrong step ordering, or a step that genuinely + shouldn't be in the funnel + +> Flag as: *"Conversion of X% looks [implausibly high / implausibly +> low] — worth sanity-checking the funnel definition."* + +### Step ordering looks wrong + +If the absolute count at step 2 is *higher* than step 1, the funnel is +misconfigured (steps are out of order, or the user did the steps in a +different order than the funnel assumes). + +> Flag as: *"Step counts don't decrease monotonically — step ordering +> may be wrong. Cart should usually come before Checkout."* + +### Cohort divergence + +If a breakdown shows one cohort converting at 60% and another at 5% on +the same funnel, that's the headline finding. The funnel isn't really +"the funnel" — it's two different user experiences. + +> Flag as: *"[Cohort A] converts at X%, [Cohort B] at Y%. The headline +> rate hides a 10x gap between segments."* + +### Time-to-convert anomaly + +If the funnel chart includes time-to-convert distribution, flag if the +median time-to-convert is suspiciously fast (test traffic, bots) or +very slow (might mean conversion window is too generous and counting +unrelated activity). + +--- + +## Common reader pitfalls + +**Reading absolute numbers instead of conversion rates** +"100 users completed checkout" is a volume statement, not a funnel +performance statement. The funnel is about rates. + +**Confusing per-step % with cumulative %** +Each step's drop can be reported as % of previous step or % of entry. +Mixing these gives wrong answers. Always be explicit which one is +being summarized. + +**Mistaking volume change for conversion change** +A funnel can have flat conversion rates but lower entry volume — the +headline metric is the rate, not how many users entered. + +**Conversion window mismatch** +A funnel with a 1-hour window will show worse conversion than the +same funnel with a 7-day window. Make sure the window is appropriate +for the user behavior being measured before flagging the rate as low. + +--- + +## Output focus + +Funnel summary should answer: +- What's the headline conversion rate? +- Where's the biggest drop-off? +- Is the drop-off pattern consistent or has it shifted? + +Skip: +- Reorganizing the steps (that's a build task — out of scope) +- Hypothesis on causes ("the payment page might be slow" — that's a + root-cause investigation, out of scope) diff --git a/plugins/mixpanel-mcp-in/skills/analyze-report/references/read-insights.md b/plugins/mixpanel-mcp-in/skills/analyze-report/references/read-insights.md new file mode 100644 index 0000000..9b19407 --- /dev/null +++ b/plugins/mixpanel-mcp-in/skills/analyze-report/references/read-insights.md @@ -0,0 +1,111 @@ +# Reading Insights charts — reference + +Use this reference when the chart being analyzed is an **Insights** +chart (event volume, trend over time, breakdown, ratio). + +--- + +## What to read first + +1. **Current value** — last point of the series, or total for the + period. State it in the customer's units (events, unique users, + conversion %). + +2. **Trend direction** — is the line up, down, flat, or oscillating? + Compare last 7 days to prior 7 days for short charts, last 30 to + prior 30 for medium charts. + +3. **Magnitude of change** — express as % change, not just direction. + "DAU is up" is weaker than "DAU is up 12% WoW." + +4. **Breakdown distribution** — if the chart has a breakdown, what's + the top segment's share? A breakdown where one segment is 80%+ of + volume is notable on its own (concentration risk or + instrumentation issue). + +--- + +## Patterns to flag + +### Step-change + +A single point where the line jumps or drops and stays at the new +level. Distinct from a gradual trend. Almost always indicates a +deploy, instrumentation change, or external trigger event. + +> Flag as: *"Step-change on [date] — value moved from X to Y and held."* + +### Spike then return + +A single point sharply different, then back to normal. Usually a +campaign, batch event, or test traffic. + +> Flag as: *"Single-day spike on [date], value returned to baseline +> next day. Looks like a one-off."* + +### Drift (trend-level shift) + +The last 30 days are running consistently above or below the prior 30, +without a single step-change point. Slower-moving than a step-change, +harder to spot at a glance. + +> Flag as: *"The last 30 days run ~X% [above/below] the prior period — +> looks like a baseline shift, not a single event."* + +### Going to zero + +A series that drops to zero and stays there is almost never a real +business signal — it's an instrumentation break. SDK update, event +rename, deploy that broke tracking. + +> Flag as: *"Series goes to zero on [date] and stays flat. This usually +> means tracking broke, not that the behavior actually stopped."* + +### Cyclic pattern (weekly seasonality) + +Most user-facing metrics show weekday/weekend cycles. If the chart +spans a few weeks, the cycle should be obvious. Two things to flag: +- Cycle disappears suddenly (something dampened weekend activity) +- Cycle inverts (weekends becoming higher than weekdays) + +### High-cardinality breakdown explosion + +If the breakdown shows hundreds of small segments, the chart is +probably misconfigured (e.g., breaking down by `user_id`). Surface +this as a chart quality issue, not a metric finding. + +--- + +## Common reader pitfalls + +**Mistaking weekend dips for drops** +If the customer is looking at a single recent low point, check if it's +a weekend. The chart isn't broken; it's Tuesday vs. Sunday. + +**Treating ratios like volumes** +A conversion ratio chart can change because the numerator moved OR the +denominator moved. Always state which. + +**Reading the legend wrong** +Multi-series charts: confirm which line the customer is asking about +before analyzing. "The blue one" might be a different segment from +what they think. + +**Comparing different time aggregations** +A chart switching from daily to weekly granularity creates an +artificial "drop" because weekly bins are smaller in the partial last +week. Verify granularity before flagging movement. + +--- + +## Output focus + +Insights summary should answer: +- What's the current level? +- What direction is it moving? +- Is anything unusual happening? + +Skip: +- Methodology ("this is unique users, not events" — only mention if + relevant to the finding) +- Hypothesis on why ("might be because of..." — that's a root-cause investigation, out of scope) diff --git a/plugins/mixpanel-mcp-in/skills/analyze-report/references/read-retention.md b/plugins/mixpanel-mcp-in/skills/analyze-report/references/read-retention.md new file mode 100644 index 0000000..a569849 --- /dev/null +++ b/plugins/mixpanel-mcp-in/skills/analyze-report/references/read-retention.md @@ -0,0 +1,124 @@ +# Reading Retention charts — reference + +Use this reference when the chart being analyzed is a **Retention** +chart (cohort retention triangle, stickiness, DAU/MAU). + +--- + +## What to read first + +1. **Period-1 retention** — what % of cohort returns the period + immediately after birth. This is the steepest drop-off and the most + important number. + +2. **Long-tail retention** — where does the curve flatten? A retention + curve that flattens at 20% means roughly 1-in-5 users become + long-term active. A curve that goes to zero has no durable base. + +3. **Cohort comparison** — are recent cohorts retaining better, worse, + or similar to older cohorts? This is the trend signal — improving + onboarding shows up here. + +4. **Cohort sizes** — note if cohorts are very different sizes, + especially if recent cohorts are small. Small cohorts have noisy + retention. + +--- + +## Patterns to flag + +### Curve doesn't flatten + +A healthy retention curve flattens — losing fewer users each period +because the remaining users are increasingly engaged. If the curve +keeps declining linearly, the product has no "sticky" base. + +> Flag as: *"Curve continues to decline through period [N] without +> flattening — no sign of a durable retained user base."* + +### Flat curve after period 1 + +Sometimes the curve drops sharply in period 1 then is essentially flat +— a small core of users who keep coming back. The headline retention % +might look low, but the *shape* is healthy. + +> Flag as: *"Big drop in period 1, then nearly flat — small but +> durable retained cohort."* + +### Recent cohorts diverging from older cohorts + +If recent cohorts retain noticeably better or worse than older ones, +something changed — onboarding flow, acquisition source mix, or +product changes. Worth flagging clearly. + +> Flag as: *"Cohorts from [recent period] retain ~X% [better/worse] than +> cohorts from [earlier period] — the product or acquisition changed."* + +### Small cohort noise + +If recent cohorts are <100 users per period, retention numbers are +unreliable. Surface this so the customer doesn't read meaning into +noise. + +> Flag as: *"Recent cohorts are small (<100 users/period) — the +> percentages are noisy. Need a longer date range or larger acquisition +> volume for clean numbers."* + +### Impossible retention (>100% or 0%) + +If period-N retention shows >100%, the retention type is bounded vs. +unbounded mismatched, or the same user is being counted multiple times. +Surface as a chart configuration issue, not a finding. + +If period-1 retention is 0% across the board, the return event likely +is the same as the birth event (e.g., signup retention measured against +signup, which by definition only fires once per user). + +### Stickiness (DAU/MAU) anomalies + +For DAU/MAU charts: +- Healthy consumer products: 10–25% +- Healthy B2B products: 30–50% +- >70% almost always means MAU is artificially low (small user base or + short measurement window) +- <5% means daily engagement is rare — flag as low stickiness + +--- + +## Common reader pitfalls + +**Reading retention as engagement** +A user who returns once in week N counts as retained, even if their +engagement is shallow. High retention % doesn't mean high usage. + +**Comparing cohorts across product changes** +If the product changed materially mid-window, comparing pre-change +cohorts to post-change cohorts is comparing two different products. +Surface this if the customer's business context mentions a recent +launch or major change. + +**Confusing retention with churn** +Retention is the inverse of churn, but they're not always perfectly +complementary in Mixpanel. A user "not retained" in week N might +return in week N+1. Don't equate "not retained this week" with "lost +forever." + +**Cohort retention vs. rolling retention** +Mixpanel's native retention is cohort retention (% of birth-week users +who returned in week N). If the customer asks about "30-day retention" +and means rolling retention (% of users active today who were active +30 days ago), the chart might not be answering their question. + +--- + +## Output focus + +Retention summary should answer: +- What's period-1 retention? +- Does the curve flatten, and at what level? +- Are recent cohorts trending better or worse? + +Skip: +- Methodology lectures (only explain bounded vs. unbounded if relevant + to a finding) +- Hypotheses on why retention shifted (that's a root-cause investigation, out of scope) diff --git a/plugins/mixpanel-mcp/skills/analyze-report/SKILL.md b/plugins/mixpanel-mcp/skills/analyze-report/SKILL.md new file mode 100644 index 0000000..6716944 --- /dev/null +++ b/plugins/mixpanel-mcp/skills/analyze-report/SKILL.md @@ -0,0 +1,254 @@ +--- +name: analyze-report +description: > + Read and explain a Mixpanel report or chart — what it shows, what's + notable, and what's worth a closer look. Use whenever the user asks to + interpret, explain, summarize, review, or break down an existing + chart, report, or saved query in Mixpanel. Trigger phrases: + "what does this chart show", "explain this report", "interpret this + chart", "summarize this for me", "what's notable here", "anything + weird in this chart", "tell me what's happening", "review this + insight", "walk me through this report", "what's the takeaway from + this". Also trigger when the user pastes a Mixpanel chart or report + URL and asks anything about it. Lean by default — surfaces what the + report shows and flags notable patterns, but does not chase root + causes. Do NOT trigger for building new charts, reviewing entire + dashboards, or full root-cause diagnostic workflows. Requires Mixpanel MCP. +compatibility: "Requires Mixpanel MCP. Works for any project the user has access to." +--- + +# Mixpanel Analyze Report + +Take a Mixpanel report or chart that already exists (or just got built) +and turn it into a one-screen summary the customer can act on. The skill +is **lean by default** — it explains what the report shows and flags +what's notable, but does not chase root causes unless the customer asks. + +If the customer's follow-up is "why is this happening" or anything +similar, treat that as a deeper root-cause investigation that is out of +scope here. Flag what you see and stop; don't attempt multi-step RCA +inline. This skill is built for fast interpretation. + +--- + +## When this skill runs, it does four things in order + +1. **Locate the report** — by URL, ID, or fresh build +2. **Pull the data** — re-run the query and parse the result +3. **Read the shape** — trend, anomalies, breakdown distribution +4. **Summarize for the customer** — what it shows, what's notable, what to do next + +--- + +## Step 1 — Locate the report + +Three input modes. Detect which one applies from the customer's message: + +### Mode A — Customer provides a URL or chart/report ID + +Most common. Mixpanel report URLs look like +`https://mixpanel.com/project//view//app/` +or include `report_id=`. Extract the ID(s). + +Use the relevant Mixpanel MCP tool to fetch the report's metadata and +configuration — this gives you the events, properties, filters, +breakdowns, date range, and chart type without having to ask the +customer. + +If you can't resolve the URL/ID (404, permission error, malformed URL), +say so plainly and ask if they meant a different report. + +### Mode B — Customer describes the report in natural language + +If the customer says "the DAU chart on my exec board" or "the funnel I +built last week," they're pointing at an existing report but haven't +given an ID. Use `Search-Entities` with `entity_types=['report']` to +find candidates. Show the top 3 matches with their titles and dates, +ask which one. + +If `Search-Entities` returns nothing useful, escalate to Mode C: + +> *"I can't find that report. Want to build it fresh and analyze that?"* + +### Mode C — Customer wants to analyze a report that doesn't exist yet + +The report has to be built before it can be analyzed. Build the chart +first (or ask the customer to point you at the configuration they want), +then come back to Step 2 and analyze the result. Once the chart is +built you'll have a `query_id` and a rendered widget; this skill picks +up from there. + +If the customer asks for both in one turn ("build me a DAU chart and +tell me what it shows"), do them as one workflow: build → analyze → +present together. + +--- + +## Step 2 — Pull the data + +For Mode A or B (existing report), call `Run-Query` with the same +configuration as the saved report to get fresh data. Don't trust cached +chart state — the customer may not have refreshed in days. + +For Mode C, you already have the `query_id` from the just-built chart. + +In both cases, you need: +- The query result data (time series, breakdown values, etc.) +- The chart configuration (events, properties, filters, date range, + chart type) + +Without configuration metadata, the analysis is shallow ("the line +goes up") instead of grounded ("checkout volume rose 18% WoW, isolated +to the iOS platform"). + +--- + +## Step 3 — Read the shape + +What to look for depends on chart type. Read the matching reference: + +- Insights → `references/read-insights.md` +- Funnels → `references/read-funnels.md` +- Retention → `references/read-retention.md` +- Flows → `references/read-flows.md` + +The references hold the **specific patterns** to look for in each +chart type. The high-level rules across all types: + +### What to surface (always) + +- **The current value** — what the metric is right now +- **Direction and magnitude of change** — is it up/down/flat, by how + much, vs. when +- **The biggest contributor** — if there's a breakdown, which segment + drives the volume + +### What to flag (only if present) + +- **Step-change anomalies** — a single point that breaks the pattern +- **Sustained drift** — the baseline has shifted (last 30 days look + different from prior 30 days) +- **Suspicious-looking segments** — one segment doing all the work, or + a segment that suddenly disappeared +- **Data quality cues** — a sudden jump that aligns with a deploy, an + event going to zero (looks like instrumentation broke) + +### What NOT to do + +- **Don't chase root cause.** If you spot a drop, flag it and stop. + Attributing the movement to a specific cause is a separate, deeper + workflow. +- **Don't speculate about external causes.** Saying "this might be + because of holiday traffic" without evidence is hallucination. +- **Don't recommend fixes.** The customer didn't ask for fixes. They + asked what the report shows. + +--- + +## Step 4 — Summarize for the customer + +Output structure (always this shape, length scales with content): + +``` +**What this shows** +[1–2 sentences: report subject, time window, current value] + +**The shape** +[1–3 sentences: trend direction, magnitude, key inflection points] + +**Worth noting** +[Bullet list — only items that meet the "flag" bar above. Skip if +nothing notable.] + +**Want to dig in?** +[Offer to either: (a) investigate why the movement happened, OR +(b) recut the report with a different breakdown, filter, or date range +if that would help] +``` + +Example output for a DAU chart that dipped: + +``` +**What this shows** +Daily Active Users over the last 30 days. Currently at 142K DAU. + +**The shape** +Flat through most of the month, with a clear step-down on March 18th +— DAU dropped from ~150K to ~135K and hasn't recovered. The post-drop +baseline is roughly 9% below the pre-drop average. + +**Worth noting** +- The drop is a step-change, not a gradual decline — typical of a + deploy, instrumentation change, or external event. +- Weekend dips are still present at the same magnitude — the issue + isn't a day-of-week shift. + +**Want to dig in?** +The shape suggests a single trigger event around March 18th. Want me +to dig into which segments are driving the drop? +``` + +Keep it tight. A customer reading this on a phone needs to get the +takeaway in the first paragraph. + +--- + +## Hybrid scope — when to stop + +Lean by default means: surface what's there, stop. The boundary is the +"why" question. If the customer asks any of: + +- "Why did this drop / spike / change?" +- "What's causing this?" +- "Where is it coming from?" +- "Is it specific users / regions / platforms?" + +…that's a root-cause investigation, which is a deeper, multi-step +workflow. Don't try to answer it inline here. Flag what the data shows +and offer the deeper dig as an explicit next step: + +> *"That's a root-cause question — it can take a few cuts to answer +> properly. Want me to dig into the segments driving this?"* + +Do not silently expand the analysis. An unbounded "why" question turns +a 30-second summary into a 10-minute investigation. Better to make the +boundary explicit and let the customer opt in. + +--- + +## Hard rules + +- **Always re-run the query.** Don't trust cached chart state. +- **Configuration metadata grounds the analysis.** Without knowing the + events/filters, you can't tell the customer what they're looking at. +- **Flag, don't diagnose.** Drift detection ≠ root cause. +- **One screen of output.** Long analyses lose the customer. +- **Make "why" an explicit next step.** Don't RCA inline. +- **No speculation about external causes.** Stick to what the data + shows. + +--- + +## Quick reference — MCP tools used + +| Step | Tool | +|---|---| +| 1 | `Get-Report` (for URL/ID), `Search-Entities` (for NL search) | +| 1, Mode C | build the chart first, then come back with the `query_id` | +| 2 | `Run-Query` | +| 3 | (no new tool calls — pure analysis on the data already pulled) | +| 4 | (output to user) | + +For chart-type-specific reading patterns, see `references/`. + +--- + +## When to stop and redirect + +- Customer asks "why" → that's a root-cause investigation; flag and + offer it as a deeper next step, don't do it inline +- Customer wants to modify or rebuild the chart → that's a build task, + out of scope for interpretation +- Customer wants to analyze the whole dashboard → out of scope; this + skill reads a single report +- Customer wants to clean up or manage old charts → out of scope diff --git a/plugins/mixpanel-mcp/skills/analyze-report/references/read-flows.md b/plugins/mixpanel-mcp/skills/analyze-report/references/read-flows.md new file mode 100644 index 0000000..a157cc0 --- /dev/null +++ b/plugins/mixpanel-mcp/skills/analyze-report/references/read-flows.md @@ -0,0 +1,116 @@ +# Reading Flow charts — reference + +Use this reference when the chart being analyzed is a **Flow** (Sankey +showing event-to-event transitions before or after an anchor event). + +--- + +## What to read first + +1. **Anchor event volume** — how many users / events feed the anchor. + This is the denominator for everything downstream. + +2. **Top 1–3 paths** — what's the most common next event (or previous + event, for backward flows)? What % of users go that way? + +3. **Long tail** — how concentrated is the flow? If the top 3 paths + account for 80% of users, the flow has clear dominant patterns. If + the top 3 paths only account for 30%, the flow is fragmented. + +4. **Drop-off branch** — in forward flows, where do users *exit* the + product? In backward flows, where do they *enter* from? + +--- + +## Patterns to flag + +### Highly concentrated flow + +If one path accounts for >70% of post-anchor activity, that path is +the de facto product behavior. Flag it as the dominant pattern. + +> Flag as: *"After [anchor], [%] of users go to [next event] — that's +> the dominant path. Other branches are minor."* + +### Highly fragmented flow + +If the top 3 paths account for <40% combined, users do many different +things. This is either a power-user product (variety is healthy) or a +confusing UX (users don't know what to do next). + +> Flag as: *"Flow is fragmented — top 3 paths account for only [%] +> combined. Either deep variety in user behavior, or unclear next-step +> guidance."* + +### High drop-off branch in forward flow + +A "drop-off" or "session end" branch claiming a large share is the +flow chart's version of a funnel drop-off. Flag if it's a meaningful +share (e.g., >30% drop off immediately after the anchor). + +> Flag as: *"[%] of users drop off immediately after [anchor] — they +> don't proceed to any tracked event. Worth investigating where they +> go."* + +### Unexpected next event + +If the customer's mental model is "users do A → B" but the flow shows +"users do A → C", flag the surprise. The mental model and the data +disagree. + +> Flag as: *"Most users go to [unexpected event] after [anchor] — +> [expected event] is only [%]. The flow's not what you might +> intuitively expect."* + +### Backward flow showing unexpected sources + +If the customer is looking at "what leads to [event]" and the top +preceding event is a generic event (Page View, App Open) rather than +a meaningful action, the flow isn't very informative. Suggest a +deeper backward flow or filter out generic events. + +### Loops or repeating events + +If the flow shows the same event repeating (e.g., Page View → Page +View → Page View), the chart needs a filter on a property to +differentiate (which page?). Flag as a chart configuration issue. + +--- + +## Common reader pitfalls + +**Confusing share % with conversion %** +A flow showing "30% of users go to checkout after cart" is not the +same as "30% of cart-add events convert." The flow share is users who +did *that next event*, not conversion through a defined funnel. + +**Reading flows as session-bounded when they're not** +Mixpanel flows aren't strictly session-bounded — events from different +sessions hours or days apart can appear in the same flow. If the +customer is asking about within-session behavior, flag this caveat. + +**Treating the anchor as a starting point when it isn't** +Flows can be anchored anywhere, not just on entry events. If the +customer says "user journey from signup" and the chart anchors on a +mid-funnel event, the data isn't answering the question they asked. + +**Depth too shallow or too deep** +Depth-1 flows show only one next event — useful for "what's the +immediate next action" but not for path analysis. Depth-5+ flows are +visually noisy. If the chart depth doesn't match the question, surface +that. + +--- + +## Output focus + +Flow summary should answer: +- What's the dominant path? +- How concentrated is the behavior? +- What surprises (unexpected next/prior events, big drop-offs)? + +Skip: +- Speculating on UX changes ("maybe the checkout button is + hidden" — out of scope) +- Hypotheses on why users drop where they do (that's a root-cause + investigation, out of scope) diff --git a/plugins/mixpanel-mcp/skills/analyze-report/references/read-funnels.md b/plugins/mixpanel-mcp/skills/analyze-report/references/read-funnels.md new file mode 100644 index 0000000..115b83b --- /dev/null +++ b/plugins/mixpanel-mcp/skills/analyze-report/references/read-funnels.md @@ -0,0 +1,117 @@ +# Reading Funnel charts — reference + +Use this reference when the chart being analyzed is a **Funnel**. + +--- + +## What to read first + +1. **Top-line conversion rate** — entry to final step. State as a %. + +2. **Where the biggest drop-off is** — identify the step with the + largest absolute % drop, not the largest absolute user drop. (A + step that loses 50% of 100 users matters more than one that loses + 5% of 1M users when you're talking about conversion quality.) + +3. **Trend over time** — if the funnel is shown as a time series + (conversion % over weeks/days), is it improving or degrading? + +4. **Cohort segments** — if the funnel has a breakdown (by source, + plan, platform), which segment converts best? Worst? + +--- + +## Patterns to flag + +### Surprising step where users drop + +Funnels are intuitive when drop-off is concentrated at known friction +points (e.g., payment step). Flag when it's not — when users drop at +an unexpected step. + +> Flag as: *"Most drop-off is at [step] — usually I'd expect [other +> step] to be the friction point. Worth checking if something changed +> on that page."* + +### Conversion rate collapse + +If the headline conversion rate dropped sharply over the time series, +identify which step caused it. The drop is rarely uniform — usually +one step regressed. + +> Flag as: *"Conversion fell from X% to Y% over the window — the +> regression is concentrated at the [step] step."* + +### Conversion rate looks too high or too low + +Some patterns are physically suspicious: +- Final-step conversion >95% is rarely real — usually means the funnel + steps are too lenient (each step almost guaranteed to fire after the + previous) +- Final-step conversion <1% might be a definitional issue — wrong + conversion window, wrong step ordering, or a step that genuinely + shouldn't be in the funnel + +> Flag as: *"Conversion of X% looks [implausibly high / implausibly +> low] — worth sanity-checking the funnel definition."* + +### Step ordering looks wrong + +If the absolute count at step 2 is *higher* than step 1, the funnel is +misconfigured (steps are out of order, or the user did the steps in a +different order than the funnel assumes). + +> Flag as: *"Step counts don't decrease monotonically — step ordering +> may be wrong. Cart should usually come before Checkout."* + +### Cohort divergence + +If a breakdown shows one cohort converting at 60% and another at 5% on +the same funnel, that's the headline finding. The funnel isn't really +"the funnel" — it's two different user experiences. + +> Flag as: *"[Cohort A] converts at X%, [Cohort B] at Y%. The headline +> rate hides a 10x gap between segments."* + +### Time-to-convert anomaly + +If the funnel chart includes time-to-convert distribution, flag if the +median time-to-convert is suspiciously fast (test traffic, bots) or +very slow (might mean conversion window is too generous and counting +unrelated activity). + +--- + +## Common reader pitfalls + +**Reading absolute numbers instead of conversion rates** +"100 users completed checkout" is a volume statement, not a funnel +performance statement. The funnel is about rates. + +**Confusing per-step % with cumulative %** +Each step's drop can be reported as % of previous step or % of entry. +Mixing these gives wrong answers. Always be explicit which one is +being summarized. + +**Mistaking volume change for conversion change** +A funnel can have flat conversion rates but lower entry volume — the +headline metric is the rate, not how many users entered. + +**Conversion window mismatch** +A funnel with a 1-hour window will show worse conversion than the +same funnel with a 7-day window. Make sure the window is appropriate +for the user behavior being measured before flagging the rate as low. + +--- + +## Output focus + +Funnel summary should answer: +- What's the headline conversion rate? +- Where's the biggest drop-off? +- Is the drop-off pattern consistent or has it shifted? + +Skip: +- Reorganizing the steps (that's a build task — out of scope) +- Hypothesis on causes ("the payment page might be slow" — that's a + root-cause investigation, out of scope) diff --git a/plugins/mixpanel-mcp/skills/analyze-report/references/read-insights.md b/plugins/mixpanel-mcp/skills/analyze-report/references/read-insights.md new file mode 100644 index 0000000..9b19407 --- /dev/null +++ b/plugins/mixpanel-mcp/skills/analyze-report/references/read-insights.md @@ -0,0 +1,111 @@ +# Reading Insights charts — reference + +Use this reference when the chart being analyzed is an **Insights** +chart (event volume, trend over time, breakdown, ratio). + +--- + +## What to read first + +1. **Current value** — last point of the series, or total for the + period. State it in the customer's units (events, unique users, + conversion %). + +2. **Trend direction** — is the line up, down, flat, or oscillating? + Compare last 7 days to prior 7 days for short charts, last 30 to + prior 30 for medium charts. + +3. **Magnitude of change** — express as % change, not just direction. + "DAU is up" is weaker than "DAU is up 12% WoW." + +4. **Breakdown distribution** — if the chart has a breakdown, what's + the top segment's share? A breakdown where one segment is 80%+ of + volume is notable on its own (concentration risk or + instrumentation issue). + +--- + +## Patterns to flag + +### Step-change + +A single point where the line jumps or drops and stays at the new +level. Distinct from a gradual trend. Almost always indicates a +deploy, instrumentation change, or external trigger event. + +> Flag as: *"Step-change on [date] — value moved from X to Y and held."* + +### Spike then return + +A single point sharply different, then back to normal. Usually a +campaign, batch event, or test traffic. + +> Flag as: *"Single-day spike on [date], value returned to baseline +> next day. Looks like a one-off."* + +### Drift (trend-level shift) + +The last 30 days are running consistently above or below the prior 30, +without a single step-change point. Slower-moving than a step-change, +harder to spot at a glance. + +> Flag as: *"The last 30 days run ~X% [above/below] the prior period — +> looks like a baseline shift, not a single event."* + +### Going to zero + +A series that drops to zero and stays there is almost never a real +business signal — it's an instrumentation break. SDK update, event +rename, deploy that broke tracking. + +> Flag as: *"Series goes to zero on [date] and stays flat. This usually +> means tracking broke, not that the behavior actually stopped."* + +### Cyclic pattern (weekly seasonality) + +Most user-facing metrics show weekday/weekend cycles. If the chart +spans a few weeks, the cycle should be obvious. Two things to flag: +- Cycle disappears suddenly (something dampened weekend activity) +- Cycle inverts (weekends becoming higher than weekdays) + +### High-cardinality breakdown explosion + +If the breakdown shows hundreds of small segments, the chart is +probably misconfigured (e.g., breaking down by `user_id`). Surface +this as a chart quality issue, not a metric finding. + +--- + +## Common reader pitfalls + +**Mistaking weekend dips for drops** +If the customer is looking at a single recent low point, check if it's +a weekend. The chart isn't broken; it's Tuesday vs. Sunday. + +**Treating ratios like volumes** +A conversion ratio chart can change because the numerator moved OR the +denominator moved. Always state which. + +**Reading the legend wrong** +Multi-series charts: confirm which line the customer is asking about +before analyzing. "The blue one" might be a different segment from +what they think. + +**Comparing different time aggregations** +A chart switching from daily to weekly granularity creates an +artificial "drop" because weekly bins are smaller in the partial last +week. Verify granularity before flagging movement. + +--- + +## Output focus + +Insights summary should answer: +- What's the current level? +- What direction is it moving? +- Is anything unusual happening? + +Skip: +- Methodology ("this is unique users, not events" — only mention if + relevant to the finding) +- Hypothesis on why ("might be because of..." — that's a root-cause investigation, out of scope) diff --git a/plugins/mixpanel-mcp/skills/analyze-report/references/read-retention.md b/plugins/mixpanel-mcp/skills/analyze-report/references/read-retention.md new file mode 100644 index 0000000..a569849 --- /dev/null +++ b/plugins/mixpanel-mcp/skills/analyze-report/references/read-retention.md @@ -0,0 +1,124 @@ +# Reading Retention charts — reference + +Use this reference when the chart being analyzed is a **Retention** +chart (cohort retention triangle, stickiness, DAU/MAU). + +--- + +## What to read first + +1. **Period-1 retention** — what % of cohort returns the period + immediately after birth. This is the steepest drop-off and the most + important number. + +2. **Long-tail retention** — where does the curve flatten? A retention + curve that flattens at 20% means roughly 1-in-5 users become + long-term active. A curve that goes to zero has no durable base. + +3. **Cohort comparison** — are recent cohorts retaining better, worse, + or similar to older cohorts? This is the trend signal — improving + onboarding shows up here. + +4. **Cohort sizes** — note if cohorts are very different sizes, + especially if recent cohorts are small. Small cohorts have noisy + retention. + +--- + +## Patterns to flag + +### Curve doesn't flatten + +A healthy retention curve flattens — losing fewer users each period +because the remaining users are increasingly engaged. If the curve +keeps declining linearly, the product has no "sticky" base. + +> Flag as: *"Curve continues to decline through period [N] without +> flattening — no sign of a durable retained user base."* + +### Flat curve after period 1 + +Sometimes the curve drops sharply in period 1 then is essentially flat +— a small core of users who keep coming back. The headline retention % +might look low, but the *shape* is healthy. + +> Flag as: *"Big drop in period 1, then nearly flat — small but +> durable retained cohort."* + +### Recent cohorts diverging from older cohorts + +If recent cohorts retain noticeably better or worse than older ones, +something changed — onboarding flow, acquisition source mix, or +product changes. Worth flagging clearly. + +> Flag as: *"Cohorts from [recent period] retain ~X% [better/worse] than +> cohorts from [earlier period] — the product or acquisition changed."* + +### Small cohort noise + +If recent cohorts are <100 users per period, retention numbers are +unreliable. Surface this so the customer doesn't read meaning into +noise. + +> Flag as: *"Recent cohorts are small (<100 users/period) — the +> percentages are noisy. Need a longer date range or larger acquisition +> volume for clean numbers."* + +### Impossible retention (>100% or 0%) + +If period-N retention shows >100%, the retention type is bounded vs. +unbounded mismatched, or the same user is being counted multiple times. +Surface as a chart configuration issue, not a finding. + +If period-1 retention is 0% across the board, the return event likely +is the same as the birth event (e.g., signup retention measured against +signup, which by definition only fires once per user). + +### Stickiness (DAU/MAU) anomalies + +For DAU/MAU charts: +- Healthy consumer products: 10–25% +- Healthy B2B products: 30–50% +- >70% almost always means MAU is artificially low (small user base or + short measurement window) +- <5% means daily engagement is rare — flag as low stickiness + +--- + +## Common reader pitfalls + +**Reading retention as engagement** +A user who returns once in week N counts as retained, even if their +engagement is shallow. High retention % doesn't mean high usage. + +**Comparing cohorts across product changes** +If the product changed materially mid-window, comparing pre-change +cohorts to post-change cohorts is comparing two different products. +Surface this if the customer's business context mentions a recent +launch or major change. + +**Confusing retention with churn** +Retention is the inverse of churn, but they're not always perfectly +complementary in Mixpanel. A user "not retained" in week N might +return in week N+1. Don't equate "not retained this week" with "lost +forever." + +**Cohort retention vs. rolling retention** +Mixpanel's native retention is cohort retention (% of birth-week users +who returned in week N). If the customer asks about "30-day retention" +and means rolling retention (% of users active today who were active +30 days ago), the chart might not be answering their question. + +--- + +## Output focus + +Retention summary should answer: +- What's period-1 retention? +- Does the curve flatten, and at what level? +- Are recent cohorts trending better or worse? + +Skip: +- Methodology lectures (only explain bounded vs. unbounded if relevant + to a finding) +- Hypotheses on why retention shifted (that's a root-cause investigation, out of scope) From 5ab89f66acacc9db45e8efe492ae01a53d6718a6 Mon Sep 17 00:00:00 2001 From: Naitik Soni <91239827+naitik-mixpanel@users.noreply.github.com> Date: Tue, 9 Jun 2026 23:43:46 +0530 Subject: [PATCH 2/2] minor updates to skill.md file --- .../skills/analyze-report/SKILL.md | 29 ++++++++++++++----- .../skills/analyze-report/SKILL.md | 29 ++++++++++++++----- .../skills/analyze-report/SKILL.md | 29 ++++++++++++++----- 3 files changed, 66 insertions(+), 21 deletions(-) diff --git a/plugins/mixpanel-mcp-eu/skills/analyze-report/SKILL.md b/plugins/mixpanel-mcp-eu/skills/analyze-report/SKILL.md index 6716944..fd1d17c 100644 --- a/plugins/mixpanel-mcp-eu/skills/analyze-report/SKILL.md +++ b/plugins/mixpanel-mcp-eu/skills/analyze-report/SKILL.md @@ -12,8 +12,11 @@ description: > this". Also trigger when the user pastes a Mixpanel chart or report URL and asks anything about it. Lean by default — surfaces what the report shows and flags notable patterns, but does not chase root - causes. Do NOT trigger for building new charts, reviewing entire - dashboards, or full root-cause diagnostic workflows. Requires Mixpanel MCP. + causes. This skill = interpret WHAT a report shows; mxp-metric-diagnosis + = investigate WHY a metric moved. Do NOT trigger for building new charts, + reviewing entire dashboards, or full root-cause diagnostic workflows. Do NOT + trigger for root-cause diagnosis, anomaly investigation, or metric drift — + use mxp-metric-diagnosis for those. Requires Mixpanel MCP. compatibility: "Requires Mixpanel MCP. Works for any project the user has access to." --- @@ -72,11 +75,20 @@ If `Search-Entities` returns nothing useful, escalate to Mode C: ### Mode C — Customer wants to analyze a report that doesn't exist yet -The report has to be built before it can be analyzed. Build the chart -first (or ask the customer to point you at the configuration they want), -then come back to Step 2 and analyze the result. Once the chart is -built you'll have a `query_id` and a rendered widget; this skill picks -up from there. +The report has to be built before it can be analyzed. This skill builds +it inline — it does not hand off to another skill. Do it in three calls: + +1. Call `Get-Query-Schema` to learn the valid shape for the query type + (insights, funnel, retention, flows) the customer is describing. +2. Construct the query from the customer's description and call + `Run-Query` to execute it. This returns the result data and gives you + the configuration metadata you need for analysis. +3. Optionally call `Display-Query` to render the chart so the customer + can see it alongside the summary. + +Once `Run-Query` returns, you already have the data and config — skip +ahead to Step 3 and read the shape (Step 2 is only for pulling data on +an existing report). If the customer asks for both in one turn ("build me a DAU chart and tell me what it shows"), do them as one workflow: build → analyze → @@ -112,6 +124,9 @@ What to look for depends on chart type. Read the matching reference: - Retention → `references/read-retention.md` - Flows → `references/read-flows.md` +Only load the reference file that matches the chart type — do not load +all four. + The references hold the **specific patterns** to look for in each chart type. The high-level rules across all types: diff --git a/plugins/mixpanel-mcp-in/skills/analyze-report/SKILL.md b/plugins/mixpanel-mcp-in/skills/analyze-report/SKILL.md index 6716944..fd1d17c 100644 --- a/plugins/mixpanel-mcp-in/skills/analyze-report/SKILL.md +++ b/plugins/mixpanel-mcp-in/skills/analyze-report/SKILL.md @@ -12,8 +12,11 @@ description: > this". Also trigger when the user pastes a Mixpanel chart or report URL and asks anything about it. Lean by default — surfaces what the report shows and flags notable patterns, but does not chase root - causes. Do NOT trigger for building new charts, reviewing entire - dashboards, or full root-cause diagnostic workflows. Requires Mixpanel MCP. + causes. This skill = interpret WHAT a report shows; mxp-metric-diagnosis + = investigate WHY a metric moved. Do NOT trigger for building new charts, + reviewing entire dashboards, or full root-cause diagnostic workflows. Do NOT + trigger for root-cause diagnosis, anomaly investigation, or metric drift — + use mxp-metric-diagnosis for those. Requires Mixpanel MCP. compatibility: "Requires Mixpanel MCP. Works for any project the user has access to." --- @@ -72,11 +75,20 @@ If `Search-Entities` returns nothing useful, escalate to Mode C: ### Mode C — Customer wants to analyze a report that doesn't exist yet -The report has to be built before it can be analyzed. Build the chart -first (or ask the customer to point you at the configuration they want), -then come back to Step 2 and analyze the result. Once the chart is -built you'll have a `query_id` and a rendered widget; this skill picks -up from there. +The report has to be built before it can be analyzed. This skill builds +it inline — it does not hand off to another skill. Do it in three calls: + +1. Call `Get-Query-Schema` to learn the valid shape for the query type + (insights, funnel, retention, flows) the customer is describing. +2. Construct the query from the customer's description and call + `Run-Query` to execute it. This returns the result data and gives you + the configuration metadata you need for analysis. +3. Optionally call `Display-Query` to render the chart so the customer + can see it alongside the summary. + +Once `Run-Query` returns, you already have the data and config — skip +ahead to Step 3 and read the shape (Step 2 is only for pulling data on +an existing report). If the customer asks for both in one turn ("build me a DAU chart and tell me what it shows"), do them as one workflow: build → analyze → @@ -112,6 +124,9 @@ What to look for depends on chart type. Read the matching reference: - Retention → `references/read-retention.md` - Flows → `references/read-flows.md` +Only load the reference file that matches the chart type — do not load +all four. + The references hold the **specific patterns** to look for in each chart type. The high-level rules across all types: diff --git a/plugins/mixpanel-mcp/skills/analyze-report/SKILL.md b/plugins/mixpanel-mcp/skills/analyze-report/SKILL.md index 6716944..fd1d17c 100644 --- a/plugins/mixpanel-mcp/skills/analyze-report/SKILL.md +++ b/plugins/mixpanel-mcp/skills/analyze-report/SKILL.md @@ -12,8 +12,11 @@ description: > this". Also trigger when the user pastes a Mixpanel chart or report URL and asks anything about it. Lean by default — surfaces what the report shows and flags notable patterns, but does not chase root - causes. Do NOT trigger for building new charts, reviewing entire - dashboards, or full root-cause diagnostic workflows. Requires Mixpanel MCP. + causes. This skill = interpret WHAT a report shows; mxp-metric-diagnosis + = investigate WHY a metric moved. Do NOT trigger for building new charts, + reviewing entire dashboards, or full root-cause diagnostic workflows. Do NOT + trigger for root-cause diagnosis, anomaly investigation, or metric drift — + use mxp-metric-diagnosis for those. Requires Mixpanel MCP. compatibility: "Requires Mixpanel MCP. Works for any project the user has access to." --- @@ -72,11 +75,20 @@ If `Search-Entities` returns nothing useful, escalate to Mode C: ### Mode C — Customer wants to analyze a report that doesn't exist yet -The report has to be built before it can be analyzed. Build the chart -first (or ask the customer to point you at the configuration they want), -then come back to Step 2 and analyze the result. Once the chart is -built you'll have a `query_id` and a rendered widget; this skill picks -up from there. +The report has to be built before it can be analyzed. This skill builds +it inline — it does not hand off to another skill. Do it in three calls: + +1. Call `Get-Query-Schema` to learn the valid shape for the query type + (insights, funnel, retention, flows) the customer is describing. +2. Construct the query from the customer's description and call + `Run-Query` to execute it. This returns the result data and gives you + the configuration metadata you need for analysis. +3. Optionally call `Display-Query` to render the chart so the customer + can see it alongside the summary. + +Once `Run-Query` returns, you already have the data and config — skip +ahead to Step 3 and read the shape (Step 2 is only for pulling data on +an existing report). If the customer asks for both in one turn ("build me a DAU chart and tell me what it shows"), do them as one workflow: build → analyze → @@ -112,6 +124,9 @@ What to look for depends on chart type. Read the matching reference: - Retention → `references/read-retention.md` - Flows → `references/read-flows.md` +Only load the reference file that matches the chart type — do not load +all four. + The references hold the **specific patterns** to look for in each chart type. The high-level rules across all types: