dbt-agent-readiness
Audit a dbt project for agent-readiness: what would an AI agent get wrong if you pointed it at this data today? Produces a prioritized report organized by failure modes (wrong numbers, wrong table, wrong column, can't join, query fails). Scales via two-pass architecture with parallel subagents. Each subagent reads its own phase instruction file, keeping context tight. Use when asked to "audit", "agent-readiness", "scan dbt project", "check data quality", "how ready is my data for AI agents", or "run dbt-agent-readiness."
GetCassis · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add GetCassis/dbt-agent-readiness --skill dbt-agent-readiness技能说明
name: dbt-agent-readiness description: | Audit a dbt project for agent-readiness: what would an AI agent get wrong if you pointed it at this data today? Produces a prioritized report organized by failure modes (wrong numbers, wrong table, wrong column, can't join, query fails). Scales via two-pass architecture with parallel subagents. Each subagent reads its own phase instruction file, keeping context tight. Use when asked to "audit", "agent-readiness", "scan dbt project", "check data quality", "how ready is my data for AI agents", or "run dbt-agent-readiness." argument-hint: "[path/to/dbt/project]" allowed-tools:
- Bash
- Glob
- Read
- Grep
- Write
- AskUserQuestion
- Agent
dbt-agent-readiness (orchestrator)
Target project path: $0 (or current directory if not specified)
This file orchestrates the audit. Phase instructions live in phases/ files. Each subagent reads only its own phase file. The orchestrator passes structured JSON between phases.
Design principles
The audit is framed around what an agent actually hits (code evidence) vs what an audit can only forecast (missing tests, unenforced relationships). Findings that require querying the warehouse to confirm (duplicates, orphans, bad data) are not reported as facts.
- Report split into Blockers vs Hygiene. Blockers require code evidence (scope divergence, copy-paste descriptions, broken refs, polymorphic columns, within-model collisions, unit mismatch, measure/agg mismatch, high-confidence phantom columns). Hygiene lists missing tests and unenforced relationships, each with a runnable verification query the user can run in ten minutes to confirm or dismiss.
- Broken refs always Blocker #1.
issues.broken_refsis the most evidence-backed possible finding: the query fails at compile time. Exception: when the project declares package or extension deps (packages.yml/dependencies.yml) that are not installed (dbt_packages/absent) and there is no compiled manifest, unresolved refs are package models or user-supplied extension points, not broken refs. They move toissues.broken_refs_suppressed_no_depsand synthesis emits one aggregate "rundbt deps(thendbt compile)" notice instead of per-ref Blockers (packages_unresolvedis true). - Phantom columns suppressed when evidence is weak. If a model uses
dbt_utils.star,SELECT *that can't be resolved, or Jinja for-loops, and no compiled manifest is present, the phantom finding is not emitted. It goes tocatalogs.phantom_columns_suppressed_no_manifestinstead. Synthesis emits one aggregate "rundbt compile" notice rather than per-modelprovisionalrows. All rows inphantom_columns_by_modelcarryconfidence: 'high'and are evidence-backed. - Phantom columns traced through multi-hop CTEs and column lineage.
_extract_columns_via_sqlglotresolves CTE output columns recursively (depth 10), so a YAML column that survives throughbase -> mid -> topis not flagged phantom. When the simple YAML-vs-SQL diff still flags something,cross_referenceretries viasqlglot.lineage.lineage; resolved findings land incatalogs.phantom_columns_resolved_by_lineagerather thanphantom_columns. Unit / currency drift candidates (col * 100,col / 100.0, etc.) are collected intocatalogs.potential_unit_driftfor synthesis to treat as Blocker candidates when the description doesn't call out the conversion. catalogs.description_contradicts_sqlcatches three high-signal failure modes deterministically: copy-paste descriptions, scope contradictions ("toutes les lignes" + non-trivial WHERE), and measure/agg mismatches ("count of customers" +SUM(...)).catalogs.undefined_column_refsmakes the worst query-fails bug deterministic: for every model, each SELECT scope (outer query + CTEs) is resolved against its input relations (CTEs recursively, ref'd models through their extracted columns); a column referenced in SELECT or GROUP BY that no input produces is flagged withconfidence: 'high'. Scopes with any unresolvable input (macros, regex-fallback upstreams, sources) are skipped rather than guessed at. Constructs that produce columns no input relation lists are handled so they never read as undefined: SQL date-part tokens insideDATEADD/DATEDIFF/DATE_TRUNC(day,month,quarter...),UNPIVOTvalue/name outputs, lateral table-function system columns (SPLIT_TO_TABLE->value), andfivetran_utils.fill_staging_columnsstyle macro column sets. Aref()always resolves to the model, never a same-named sibling CTE. Without a compiled manifest these checks stay conservative by construction (verified against real Snowflake projects: GitLab, Stripe, Mattermost).catalogs.fan_out_joinsdeterministically flags models joined by 2+ downstream models on a key with no uniqueness guarantee, each with a runnable verification query. A guarantee is a column-leveluniquetest, the tested PK, or adbt_utils.unique_combination_of_columnstuple (read from inline tests and from YAML anchor aliases). A join on the whole tuple or a superset is not flagged; a join on a strict subset still can fan out and stays flagged.catalogs.effective_description_coveragereports raw vs effective coverage. Effective = raw minus weak / phantom-documented / contradicts-SQL columns. The gap is the share of docs an agent cannot trust.- Severity, grain-declared, and zero-tests are not root issues. Severity gets one line under Hygiene; grain-declared is informational unless the description is also silent on cardinality; zero-tests is appendix-only.
- "Safe today" criteria. No Blocker flags, key columns agent-ready, no high-confidence phantoms, either has a PK test OR has 0 inbound refs, not a staging-only alternative to a core model. Grain qualifies via description text ("one row per customer per day") even without
meta.grain:.
The script-generated review queue drives the flag-driven
阅读完整来源 ↗