mcpField
C
cohort-analysis

cohort-analysis

github.com/nimrodfisherData & databases509237 installsUpdated 5w ago
Repository

About cohort-analysis

A product analytics skill for measuring retention across signup or other user cohorts and comparing their behavior over time. It provides a workflow from event data through retention matrices and visualizations to a written report.

Key features

  1. 01Define cohorts and retention events
  2. 02Build cohort tables from event data
  3. 03Calculate retention matrices
  4. 04Visualize retention with heatmaps and curves
  5. 05Report templates and metric references

Use cases

  1. 01Compare retention with a previous period
  2. 02Measure daily, weekly, or monthly retention
  3. 03Compare acquisition cohorts over their lifetimes
  4. 04Identify when users typically churn

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/nimrodfisher/data-analytics-skills --skill cohort-analysis

After installing, type/cohort-analysisin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

assets/
cohort_report_template.md
retention_matrix.html
references/
cohort_definition_patterns.md
retention_metrics_glossary.md
scripts/
cohort_builder.py
cohort_query.sql
cohort_visualizer.py
retention_matrix.py

Details

From the project README

When to use

  • A stakeholder asks "are we retaining users better than last quarter?"
  • You need to measure N-day, weekly, or monthly retention for a product or feature
  • You want to compare how different acquisition cohorts (by channel, plan, or signup date) perform over their lifetime
  • You're investigating churn and need to identify at which period users typically leave

Process

  1. Define the cohort and activity — clarify: cohort grouping (signup month, first purchase date, etc.) and retention event (login, purchase, feature use). Document in the report header.
  2. Pull or build the data — if starting from a database, use scripts/cohort_query.sql as the starting point. Adapt the cohort_date and activity_date columns to your schema.
  3. Build the cohort table — run scripts/cohort_builder.py to produce a cohort × period membership table from event data. Output is a CSV with user_id, cohort_period, activity_period.
  4. Compute the retention matrix — run scripts/retention_matrix.py on the cohort table to generate the period-over-period retention rates. Output is an N×M matrix (cohort × period).
  5. Visualise — run scripts/cohort_visualizer.py to render a heatmap of the retention matrix and a time-series of retention curves per cohort.
  6. Interpret findings — consult references/retention_metrics_glossary.md for metric definitions and references/cohort_definition_patterns.md for pattern recognition.
  7. Write the report — fill assets/cohort_report_template.md. For a visual deliverable, fill in the assets/retention_matrix.html heatmap template.

Inputs the skill needs

  • Required: event data with user_id, cohort_date (e.g. signup_date), activity_date
  • Required: cohort grouping granularity (daily / weekly / monthly)
  • Required: retention event definition — what counts as "active" or "retained"?
  • Optional: minimum cohort size (recommend ≥ 100 users; smaller cohorts have noisy rates)
  • Optional: number of periods to track (e.g. 12 months)
  • Optional: cohort attributes to segment by (acquisition channel, plan tier, geography)

Output

  • assets/cohort_report_template.md (filled) — narrative interpretation and retention figures
  • assets/retention_matrix.html (filled) — colour-coded retention heatmap
  • scripts/retention_matrix.py output CSV — raw retention rates for downstream use

Comments

Markdown supported