data-context-extractor

Data Context Extractor

一个元技能（meta-skill），用于从分析师处提取公司特定的数据知识，并生成量身定制的数据分析技能。

工作方式

该技能有两种模式：

1. 引导模式（Bootstrap Mode）：从零开始创建新的数据分析技能
2. 迭代模式（Iteration Mode）：通过添加特定领域的参考文件来改进现有技能

---

引导模式

适用场景：用户希望为其数据仓库创建新的数据上下文技能。

第一阶段：数据库连接与发现

第 1 步：确定数据库类型

询问："你们使用的是哪种数据仓库？"

常见选项：

• BigQuery
• Snowflake
• PostgreSQL/Redshift
• Databricks

使用 ~~data warehouse 工具（查询和 schema）进行连接。如果不确定，请检查当前会话中可用的 MCP 工具。

第 2 步：探索 schema

使用 ~~data warehouse schema 工具来：

1. 列出可用的数据集/schema
2. 确定最重要的表（询问用户："分析师最常查询的 3-5 张表是哪些？"）
3. 提取这些关键表的 schema 详情

按方言划分的示例探索查询：

-- BigQuery: List datasets
SELECT schema_name FROM INFORMATION_SCHEMA.SCHEMATA

-- BigQuery: List tables in a dataset
SELECT table_name FROM `project.dataset.INFORMATION_SCHEMA.TABLES`

-- Snowflake: List schemas
SHOW SCHEMAS IN DATABASE my_database

-- Snowflake: List tables
SHOW TABLES IN SCHEMA my_schema

第二阶段：核心问题（需提问）

完成 schema 发现后，以对话形式逐一提问（不要一次全部抛出）：

实体消歧（至关重要）

"大家说'用户'或'客户'时，具体指的是什么？是否存在不同类型？"

需要关注：

• 多种实体类型（用户 vs 账户 vs 组织）
• 它们之间的关系（1:1、1:多、多:多）
• 哪些 ID 字段将它们关联起来

主标识符

"一个[客户/用户/账户]的主标识符是什么？同一实体是否有多个 ID？"

需要关注：

• 主键 vs 业务键
• UUID 与整数 ID
• 遗留 ID 系统

关键指标

"人们最常询问的 2-3 个指标是什么？每个指标如何计算？"

需要关注：

• 精确公式（ARR = monthly_revenue × 12）
• 每个指标依赖哪些表/列
• 时间周期约定（最近 7 天、自然月等）

数据清洗

"查询时哪些内容必须始终过滤掉？（测试数据、欺诈、内部用户等）"

需要关注：

• 必须始终包含的标准 WHERE 子句
• 表示排除的标记列（is_test、is_internal、is_fraud）
• 需要排除的特定值（status = 'deleted'）

常见陷阱

"新分析师在使用这些数据时通常会犯哪些错误？"

需要关注：

• 容易混淆的列名
• 时区问题
• NULL 值处理的特殊情况
• 历史表与当前状态表的区别

第三阶段：生成技能

按以下结构创建技能：

[company]-data-analyst/
├── SKILL.md
└── references/
    ├── entities.md          # Entity definitions and relationships
    ├── metrics.md           # KPI calculations
    ├── tables/              # One file per domain
    │   ├── [domain1].md
    │   └── [domain2].md
    └── dashboards.json      # Optional: existing dashboards catalog

SKILL.md 模板：参见 references/skill-template.md

SQL 方言部分：参见 references/sql-dialects.md，并加入适用的方言说明。

参考文件模板：参见 references/domain-template.md

第四阶段：打包与交付

1. 在技能目录中创建所有文件
2. 打包为 zip 文件
3. 向用户展示，并总结所获取的内容

---

迭代模式

适用场景：用户已有技能，但需要补充更多上下文。

第 1 步：加载现有技能

请用户上传其现有技能（zip 或文件夹），或者如果已在会话中，则直接定位该技能。

阅读当前的 SKILL.md 和参考文件，了解已记录的内容。

第 2 步：识别缺口

询问："哪个领域或主题需要更多上下文？哪些查询失败或产生了错误结果？"

常见缺口：

• 新的数据领域（营销、财务、产品等）
• 缺失的指标定义
• 未记录的表关系
• 新术语

第 3 步：有针对性的发现

针对已识别的领域：

1. 探索相关表：使用 ~~data warehouse schema 工具查找该领域的表

2. 询问领域相关问题：

   • "[领域]分析使用哪些表？"
   • "[领域]的关键指标有哪些？"
   • "处理[领域]数据时有哪些特殊过滤条件或陷阱？"

3. 生成新的参考文件：使用领域模板创建 references/[domain].md

第 4 步：更新并重新打包

1. 添加新的参考文件
2. 更新 SKILL.md 中的「知识库导航」部分，加入新的领域
3. 重新打包 Skill
4. 向用户展示更新后的 Skill

---

参考文件规范

每个参考文件应包含以下内容：

表格文档

• 位置：完整的表格路径
• 描述：该表包含什么内容，何时使用
• 主键：如何唯一标识行
• 更新频率：数据多久刷新一次
• 关键列：包含列名、类型、描述、备注的表格
• 关联关系：该表如何与其他表进行连接
• 示例查询：2-3 个常见查询模式

指标文档

• 指标名称：便于阅读的名称
• 定义：用通俗语言解释
• 公式：带列引用的精确计算方式
• 来源表：数据来自哪里
• 注意事项：边界情况、排除项、易错点

实体文档

• 实体名称：其名称
• 定义：它在业务中代表什么
• 主表：在哪里可以找到该实体
• ID 字段：如何标识它
• 关联关系：它与其他实体的关系
• 常用过滤条件：标准排除项（内部、测试等）

---

质量检查清单

交付生成的 Skill 之前，请确认：

• SKILL.md 包含完整的 frontmatter（name、description）
• 实体消歧部分清晰明确
• 关键术语已定义
• 标准过滤条件/排除项已记录
• 每个领域至少有 2-3 个示例查询
• SQL 使用正确的方言语法
• 参考文件已从 SKILL.md 导航部分链接