name: agent-analytics

description: "通过你的 AI 代理实现产品数据分析：设置基于用户同意的追踪，分析漏斗、路径、留存、实验和上下文信息，再利用官方 Agent Analytics CLI 推荐最小可行增长动作。"

version: 4.0.34

author: dannyshmueli

license: MIT

repository: https://github.com/Agent-Analytics/skills

homepage: https://agentanalytics.sh

compatibility: 需要 npx 支持。浏览器授权是常规登录方式。若使用 Paperclip、OpenClaw、基于问题或无头运行时，或回调失败环境，请使用脱离式授权 + 完成代码交接。常规设置无需 API 密钥。

tags:

- analytics

- product-analytics

- tracking

- funnels

- retention

- experiments

- growth

provides:

- capability: analytics

- capability: product-analytics

- capability: ab-testing

- capability: funnels

- capability: retention

metadata:

openclaw:

requires:

anyBins:

- npx

Agent Analytics

通过你的 AI 代理进行产品数据分析。当用户希望代理安装 Agent Analytics、查询产品行为、诊断激活或留存问题、检查路径与漏斗、读取实验结果，或决定下一步该采取什么增长行动时，可使用本技能。

CLI 是执行的基础。若有代码库访问权限，请从用户的代码库、项目目标和产品流程出发。框架类建议放入 references/growth-recipes.md，不应作为独立技能存在。

必须遵守的执行策略

• 实际使用 Agent Analytics 时，请始终使用命令：npx --yes @agent-analytics/cli@0.5.34 <command>。
• 除非用户明确要求，否则不得使用原始 API 调用、curl、本地脚本、MCP 工具或本地安装的二进制文件替代。
• 优先使用固定命令：projects、all-sites、create、stats、insights、events、properties、properties-received、breakdown、pages、paths、journey、sessions、sessions-dist、replays、retention、funnel、experiments、context、portfolios、feedback 和 upgrade-link。
• CLI 0.5.34 版本中没有 report 命令。请根据固定命令输出自行生成最终报告，不要调用 report。
• 仅在固定命令无法回答特定聚合问题时使用 query。不要用 query 启动广泛的增长诊断；也不要从用户原始文本构建 --filter JSON。
• 默认采用浏览器授权方式。仅在使用 Paperclip、OpenClaw、基于问题或无头运行时，或浏览器回调无法工作时，才使用脱离式登录。
• 不得主动索取原始 API 密钥或密钥。正常设置、付费升级及中断后继续工作均应基于浏览器授权的 CLI 会话。
• 若 CLI 返回 PRO_REQUIRED 或免费版读取上限提示，请说明被阻断的原因，运行 upgrade-link --detached --reason "<为何需要 Pro>" --command "<被阻断的命令>"，发送仪表盘交接链接，完成升级后运行 whoami，再重新执行被阻断的命令。仅在有意轮询时使用 upgrade-link --wait。仪表盘页面将确认与 CLI 使用同一账户，并显示被阻断的命令及原因。
• 在 create 前验证项目名称格式：^[a-zA-Z0-9._-]{1,64}$。

认证与设置

对于 Claude Code、Codex、Cursor 及本地 CLI 运行时，请从标准浏览器授权开始：

npx --yes @agent-analytics/cli@0.5.34 login
npx --yes @agent-analytics/cli@0.5.34 create my-site --domain https://mysite.com
npx --yes @agent-analytics/cli@0.5.34 events my-site --event <first_useful_event> --days 7 --limit 20

不要因为工作在代理内部就随意选择脱离式登录。对于 Paperclip、OpenClaw 等基于问题的运行时，请运行 login --detached，发送授权链接，等待用户返回完成码，然后执行打印出的交换命令。

在 OpenClaw 等托管运行时中，应使用持久化认证存储，且绝不提交该配置：

export AGENT_ANALYTICS_CONFIG_DIR="$PWD/.openclaw/agent-analytics"
npx --yes @agent-analytics/cli@0.5.34 login --detached
npx --yes @agent-analytics/cli@0.5.34 auth status
AGENT_ANALYTICS_CONFIG_DIR="$PWD/.openclaw/agent-analytics" npx --yes @agent-analytics/cli@0.5.34 projects

--config-dir "$PWD/.openclaw/agent-analytics" 也有效。切勿提交 .openclaw/agent-analytics/config.json。更多设置细节请参阅 references/setup-auth.md。

行动前分类判断

Agent Analytics 以项目为核心，具备组合项目感知能力。在设置、分析或推荐埋点之前，请先判断目标是项目内工作、项目内的某个表面（surface），还是相关项目的组合工作。

• 项目是本地产品学习的基本单位，拥有事件、激活、留存、生命周期、发布、实验、目标和项目上下文。
• 一个项目可包含多个表面：应用、营销页、文档、博客、定价页、注册页、引导页、子域名、移动端客户端、本地预览 URL、部署预览等。
• 组合项目（portfolio）是用于关联项目的跨项目增长系统，用于共享目标、角色、里程碑和身份感知的读取分析。
• 保持项目本地真相的独立性。禁止组合上下文覆盖单个项目的激活定义、事件含义、生命周期或目标。

决策规则：子域名通常为表面；移动端在共享激活与生命周期时视为表面；免费工具若服务于相同产品循环，则视为表面；localhost、测试环境、局域网地址和预览环境属于设置或 QA 表面；独立产品应作为单独项目置于同一组合下。若 URL 与预期不符，不要立即判定为错误。请澄清其所属项目与表面。

作用范围命令：项目内设置或分析使用项目命令；相关项目分组使用 portfolios create、portfolios update 和 portfolios list；共享目标、角色与里程碑仅在组合解释中体现。参考文档：<https://docs.agentanalytics.sh/guides/projects-surfaces-portfolios/>。

对于跨项目身份拼接，需双向配置：data-link-domains 会在相关域名间传递匿名 _aa 值，但只有服务器端组合范围才能使不同项目共享身份。使用 portfolios create、portfolios update 和 portfolios list 创建身份组合，界定成员边界并实现隐私优先的邮箱查找范围。仅靠 data-link-domains 只能装饰链接，不能实现跨项目身份共享。除非双方均已配置，否则不可声称严格的用户转化。

基于用户同意的追踪设置策略

安装追踪或事件时，必须采用基于用户同意、由项目所有者控制的流程。不得猜测，不得过度追踪，不得安装与用户确认的产品目标或代码库中的具体流程无关的通用事件。

设置顺序如下：

1. 判断项目/表面/组合的范围。
2. 询问或提出初始项目/组合目标，并在存储持久化上下文前获得确认。
3. 若有代码库访问权限，检查路由、表单、CTA 处理器、认证/设置/结账流程、现有分析调用、服务端持久化结果及测试。
4. 如需登录，请先登录。
5. 使用 create <project> --domain <origin> 或 projects 创建或识别项目；--domain 仅为设置起点，非项目标识。
6. 添加该项目返回的精确追踪代码片段。将基础追踪代码视为埋点起点，而非完整埋点计划。
7. 仅添加满足用户确认目标所需的最小命名事件集和追踪选项。
8. 优先使用命名的 CTA 点击、注册意图、定价互动、结账进度或完成、安装/设置步骤、激活里程碑，以及服务端持久化事件如 signup_completed、subscription_started、install_completed、project_created 或 first_event_received。
9. 将需求映射到追踪能力：data-aa-event、data-aa-impression、window.aa.track(...)、服务端追踪、aa.identify(...) 和 aa.set(...)。仅在能推动具体增长决策时，才启用滚动深度、表单追踪、下载、性能/错误/指标、SPA 追踪等功能。
10. 不得重复添加自动信号的自定义事件：页面浏览、路径、来源、UTM、会话、首次访问以来天数、首次触达归因、设备/浏览器字段、国家等。
11. 解释每个事件的作用，通过 events <project> 验证首个有效事件，并总结已安装事件能让用户代理回答的问题。

可复制的设置交接语：

为该项目设置 Agent Analytics。若需浏览器授权，请打开并等待我完成登录。我将使用 Google 或 GitHub 登录并批准授权。若浏览器回调无法恢复，请向我索取完成码作为备用方案。之后创建或识别对应的 Agent Analytics 项目，请求我确认初始产品目标后再存储持久化上下文，安装项目专属追踪代码，仅添加与当前代码库产品流程和目标相关的有意义自定义事件，解释每个事件的作用，并验证首个有效事件。

产品上下文循环

使用 context get 和 context set 实现紧凑的自我改进记忆。在任何项目分析开始前，解析项目后请先运行 context get <project>。context set 会替换存储的上下文；每次更新前请先读取现有内容，合并变更，并保留仍有效的目标、激活事件、术语表条目和注释。

保持上下文简洁。保存持久化的业务真相：目标、激活定义、与 event_name 关联的事件含义，以及重大产品变更的时间标注：落地页、定价、引导、功能、发布或实验变更。更新术语表前，请先通过 properties <project> 或 properties-received <project> 检查当前事件名。

忽略噪音信息：每周指标值、临时峰值、粘贴的报告、原始笔记、长篇记录、用户列表、PII、密钥、git 提交日志和猜测。不存储 git 提交日志。不虚构不受支持的字段如 findings、learnings 或 open_questions；仅存储符合 goals、activation_events、事件名 glossary 和 annotations 的内容。

注释使用 occurred_at、title 和可选的 note。数量应极少：最多 100 条，JSON 内容不超过 512KB。分析响应中仅包含请求日期范围及其前后各一天的注释；context get 返回全部注释。对于多项目或多域名系统，除非人类明确说明，否则应保持激活和术语表独立。示例激活条件：试用注册加首个项目创建；邀请队友。这正是下一次分析更智能的起点。

分析循环

使用此闭环增长配方应对广泛问题，如激活下降点、下一步修复方向、或应运行哪个实验。此为指导原则，非僵化流程。

1. 解决认证与项目归属；全账户问题从 projects 开始。

npx --yes @agent-analytics/cli@0.5.34 context get my-site
npx --yes @agent-analytics/cli@0.5.34 funnel my-site --steps-json '[{"event":"page_view"},{"event":"signup_completed"},{"event":"first_value"}]'

1. 执行 context get <project>，将配置的激活事件视为激活的唯一真实来源。若缺失激活定义，请询问或配置，不得沉默猜测。
2. 通过 properties <project>、properties-received <project> 和近期 events <project> 发现真实情况。
3. 使用 funnel 分析有序激活流失，包括人群、窗口、步骤事件、身份基础、严格幸存者、最大绝对损失与最大相对损失。步骤或标签需精确时，优先使用 --steps-json。
4. 使用 paths 分析围绕激活目标的会话级入口、退出、绕行与流失行为；不要将路径视为长期归因。
5. 在最大流失点周围，按存在的维度进行 breakdown：路径、来源、引荐来源、CTA 标签、设备、浏览器、国家、活动、套餐、表面或引导步骤。
6. 仅在代表性检查或埋点合理性验证时使用 events 或 journey。
7. 当 sessions <project> 标记代表会话并显示 ▶ replay 时，若视觉行为可解释漏斗/路径发现，使用 replays open --session <session_id> --project <project>。将回放视为该会话的定性证据，绝非聚合证明。该命令将打开最新可播放片段，并报告是否存在更多片段。
8. 使用 retention 分析用户群组，而非混合活跃用户声明。比较同龄群组，并注意右删失期。
9. 实验读取应以业务目标事件为准，而非曝光量。在决定保留、修改、停止或完成实验时，考虑样本量、因果关系、保护机制和实际显著性。
10. 默认推荐一项狭窄实验。当追踪、激活、样本量、身份或重叠实验阻碍读取时，推荐准备就绪修复而非实验。

漏斗分析师行为：明确定义人群与转化窗口，展示数量与比率，识别主要驱动因素，检查分段/表面集中度，避免模糊的追踪建议。

组合项目表面角色诊断：识别每个项目在增长体系中的角色，再对照该角色读取项目本地指标。除非用户明确定义，否则不要在应用、文档、目录、落地页或线索获取项目间复用同一激活定义。

分析回答契约

以决策开头，再以数据证明。针对漏斗、留存、路径、实验、归因与审计，回答应遵循以下结构：

1. 最佳推测或诊断。
2. 指标定义：人群、窗口、事件名称、身份基础与转化窗口。
3. 证据：数量、比率、原始活动、严格幸存者、变化趋势与主要驱动因素。
4. 问题集中的分段、群组或表面。
5. 局限性：身份、样本量、右删失数据、归因、因果关系或追踪限制。
6. 一个明确的下一步查询或操作。

指标质疑态度：注册 ≠ 激活。优先使用留存激活用户、收入、回报率或持久价值，而非注册量。漏斗诊断泄漏，但不证明用户流失原因。未经实验或因果设计，不得将相关性当作因果。实验转化上升不代表“获胜”。添加最小事件或属性以解锁增长问题。

示例：

最佳推测：修复激活设置摩擦。
指标定义：应用引导页查看 → 设置文案点击 → 注册 → project_created → first_event_received，时间窗口为 7 天内。
证据：注册/项目活动存在，但严格幸存者在 first_event_received 前急剧下降。
局限性：跨项目身份仅在组合成员资格与 link-domain 传输配置完成后才生效。
下一步：按所选运行时拆分 setup-copy 用户，并分析其 first_event_received 情况。

参考资料路由

仅在需要时加载参考资料：

• references/setup-auth.md：登录模式、托管运行时存储、付费层级交接、安全命令示例。
• references/product-analytics-operating-model.md：项目/表面/组合、基于同意的埋点、上下文维护与验证。
• references/growth-recipes.md：AARRR、Bullseye、AIDA、STP、JTBD、4Ps、漏斗/留存/实验配方，以及可复制的提示语。

常见陷阱

• 有代码库访问权限时，不得仅依赖 URL 假设，而应检查代码。
• 不得为每个子域名、localhost URL、测试 URL 或预览创建独立项目。
• 不得为自动追踪信号安装通用点击/页面浏览重复事件。
• 不得在上下文中存储临时指标、报告、PII、密钥或 git 提交日志。
• 不得直接返回数字堆砌；必须使用分析回答契约。
• 不得仅凭注册量对渠道排序；不得声称跨项目严格用户转化