data-quality-frameworks

data-quality-frameworks 技能概览

data-quality-frameworks 技能能做什么

data-quality-frameworks skill 用来帮助智能体基于三种常见方式设计实用的数据质量校验：dbt tests、Great Expectations 和 data contracts。它适合那些不满足于一句模糊“加点数据检查”提示的团队，想要用更结构化的方法判断该测什么、在哪里测，以及如何把这些检查真正落到 pipeline 和 CI/CD 里。

谁适合使用 data-quality-frameworks

这个 skill 最适合为表、模型和 pipeline 接口建立可复用质量控制的数据工程师、分析工程师、平台团队和技术负责人。尤其当你需要在生产环境中使用 data-quality-frameworks for Data Cleaning，而不是只做一次性的探索式清洗时，它会特别有价值。

它真正解决的是什么问题

用户通常不是只想知道一个框架名，而是想回答这类实际问题：

• 这个数据集最关键的数据质量维度是什么？
• 这个检查应该写在 SQL、dbt、Great Expectations 还是 contract 里？
• 上生产前，最小可行测试集应该包含哪些内容？
• 如何防止 schema drift 和上游错误变更？

当目标是把业务层面对可靠性的要求翻译成具体、可执行的校验模式时，data-quality-frameworks skill 的价值最大。

它和普通提示词相比有什么不同

仓库里的内容更偏“如何做决策”，而不是“如何做自动化”。它提供了一套可复用的思考框架，核心围绕：

• 核心数据质量维度
• 面向数据的 testing pyramid
• 在 dbt、Great Expectations 和 contracts 之间做框架选择
• 面向生产的使用场景，比如 CI/CD 和监控

因此，它比泛泛的“写几个数据检查”提示更有用；但同时它也要求你提供自己的技术栈、schema 和失败阈值。

安装前你需要知道什么

这是一个纯文本 skill，指导内容都在 SKILL.md 里。skill 文件夹中没有 helper scripts、templates 或 reference files。因为几乎不用额外配置，上手门槛很低；但输出质量会高度依赖你提供的输入。如果你希望在不提供表结构细节的情况下，直接拿到可复制粘贴的配置，这个 skill 会显得不够完整。

如何使用 data-quality-frameworks skill

data-quality-frameworks 的安装背景

从 wshobson/agents 仓库安装这个 skill：

npx skills add https://github.com/wshobson/agents --skill data-quality-frameworks

由于这个 skill 本身只有一个 SKILL.md，skill 内部不需要额外的本地 package 配置。真正的准备工作在你自己的环境里：dbt、Great Expectations、数仓访问权限，以及你使用的任何 CI runner。

先读这个文件

从这里开始：

• plugins/data-engineering/skills/data-quality-frameworks/SKILL.md

因为没有额外的 README、resources 或 scripts，最快的阅读路径是：

1. When to Use This Skill
2. Core Concepts
3. testing pyramid 和 framework patterns 相关章节
4. code block 里的任何实现示例

这是一个篇幅不长的 skill，所以真正的收益不在于深挖仓库，而在于配合精确 prompt 来使用。

这个 skill 需要你提供哪些输入

想获得高质量的 data-quality-frameworks usage，请尽量向智能体提供：

• dataset 或 model 名称
• 带类型的列清单
• 预期 grain 或 primary key
• freshness 预期
• 合法取值范围或 enums
• nullable 与 required 字段区分
• 已知的 upstream/downstream 依赖
• 检查应运行的位置：ingestion、transform、publish 或 contract boundary
• 失败处理策略：warn、fail job、quarantine、alert

如果没有这些信息，智能体通常只能返回一些泛化示例，比如唯一性、空值和范围检查。

如何把模糊目标变成高质量 prompt

弱 prompt：

Help me add data quality checks.

更好的 prompt：

Use the data-quality-frameworks skill to design a validation plan for our orders pipeline. Source is raw event data loaded to BigQuery, transformed with dbt. Key fields: order_id, customer_id, order_status, order_total, created_at, updated_at. order_id must be unique at the mart layer. order_status must be one of pending, paid, shipped, cancelled, refunded. order_total must be >= 0. Freshness target is under 2 hours. We want: 1) source-level checks, 2) dbt tests, 3) any checks that fit Great Expectations, 4) a simple data contract for upstream producers, and 5) CI/CD recommendations with fail-vs-warn guidance.

这个 prompt 之所以有效，是因为它给了 skill 足够的上下文，能够把需求映射到合适的框架上。

如何要求合适的输出格式

建议让智能体分层输出：

1. 按 dataset 列出质量维度
2. 标明 testing pyramid 所在层级
3. 给出具体 framework mapping
4. 提供 sample test definitions
5. 给出 rollout order

例如：

Using the data-quality-frameworks guide, return a table with columns: check, dimension, layer, framework, severity, reason. Then generate sample dbt tests and Great Expectations expectations only for the highest-value checks.

这样可以减少过度设计，让第一版结果更聚焦于可实施性。

data-quality-frameworks 的实用工作流

一个比较好的工作流是：

1. 盘点关键 datasets。
2. 确认 grain 和 contract surface。
3. 按质量维度给检查项分类。
4. 把每个检查放进 testing pyramid。
5. 为每个检查分配到 dbt、Great Expectations 或 data contract。
6. 决定哪些检查会阻断部署，哪些只做告警。
7. 先实现最小但可靠的一组检查。

这个 skill 更擅长系统设计和校验规划，而不是暴力生成“所有可能的测试”。

什么时候用 dbt、Great Expectations 或 contracts

使用这个 skill 的一个关键价值，就是帮你把职责边界拆清楚：

• dbt 适合模型层断言，比如唯一性、非空、合法取值和 relationship tests。
• Great Expectations 适合更丰富的校验工作流、类似 profiling 的 expectations，以及围绕 pipeline 各阶段的运行时校验。
• Data contracts 适合生产者—消费者之间的约定，比如 schema shape、required fields，以及边界上的语义保证。

一个常见误区是试图让一个工具包办所有事情。只有在你让每种框架负责它最自然的层级时，data-quality-frameworks skill 才最有帮助。

testing pyramid 在实践中意味着什么

这个 skill 里的 testing pyramid 非常适合拿来做优先级排序。落到实践中，一般意味着：

• 在底层放大量成本低的结构性检查
• 在高层补充较少但更复杂的跨表和业务规则检查
• 只把昂贵的端到端校验留给最关键的路径

如果你的第一版方案里全是复杂业务断言，却没有基本的空值、唯一性、schema 或 freshness 检查，很可能跳过了 ROI 最高的那一层。

这个 skill 在 Data Cleaning 场景下擅长什么

对于 data-quality-frameworks for Data Cleaning，这个 skill 最适合用来定义“清洗逻辑上线之后，如何持续校验”。它能帮助你回答：

• 哪些脏数据输入应该被直接拦截
• 哪些值应该被标准化
• 哪些异常应触发人工复核，而不是让 pipeline 失败
• 如何确保清洗后的输出长期保持符合规范

它更关注的不是清洗转换本身，而是如何证明这些转换产出的结果值得信任。

约束与落地取舍

这个 skill 的安装阻力很低，但内置的实现资产也比较有限。你需要自己把它的建议翻译到项目文件里，例如：

• models/*.yml 用于 dbt
• expectation suites 或 checkpoints 用于 Great Expectations
• 按你偏好的 schema 格式编写 contract 文档

如果你需要的是一个自带现成模板的仓库，这个 skill 会显得更轻量。它的价值在于帮助智能体正确推理，而不是直接提供一个开箱即用的 starter kit。

data-quality-frameworks skill 常见问题

data-quality-frameworks 适合初学者吗？

适合，但前提是你已经理解表、列和 pipeline 这些基础概念。这里的核心内容并不难：质量维度、测试分层和框架选择都比较容易上手。但如果你是完全的新手，可能仍然需要另外查阅 dbt 或 Great Expectations 的语法文档，因为这个 skill 并不是任一工具的完整教程。

它比普通 prompt 更好吗？

大多数情况下是的，尤其当你的问题核心在于“框架怎么选、测试策略怎么定”时。普通 prompt 往往会随机生成一些检查项；而 data-quality-frameworks skill 会给智能体一套更有纪律性的结构：维度、pyramid 和框架适配。这通常意味着更少无关测试。

它的主要限制是什么？

这个 skill 不包含 helper files、implementation templates 或面向具体项目的 adapters。除非你明确提供，否则它无法推断你的数仓语义、SLA 或业务规则。最终结果的质量，会和 prompt 的具体程度强相关。

什么情况下不该用 data-quality-frameworks？

如果你只是想给单个 CSV 写一条简单检查，或者快速做一个 ad hoc cleanup script，那就没必要用它。如果你的团队已经完全标准化在某一个框架上，只需要语法片段，而不需要设计指导，它的匹配度也不会太高。

我可以只用 dbt 配合 data-quality-frameworks 吗？

可以。虽然这个 skill 会提到多个框架，但你完全可以要求它把建议限制在 dbt 范围内。如果你的团队更偏好 Great Expectations，或者想先聚焦 data contracts，也一样适用。

它能帮助做 CI/CD 决策吗？

能。源 skill 里比较清晰的一个使用场景，就是在 CI/CD 中自动化数据校验。你可以明确要求它区分：哪些检查应该让 pull request 失败，哪些应在 deploy 后运行，哪些只需要发出告警。这个区分会显著提高输出的实用性。

如何改进 data-quality-frameworks skill 的使用效果

给智能体提供数据语义，不要只给 schema

提升 data-quality-frameworks 结果质量最快的方法，是补充“字段含义”，而不只是列名。例如：

• “customer_id can be null for guest checkout”
• “revenue_amount should never be negative except for refunds”
• “status values are controlled by the application enum”

这些细节会让智能体更容易给出贴近实际的有效性和一致性检查，而不是泛泛而谈。

把关键检查和可选检查分开

告诉智能体哪些失败会阻断生产。比如：

Tier 1: schema drift, null primary keys, duplicate business keys.
Tier 2: freshness breaches over 2 hours.
Tier 3: soft anomaly detection on distribution shifts.

这样这个 skill 产出的就会是一套团队真正能落地的方案，而不是一个永远排不完的长 backlog。

不要只要平铺列表，要它输出 framework mapping

一个常见失败模式，是拿到 30 条检查项，却没有实现路径。要改进 prompt，可以要求每条检查都包含：

• dimension
• layer
• framework
• severity
• owner

这样一来，data-quality-frameworks guide 输出的就不只是想法清单，而是可执行计划。

提供 sample rows 和已知坏例子

如果你想获得更好的 data-quality-frameworks usage，请同时提供合法数据和非法数据的示例。已知失败样例尤其有助于智能体更精准地定义规则，尤其是在这些方面：

• 边界场景下的 nullability
• 日期先后顺序
• enum drift
• duplicate logic
• 不可能出现的取值组合

很多时候，真实的坏案例比一份完美 schema 更有信息量。

第一版输出后继续迭代

不要停在第一次生成的方案上。继续追问类似问题：

• “Which 5 tests give the highest reliability per hour of work?”
• “Which recommendations belong in dbt versus contracts?”
• “Which checks are likely too expensive for every run?”
• “Rewrite this for BigQuery and incremental models.”

把 data-quality-frameworks skill 当成一个收敛工具，连续迭代两三轮，结果通常会明显更好。

留意常见的过度设计错误

最常见的问题包括：

• 一上来就做昂贵的端到端断言
• 把 profiling 当成硬性保障的替代品
• 混淆 data cleaning logic 和 validation logic
• 每个异常都直接 fail job，导致告警疲劳
• 写了测试，却没有明确 owner 或 remediation path

如果你让智能体按 cost、confidence 和 operational impact 给检查排序，输出通常会更适合实际部署。

让它给出分阶段 rollout plan

一个很有效的改进型 prompt 是：

Using data-quality-frameworks, create a 30/60/90-day rollout: immediate checks, next-layer business assertions, and longer-term contract governance.

这样可以避免团队试图一次性把所有框架全上齐。多数情况下，更好的路径是先上基础 dbt tests，再补有针对性的 Great Expectations，最后在团队边界上逐步建立更完整的 contract discipline。