IntermediateAgent Skill

Product Analytics

Run cohort retention analysis and inspect product metrics from your own CSV exports. This Skill combines metric frameworks with a Python calculator for retention, cohorts and stage counts, helping a team turn user IDs and activity records into inspectable tables before deciding where the product experience needs closer investigation.

Views
0
Copies
0
Favorites
0
Editorial Score
82/100
01

What this Skill does

Product Analytics helps define what to measure and calculate the corresponding tables. It includes AARRR, North Star and HEART guidance alongside code whose inputs and calculations can be inspected, making it useful when the team has exports but needs a consistent analysis method.

Retention is calculated using day offsets, so compare cohorts only after checking their observation windows. The funnel function counts users at each supplied stage; it does not verify event order or that users progressed through every earlier step. Use a suitable event analysis for ordered journey questions.

02

What makes it different

01

Approach and advantage

Metric frameworks help connect a business question to a defined measure before running the calculator. Agree on user identity, activity and observation windows first so a retention table has a stable meaning across reports.

02

What you can use it for

The Python output makes retention and stage counts reviewable against the CSV inputs. Check cohort maturity and the stage-count limitation before interpreting a drop as abandonment, then use the tables to decide which behavior needs deeper investigation.

03

Before you install

Inputs to prepare

Consistent user IDs, cohort dates, activity dates or stage labels, metric definitions, and observation windows.

Agent and runtime

Use a Skill-capable agent with file access. Python 3 is required for the bundled Python helpers; inspect their sample schemas before supplying data.

Scope to confirm

Retention uses day offsets; cohort maturity must be checked. The funnel counts users per stage without validating event order or nested progression, so it is not an ordered event funnel.

04

Install and get started

Copy this request into Codex or Claude Code. The assistant downloads the original repository at the specified commit, installs the complete files and checks required dependencies.

  1. Open Codex or Claude Code with local file and terminal access.
  2. Copy the request below into the app you are using. The assistant will select that app’s installation directory.
  3. Check the returned path and file checks. Start a new session if needed, then ask the assistant to use the installed Skill.
Install product-analytics in the app I am using and carry out the file installation, not just explain it. Original repository: https://github.com/alirezarezvani/claude-skills.git Commit: 6d2f02ea077eead1bee5411a31bcc6db5a11a70c Skill folder: product-team/skills/product-analytics 1. Download this exact source into a new directory. Read SKILL.md and its setup references before running any bundled scripts. Do not substitute another author’s package. 2. For Codex, use ~/.agents/skills/product-analytics; for Claude Code, use ~/.claude/skills/product-analytics. Install only for my current app. Install the complete Skill folder, including scripts, references, assets and bundled notices. Keep any root license with the installed folder. Check all destination folders first; if any already exist, report differences before replacing them. 3. Compare the source and installed file lists and hashes. Inspect documented runtimes, dependencies and required connections. Configure only the local dependencies needed for this Skill; use an isolated environment when appropriate. Ask me to complete any account login locally, without putting credentials in chat. 4. Report the source commit, actual installation path, file-check results and any remaining runtime setup. Explain how to invoke product-analytics in this app. Check discovery separately from file copying; start a new session if needed. Do not run production tasks or claim a successful business outcome from installation alone.
05

Original Skill.md

This is the unchanged source SKILL.md for the reviewed version. Install the complete package to retain referenced scripts, assets, and instructions. Starter prompts below are EcomAgentTools examples.

---
name: product-analytics
description: Use when defining product KPIs, building metric dashboards, running cohort or retention analysis, or interpreting feature adoption trends across product stages.
---

# Product Analytics

Define, track, and interpret product metrics across discovery, growth, and mature product stages.

## When To Use

Use this skill for:
- Metric framework selection (AARRR, North Star, HEART)
- KPI definition by product stage (pre-PMF, growth, mature)
- Dashboard design and metric hierarchy
- Cohort and retention analysis
- Feature adoption and funnel interpretation

## Workflow

1. Select metric framework
- AARRR for growth loops and funnel visibility
- North Star for cross-functional strategic alignment
- HEART for UX quality and user experience measurement

2. Define stage-appropriate KPIs
- Pre-PMF: activation, early retention, qualitative success
- Growth: acquisition efficiency, expansion, conversion velocity
- Mature: retention depth, revenue quality, operational efficiency

3. Design dashboard layers
- Executive layer: 5-7 directional metrics
- Product health layer: acquisition, activation, retention, engagement
- Feature layer: adoption, depth, repeat usage, outcome correlation

4. Run cohort + retention analysis
- Segment by signup cohort or feature exposure cohort
- Compare retention curves, not single-point snapshots
- Identify inflection points around onboarding and first value moment

5. Interpret and act
- Connect metric movement to product changes and release timeline
- Distinguish signal from noise using period-over-period context
- Propose one clear product action per major metric risk/opportunity

## KPI Guidance By Stage

### Pre-PMF
- Activation rate
- Week-1 retention
- Time-to-first-value
- Problem-solution fit interview score

### Growth
- Funnel conversion by stage
- Monthly retained users
- Feature adoption among new cohorts
- Expansion / upsell proxy metrics

### Mature
- Net revenue retention aligned product metrics
- Power-user share and depth of use
- Churn risk indicators by segment
- Reliability and support-deflection product metrics

## Dashboard Design Principles

- Show trends, not isolated point estimates.
- Keep one owner per KPI.
- Pair each KPI with target, threshold, and decision rule.
- Use cohort and segment filters by default.
- Prefer comparable time windows (weekly vs weekly, monthly vs monthly).

See:
- `references/metrics-frameworks.md`
- `references/dashboard-templates.md`

## Cohort Analysis Method

1. Define cohort anchor event (signup, activation, first purchase).
2. Define retained behavior (active day, key action, repeat session).
3. Build retention matrix by cohort week/month and age period.
4. Compare curve shape across cohorts.
5. Flag early drop points and investigate journey friction.

## Retention Curve Interpretation

- Sharp early drop, low plateau: onboarding mismatch or weak initial value.
- Moderate drop, stable plateau: healthy core audience with predictable churn.
- Flattening at low level: product used occasionally, revisit value metric.
- Improving newer cohorts: onboarding or positioning improvements are working.

## Anti-Patterns

| Anti-pattern | Fix |
|---|---|
| **Vanity metrics** — tracking pageviews or total signups without activation context | Always pair acquisition metrics with activation rate and retention |
| **Single-point retention** — reporting "30-day retention is 20%" | Compare retention curves across cohorts, not isolated snapshots |
| **Dashboard overload** — 30+ metrics on one screen | Executive layer: 5-7 metrics. Feature layer: per-feature only |
| **No decision rule** — tracking a KPI with no threshold or action plan | Every KPI needs: target, threshold, owner, and "if below X, then Y" |
| **Averaging across segments** — reporting blended metrics that hide segment differences | Always segment by cohort, plan tier, channel, or geography |
| **Ignoring seasonality** — comparing this week to last week without adjusting | Use period-over-period with same-period-last-year context |

## Tooling

### `scripts/metrics_calculator.py`

CLI utility for retention, cohort, and funnel analysis from CSV data. Supports text and JSON output.

```bash
# Retention analysis
python3 scripts/metrics_calculator.py retention events.csv
python3 scripts/metrics_calculator.py retention events.csv --format json

# Cohort matrix
python3 scripts/metrics_calculator.py cohort events.csv --cohort-grain month
python3 scripts/metrics_calculator.py cohort events.csv --cohort-grain week --format json

# Funnel conversion
python3 scripts/metrics_calculator.py funnel funnel.csv --stages visit,signup,activate,pay
python3 scripts/metrics_calculator.py funnel funnel.csv --stages visit,signup,activate,pay --format json
```

**CSV format for retention/cohort:**
```csv
user_id,cohort_date,activity_date
u001,2026-01-01,2026-01-01
u001,2026-01-01,2026-01-03
u002,2026-01-02,2026-01-02
```

**CSV format for funnel:**
```csv
user_id,stage
u001,visit
u001,signup
u001,activate
u002,visit
u002,signup
```

## Cross-References

- Related: `product-team/experiment-designer` — for A/B test planning after identifying metric opportunities
- Related: `product-team/product-manager-toolkit` — for RICE prioritization of metric-driven features
- Related: `product-team/product-discovery` — for assumption mapping when metrics reveal unknowns
- Related: `finance/saas-metrics-coach` — for SaaS-specific metrics (ARR, MRR, churn, LTV)
06

Get started

Starter prompts for the main use cases—copy and use them directly.

01

Define a product metric tree for a commerce feature

Define a product metric tree for a commerce feature Use for: Define a product metric tree for a commerce feature. Prepare: Consistent user IDs, cohort dates, activity dates or stage labels, metric definitions, and observation windows.

Show prompt and variablesHide prompt and variables
Use the installed product-analytics Skill. Task: Define a product metric tree for a commerce feature. Inputs: [INPUT]. Constraints: [CONSTRAINTS]. Check missing information first. Produce a reviewable result with evidence, assumptions, and next steps. Retention uses day offsets; cohort maturity must be checked. The funnel counts users per stage without validating event order or nested progression, so it is not an ordered event funnel.

Replace these variables

[INPUT]
Consistent user IDs, cohort dates, activity dates or stage labels, metric definitions, and observation windows.
[CONSTRAINTS]
Scope, allowed actions, output format, and review requirements.
02

Compare mature retention cohorts from a clean export

Compare mature retention cohorts from a clean export Use for: Compare mature retention cohorts from a clean export. Prepare: Consistent user IDs, cohort dates, activity dates or stage labels, metric definitions, and observation windows.

Show prompt and variablesHide prompt and variables
Use the installed product-analytics Skill. Task: Compare mature retention cohorts from a clean export. Inputs: [INPUT]. Constraints: [CONSTRAINTS]. Check missing information first. Produce a reviewable result with evidence, assumptions, and next steps. Retention uses day offsets; cohort maturity must be checked. The funnel counts users per stage without validating event order or nested progression, so it is not an ordered event funnel.

Replace these variables

[INPUT]
Consistent user IDs, cohort dates, activity dates or stage labels, metric definitions, and observation windows.
[CONSTRAINTS]
Scope, allowed actions, output format, and review requirements.
03

Review stage counts and explicitly check funnel ordering

Review stage counts and explicitly check funnel ordering Use for: Review stage counts and explicitly check funnel ordering. Prepare: Consistent user IDs, cohort dates, activity dates or stage labels, metric definitions, and observation windows.

Show prompt and variablesHide prompt and variables
Use the installed product-analytics Skill. Task: Review stage counts and explicitly check funnel ordering. Inputs: [INPUT]. Constraints: [CONSTRAINTS]. Check missing information first. Produce a reviewable result with evidence, assumptions, and next steps. Retention uses day offsets; cohort maturity must be checked. The funnel counts users per stage without validating event order or nested progression, so it is not an ordered event funnel.

Replace these variables

[INPUT]
Consistent user IDs, cohort dates, activity dates or stage labels, metric definitions, and observation windows.
[CONSTRAINTS]
Scope, allowed actions, output format, and review requirements.
07

Worked example: Calculate a user funnel and fully observed retention

Two weekly business summaries, an eight-user event sample and a cutoff date support distinct session/order and user-level metrics, with D7 retention restricted to fully observed cohorts.

Steps and prompt

  1. Prepare the attached business materials, preserving amounts, units, dates and metric definitions.
  2. Analyze our customer events, purchase funnel and weekly trading data. Deduplicate users, define conversion and observation windows, calculate the main funnel losses and mature retention cohorts, and prepare a management report. Distinguish return visits or key actions from repeat purchases and prioritize the next investigation.
  3. Submit the exact prompt below. Read the primary deliverable on the right and download all deliverables for the team handoff.

Case input files: business-inputs.zip

Use the product-analytics Skill.

Analyze our customer events, purchase funnel and weekly trading data. Deduplicate users, define conversion and observation windows, calculate the main funnel losses and mature retention cohorts, and prepare a management report. Distinguish return visits or key actions from repeat purchases and prioritize the next investigation.

The attached business materials are:
- inputs/events.csv
- inputs/funnel.csv
- inputs/merchant.json
- inputs/weekly.csv

Deliver a complete result.md report that the operations team can read, plus any finished files needed for this task. Keep supporting calculations and evidence with the deliverables. Write the report in English; use the requested target language for customer-facing copy. The business datasets are fictional examples unless the brief explicitly names a live public website.

What the run produced

The primary file produced by this prompt is shown below in its original language.

HarborMug management report

Prioritize an investigation of the activate-to-pay journey, starting with event definitions and checkout instrumentation. It has the highest proportional funnel loss: 2 of 4 activated users do not appear at pay (50%). Each transition loses two users, so checkout is not uniquely the largest loss by count. Weekly sales growth comes with equal growth in traffic and advertising spend; conversion and revenue efficiency are unchanged. These results do not justify scaling advertising or claiming that the checkout copy revision improved performance.

All supplied business data are synthetic examples; no operational change or sales lift has been measured.

Measurement basis

Use AARRR for this growth-stage business: acquisition through visit and signup, activation through the supplied activate label, retention through recorded activity, and revenue through pay reach and weekly trading totals. Referral is unmeasured. The supplied activation label still needs a business definition before it can represent customer value.

The activity observation cutoff is November 2, 2026, inclusive. Dates have day-level resolution; no timezone is supplied. Retain each distinct user once in each denominator, each distinct user/cohort/activity-date combination for activity, and each distinct user/stage pair for funnel reach. This removes one duplicate activity row (18 to 17) and one duplicate funnel row (21 to 20). Each file contains eight distinct users. Cohort dates are consistent within users, and all activity falls between its cohort anchor and the cutoff.

The two files use different user identifiers with no overlap or mapping. Do not join them or infer retention for paying users. Deduplication is by supplied ID only; cross-device or cross-account identity cannot be resolved.

Current conversion definition: distinct users reaching each supplied stage divided by users in the preceding stage, across the undated funnel extract. Stage sets are nested, but sequence and elapsed time cannot be verified. The extract has no date range; November 2 cannot be asserted as its cutoff. Thus 25% visit-to-pay is stage reach, not a verified time-bounded purchase conversion rate.

Proposed production conversion window: follow users from first eligible visit for seven elapsed days; require visit → signup → a defined activation → confirmed payment in chronological order. Count each user once, attribute to the first-visit cohort, and exclude users lacking the full seven-day follow-up from the mature denominator. This is a measurement proposal, not a recalculation possible from the current files. Confirm whether signup and activation are required purchase steps before enforcing this path; track direct-purchase paths separately if permitted.

Retention definition: use the supplied cohort_date as an anchor of unspecified business meaning, not an assumed signup or first-purchase date. W0 is anchor days 0–6, W1 days 7–13, W2 days 14–20, and so on. A user is retained if at least one activity occurs in that window. Count a window only once it has fully elapsed for the cohort. Exact-day retention is separate and requires only that day to have elapsed. Missing activity in a fully observed window counts as zero, conditional on the supplied event coverage being complete.

Funnel losses

StageUnique usersConversion from preceding stageUsers lostLoss rateShare of visitors
Visit8———100%
Signup675.0%225.0%75.0%
Activate466.7%233.3%50.0%
Pay250.0%250.0%25.0%

Six of eight visitors do not reach pay: a cumulative 75% loss. Activate-to-pay has the largest proportional drop, while all three transitions tie in absolute loss. With only four activated users, one additional payer would change that transition rate by 25 percentage points. Treat the ranking as an investigation priority, not proof of a persistent checkout problem or an estimate of recoverable revenue.

Mature retention cohorts

Values are active users / cohort users and rate. N/A means the full window has not elapsed; it does not mean churn.

Anchor cohortUsersW0W1W2W3W4
October 544/4 (100%)2/4 (50%)0/4 (0%)0/4 (0%)N/A
October 1944/4 (100%)2/4 (50%)N/AN/AN/A

The October 5 W4 window is November 2–8, and the October 19 W2 window is November 2–8. Both are incomplete. The older cohort's W2 and W3 are complete and show no recorded activity. The newer cohort has the same W1 rate; there is no observed improvement in that comparable window. Across both mature W1 cohorts, retention is 4/8 (50%). Do not blend the older cohort's mature W2 zero with the newer cohort's unfinished W2.

Anchor cohortD1 exact dayD7 exact dayD14 exact dayD28 exact day
October 52/4 (50%)2/4 (50%)0/4 (0%)0/4 (0%)
October 193/4 (75%)2/4 (50%)0/4 (0%)N/A

Both D14 observations are mature, yielding 0/8, even though the newer cohort's full W2 is immature. Older-cohort D28 is also mature on the cutoff date while its full W4 is not. Exact-day zeros do not prove absence of activity throughout a week.

The curve shows activity at anchor, a drop to 50% in W1, and disappearance in later mature windows for the older cohort. Four users per cohort are too few to establish a stable curve or a release effect. W0 is not repeat retention because every user already has anchor-day activity. Five of eight users have at least one activity on a later date, but this cumulative return measure has unequal follow-up and should not replace the mature cohort comparison.

Recorded activity is not identified as a visit, key action, or purchase. These results describe generic activity retention only. Return visits and repeated key actions require event types; repeat purchases require customer-linked, distinct paid order IDs and payment dates. Neither repeat-purchase rate nor purchase frequency is measurable here. The funnel's two pay users and weekly order totals cannot supply those missing links.

Weekly trading performance

Dollar amounts are treated as USD for this US merchant. The weekly extract labels periods only as prior/current, so their dates, equal duration and relationship to the release cannot be verified.

MetricPriorCurrentChange
Sessions4,0004,800+20%
Orders100120+20%
Gross sales$2,400$2,880+20%
Refund value$120$144+20%
Sales less refunds$2,280$2,736+20%
Advertising spend$300$360+20%
Orders / sessions2.50%2.50%0.00 percentage points
Gross average order value$24$240%
Refund value / gross sales5.00%5.00%0.00 percentage points
Gross sales / ad spend8.00×8.00×0%
Sales less refunds / ad spend7.60×7.60×0%
Ad spend / order$3$30%

At the prior order/session rate, 800 additional sessions imply 20 additional orders, matching the observed increase. At unchanged $24 AOV, that accounts arithmetically for the $480 gross-sales increase. This is a decomposition, not evidence that advertising caused the increase. Sales less refunds rose $456 with $60 more ad spend, but this is not profit: fulfillment, goods, payment fees, tax and refund accounting are not fully specified at order level.

The sales/ad-spend ratios are blended store ratios, not attributed advertising ROAS. Ad spend/order is not customer acquisition cost because orders are not distinct newly acquired customers. Refund value rate is not the percentage of orders refunded. The 2.5% order/session ratio and 25% user funnel reach measure different populations and denominators and must not be reconciled as if they were one conversion metric.

The October 19 checkout copy revision has no causal evidence. The newer cohort starts on that date, but neither feature exposure nor dated funnel events nor dated trading periods are available. Seasonality and same-period-last-year comparisons are also unavailable.

Next investigation and operating dashboard

First priority — validate activate-to-pay and locate the failure. Assign the product/checkout owner, with analytics support, to define activation, confirm whether stage skipping is allowed, and reconcile the two activated non-payers against checkout starts, payment attempts, errors and confirmed orders in the source system. Obtain timestamped events with a common customer identifier, event type, order ID, release exposure, device and acquisition channel. First separate instrumentation gaps from actual abandonment, then compare mature seven-day funnels across equivalent periods and segments. These are recommended investigations; none has been performed in this analysis.

The next retention investigation should examine why the October 5 cohort has no W2/W3 activity: verify tracking coverage and identify which later visits or actions would represent customer value. Track visit retention, key-action retention and second-purchase incidence separately. For purchases, anchor on first confirmed paid order and measure a second distinct paid order within 30 days among customers with complete 30-day follow-up. A durable mug may have a longer repurchase cycle; validate the horizon against purchasing history before adopting a commercial target.

Use six executive metrics below, with weekly cohort filters and counts alongside percentages. Thresholds are proposed operating rules based on this small baseline, not established performance standards; rebaseline after obtaining comparable production coverage.

MetricCurrent baselineProposed target / alertOwnerDecision rule
Ordered seven-day visit-to-payUnavailable; undated reach 2/8 (25%)Establish mature baseline; alert below 25% provisionallyAnalytics leadRepair coverage first; investigate a mature decline before changing acquisition spend
Activate-to-payUndated reach 2/4 (50%)Above 50%; alert at or below 50%Checkout ownerReview payment and abandonment evidence; prioritize a specific fix only after diagnosis
Mature W1 activity retention4/8 (50%)At least 50%; alert below 50%Product ownerInspect onboarding and later value actions; do not infer repurchase
Orders / sessions2.50% in both periodsAt least 2.50%; alert below 2.50%Operations leadCheck dated comparable periods and segment mix before attributing movement
Sales less refunds / ad spend7.60× in both periodsAt least 7.60×; alert below 7.60×Growth leadReview acquisition mix and contribution economics before scaling
Refund value / gross sales5.00% in both periodsAt most 5%; alert above 5%Finance leadReconcile refund timing and reasons before diagnosing product quality

Below the executive layer, show acquisition → activation → pay by cohort, channel and device, followed by the mature retention matrix. At feature level, add checkout-copy exposure, adoption, repeat key actions, payment errors and purchase outcomes once instrumented; those measures cannot be inferred from these inputs. Annotate the release on dated charts without attaching causal claims.

Supporting deliverables

  • funnel_metrics.csv: unique stage counts, transition losses and conversion rates.
  • retention_weekly.csv: cohort windows, maturity flags, counts and rates; immature cells are blank.
  • retention_exact_day.csv: exact-day maturity and retention, separate from weekly windows.
  • weekly_metrics.csv: source totals and calculated trading ratios.
  • events_deduplicated.csv and funnel_deduplicated.csv: cleaned business records.
  • verification.json: row counts, duplicate removal and consistency checks.
  • calculate.py: reproducible calculations; run python3 deliverables/calculate.py from the folder containing inputs/ and deliverables/.

Rates are stored as fractions in the CSV files. Weekly formulas are orders/sessions, gross/orders, refunds/gross, gross/adspend, (gross−refunds)/adspend and adspend/orders. Supporting checks confirm nested funnel membership, consistent cohort dates and events within the observation period.

Merchant business data is synthetic. Website observations, when present, come from the public URLs listed in the report.

08

Risks and operating notes

Known limits

Retention uses day offsets; cohort maturity must be checked. The funnel counts users per stage without validating event order or nested progression, so it is not an ordered event funnel.

Evidence and review

Source and package files reviewed: GitHub 6d2f02ea077e. This is a static review, not an installation or business-outcome test.

Before acting on the result

Use authorized inputs and keep secrets out of prompts. Review customer-facing claims, calculations, code changes, and any proposed external action before applying them.

Frequently asked questions

What does it do, and what is the advantage?

Define product metrics and calculate retention, cohort tables, and funnel counts from CSV data. The Python calculator makes inputs and calculations inspectable alongside AARRR, North Star, and HEART guidance.

How do I install it and start?

Choose the method for your agent and install the complete package, not just the displayed SKILL.md. Consistent user IDs, cohort dates, activity dates or stage labels, metric definitions, and observation windows. Start a new agent session and explicitly ask to use product-analytics. Try one use case below with a small sample and review the output.

Which situations is it useful for?

Define a product metric tree for a commerce feature; Compare mature retention cohorts from a clean export; Review stage counts and explicitly check funnel ordering

What limitations should I know?

Retention uses day offsets; cohort maturity must be checked. The funnel counts users per stage without validating event order or nested progression, so it is not an ordered event funnel.

What was checked for this page?

Source and package files reviewed: GitHub 6d2f02ea077e. This is a static review, not an installation or business-outcome test.

No reviews yet.

Leave a review

Rate every dimension, then share your real experience.

Task effectiveness
Setup and ease of use
Reliability and guardrails
Documentation clarity
Time to first useful result
Author / maintainer

Alireza Rezvani

Source and package files reviewed: GitHub 6d2f02ea077e. This is a static review, not an installation or business-outcome test.