Data Analysis

数据分析技能

标准化数据分析工作流，确保分析高效、结果可靠、输出规范。

激活条件

• 用户需要查询数据库并分析数据
• 用户需要生成数据分析报告
• 涉及"数据分析"、"统计"、"报告"、"洞察"等关键词

核心约束

1. 时区处理

首次分析时确认数据库时区设定，常见情况：

| 存储时区 | 查询处理 | 展示处理 | | -------- | -------------- | -------------- | | UTC | 查询条件转 UTC | 结果转本地时区 | | 本地时区 | 直接使用 | 直接展示 | | 时间戳 | 按需转换 | 转本地时区 |

确认后记录到对应的 schema 文件中，后续分析直接参考。

2. 输出规范

{workspace}/analysis-output/{topic}_{YYYYMMDD_HHmmss}/
├── raw_data/           # 原始查询结果（仅复杂场景）
├── processed_data/     # 计算后的分析数据（JSON格式，供HTML读取）
│   └── charts_data.json
├── report.md           # Markdown 报告
└── report.html         # 可视化报告（幻灯片样式）

3. 数据处理原则

• 禁止将大量原始数据读入对话上下文
• 优先通过 SQL 聚合直接得出统计结果
• 仅当数据量大或查询复杂时，才落地本地用代码处理

工作流程

Step 1: 需求理解与 Schema 获取

1. 识别分析主题、时间范围、关注维度
2. 查看 schemas/ 是否有对应表结构，无则通过工具获取并保存
3. 确定查询范围：哪些表、哪些字段、什么条件

Schema 文件: schemas/{source}_{name}.md

Step 2: 设计分析方案

根据数据特点选择分析维度（参考 references/analysis_perspectives.md）：

• 描述性分析：规模、分布、集中趋势、离散程度
• 时序分析：趋势、周期、同环比
• 对比分析：分群、分类、交叉对比
• 关联分析：相关性、因果推断
• 异常分析：离群值、突变点

输出简要分析方案后再执行查询。

Step 3: 数据查询与计算

可用工具参考 dbtool/README.md，根据用户指定或默认使用 MySQL。

策略选择

简单场景（优先）：直接用 SQL 聚合

-- 通过 GROUP BY、COUNT、SUM、AVG 等直接得出统计结果
-- 多个统计需求可并行发起多条查询
SELECT DATE(created_at) as date, COUNT(*) as count FROM table GROUP BY date;

复杂场景（降级）：当遇到以下情况时，才落地本地处理

• 查询超时
• 需要跨表复杂计算
• 数据量过大无法一次返回
• SQL 难以表达的统计逻辑

1. 查询原始数据保存到 raw_data/
2. 在输出目录编写 Node.js 脚本处理
3. 结果保存到 processed_data/charts_data.json

Step 4: 生成报告

Markdown 报告（参考 templates/report_template.md）：

• 执行摘要：核心发现 + 关键指标
• 详细分析：按维度展开
• 洞察建议：结论 + 行动项
• 附录：数据说明 + 计算口径

HTML 幻灯片报告（参考 templates/visualization_template.html）：

技术栈：

• Reveal.js：幻灯片框架，支持键盘翻页、过渡动画、演讲者模式（按 S 键）
• Tailwind CSS：原子化 CSS，直接用类名布局
• ECharts：图表引擎，暗金色主题
• Animate.css：元素入场动画（配合 fragment）
• Remix Icon：图标库

设计规范：

• 暗金色主题（#0f0f1a 背景 + #d4af37 金色）
• 每页一个观点 + 图表 + 洞察说明
• 数据必须从 processed_data/charts_data.json 读取，禁止硬编码

Step 5: 质量检查

• [ ] 时区处理正确
• [ ] 数据可追溯
• [ ] 结论有数据支撑
• [ ] 输出文件完整
• [ ] HTML 数据从文件加载

Step 6: 更新报告索引

报告生成完成后，执行索引生成脚本，更新报告中心：

node .claude/skills/data-analysis/scripts/generate_index.mjs

提示用户查看报告：

报告已生成！使用以下命令启动服务查看：

npm run serve

然后访问 http://localhost:3000/ 查看报告中心

Step 7: 持续改进（必做）

⚠️ 每次任务完成后，必须执行此步骤：

检查本次分析过程中发现的可改进项，更新到对应文件：

| 发现类型 | 更新目标 | | ------------------ | ------------------------------------- | | 新的表结构 | schemas/{source}_{name}.md | | 有效的分析方法 | references/analysis_perspectives.md | | 常见问题及解决方案 | 本文件"问题处理"章节 | | 模板优化建议 | templates/ 下对应文件 |

当前 Skill 是动态迭代的，保持其新鲜度是工作流的一部分。

---

问题处理

| 问题 | 方案 | | ----------- | ---------------------------------------- | | 查询超时 | 缩小范围/拆分查询/落地本地处理 | | 数据量大 | SQL 聚合优先，必要时采样或分批 | | Schema 不明 | describe_table + 样本查询 | | 工具不通 | 检查 MCP Server 配置，告知用户后结束任务 |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shanggqm
• Source: shanggqm/data-insight-agent
• License: MIT

Install and usage instructions live in the source repository linked above.