Skip to content

shisuidata/ss-data-skills / skills/retention-cohort-analysis

retention-cohort-analysis

Verified

Use when analyzing retention, cohort behavior, repeat purchase, active user return, subscription renewal, or user stickiness over time. Builds cohort retention matrices from event data with a bundled zero-dependency script that masks immature cells, keeps curves on a fixed cohort set, compares segments, flags mix-adjusted anomaly cohorts, decomposes cohort-over-cohort change into mix vs retention effects, and renders an HTML report. 中文触发词:留存分析、Cohort、复购、续费、用户流失、次日留存。

Retention Cohort Analysis

目标

分析用户、客户或业务对象在进入之后是否持续回来,并回答:

  1. 留存曲线长什么样?后段有没有趋平(有没有稳定留下来的用户)?
  2. 哪些分群留存更差?哪些批次异常?
  3. 最近批次留存变差,是来了不一样的用户,还是同样的用户留得更差?

核心原则:数字由脚本算,判断由人做。留存矩阵、曲线、分群对比、异常批次和结构拆解用 scripts/retention.py 计算;模型负责定义口径、解释原因、提出验证动作。

使用场景

  • 新用户次日、7 日、30 日留存
  • 周留存、月留存、会员续费、订阅续约
  • 首购后复购
  • 不同渠道、版本、首日行为的用户质量对比
  • “最近几批用户留存变差了,为什么”
  • B 端客户活跃与流失

典型输入:

帮我看不同渠道新用户的 7 日和 30 日留存,最近几周是不是变差了。

不适用场景

  • 有序步骤的转化:使用 funnel-analysis
  • 有随机分组的实验:使用 ab-test-analysis
  • 指标口径本身有争议:先用 metric-definition-reviewer
  • 预测某个用户会不会流失:这是建模问题,使用 feature-engineering-advisor 和 model-evaluation-reviewer

没有明确“起点行为”和“回访行为”时,先定义 Cohort 口径。

输入信息

最少输入:

  • 起点:注册、首购、首次签约等事件或时间
  • 回访行为:主动打开、核心行为、再次购买、续费
  • 用户或对象 ID、时间字段

推荐输入:

  • 事件明细 CSV + 用户属性 CSV(渠道、设备、套餐等)
  • Cohort 粒度:日 / 周 / 月
  • 留存口径:第 N 期当期回访,还是 N 期内有过回访
  • 按日时:自然日还是滚动 24 小时
  • 想对比的两组批次(例如改版前后)

输入字段详见 输入格式。

上下文建议

推荐使用 留存 Cohort 分析上下文模板 准备结构化输入。

通用分析背景请参考 数据分析上下文模板。

最有价值的上下文是:起点行为、回访行为、时间口径(自然日 / 滚动 24 小时)、Cohort 粒度和分群维度。时间口径不明确时,必须先确认,不能混用。

工作流程

  1. 定义口径:起点、回访行为(只算主动行为,排除推送到达、后台唤醒)、粒度、留存口径、时间边界。写成表格请用户确认。

  2. 运行脚本(能执行代码时必须运行):

    python3 scripts/retention.py analyze --events events.csv \
      --start-event register_success --return-event "app_open|product_view" \
      --users users.csv --segment channel_id \
      --unit week --periods 1,2,3,4,6,8 --key-period 2 \
      --period 前4周=2026-03-02..2026-03-29 --period 后4周=2026-03-30..2026-04-26 --baseline 前4周 \
      --html retention_report.html
    

    数据量很大时,先用 留存 SQL 模板 在仓库里汇总,再用 --summary 输入。

    列名不同时用 --user-col、--event-col、--time-col 指定。文件可以是 UTF-8 或 GBK。批次按业务时区划分:带时区的时间按 --tz(默认 +08:00)换算,UTC 数据不用手工转换。全部参数见 命令行参数。

  3. 先看质量检查:成熟度、样本量、自然日与滚动口径的差距、回访事件是否被动。

  4. 读结果:

    • curve:固定批次集合上的留存曲线,后段是否趋平
    • segment_tests:每个分群与其余用户的差异和置信区间
    • anomalies:按分群构成调整后仍然异常的批次
    • comparison.segments[dim]:两组批次之间的结构效应与留存效应
  5. 解释与建议:结合 解读要点 给出原因假设和验证动作。

  6. 交付:Markdown 结论 + HTML 报告路径。

不能执行代码时:按同样的结构人工计算,并在结论中写明“未经脚本计算”。

输出格式

## 留存 / Cohort 分析结果

### 1. 结论
<一句话:关键周期留存多少、有没有变差、主要原因是用户构成还是产品>

### 2. Cohort 定义
| 项目 | 口径 |
| --- | --- |
| Cohort 起点 |  |
| 回访行为 |  |
| 统计对象 |  |
| 粒度与周期 |  |
| 留存口径 | 第 N 期当期 / N 期内 |
| 时间边界 | 自然日 / 滚动 24 小时 |

### 3. 留存曲线与矩阵
<曲线形状、是否趋平;矩阵里哪些批次偏深偏浅>

### 4. 分群差异
| 分群 | 关键周期留存 | 与其余用户差异 | 95% 区间 | 显著 |
| --- | --- | --- | --- | --- |

### 5. 异常批次
<批次、偏离多少、对应时间点发生了什么>

### 6. 批次间变化拆解
<结构效应 vs 留存效应,具体是哪个分群>

### 7. 可能原因与验证动作
| 假设 | 支持证据 | 如何验证 |
| --- | --- | --- |

### 8. 口径风险与待确认问题

报告文件:<retention_report.html 路径>

质量标准

输出必须:

  • 先定义起点、回访行为、时间边界,再看数字
  • 未成熟的单元格留空,不能当作 0,也不能拿来和成熟批次比较
  • 曲线基于固定的批次集合,不能每个周期各用各的批次
  • 区分“用户构成变化”和“同类用户留存变化”
  • 异常批次要先排除构成变化的影响
  • 不把短期活动拉高的留存写成长期改善
  • 标记样本量过小的批次和分群
  • 说明批次按哪个时区划分

完成后的下一步

  • 写成报告:data-analysis-report-writer,把 --json 的结果作为来源
  • 验证改善动作:ab-test-analysis
  • 做流失预测:feature-engineering-advisor

示例 Prompt

请用 retention-cohort-analysis 分析新用户周留存,并生成 HTML 报告:

数据:events.csv(user_id, event_name, event_time),users.csv(user_id, channel_id)
起点:register_success;回访:app_open 或 product_view(push_receive 不算)
粒度:按周,看 W1、W2、W3、W4、W6、W8
对比:3 月前 4 周 vs 后 4 周,最近几批留存好像变差了
请用 retention-cohort-analysis 分析 SaaS 企业客户的订阅续费留存(汇总数据):

起点:首次签约月;留存:当月订阅仍为 active
窗口:M1、M3、M6
分群:套餐类型(starter / pro)
已知:最近两个签约批次的 M3 明显低于历史,想知道是套餐结构变了还是同套餐续费变差了
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall