跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
数据与分析

maintaining-dbt-documentation

Audits dbt documentation coverage and drafts missing model/column descriptions in the project's own house style, one folder at a time, for human review. Use when documenting undocumented models, backfilling missing YAML descriptions, auditing doc coverage, or keeping schema YAML in sync with model SQL — especially on multi-contributor projects where new models routinely land undocumented.

dbt-labs · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add dbt-labs/dbt-agent-skills --skill maintaining-dbt-documentation

技能说明


name: maintaining-dbt-documentation description: Audits dbt documentation coverage and drafts missing model/column descriptions in the project's own house style, one folder at a time, for human review. Use when documenting undocumented models, backfilling missing YAML descriptions, auditing doc coverage, or keeping schema YAML in sync with model SQL — especially on multi-contributor projects where new models routinely land undocumented. allowed-tools: "Bash(dbt *), Bash(python3 *), Bash(git *), Read, Write, Edit, Glob, Grep" user-invocable: false metadata: author: dbt-labs

Maintaining dbt Documentation

Keep a dbt project's model and column documentation complete and consistent as it grows. This skill (1) audits which models lack YAML documentation, (2) drafts the missing descriptions in the conventions the project already uses — working one folder at a time — and (3) leaves every change for the user to review. It never commits or pushes.

Two ways it's used:

  • Backfill — document a folder of undocumented models on a project that has drifted below full coverage.
  • Keep in sync — after models are added or their SQL changes (common when many contributors are landing models), run the audit to find the gap, document just those, and re-verify.

This is the systematic, coverage-driven companion to using-dbt-for-analytics-engineering (which covers one-off model building and its references/writing-documentation.md guide). Use that skill for the content principles of a good description; use this one to find the gaps and backfill them at scale in a consistent style.

Match the project's conventions — do not impose your own

Before drafting anything, read several already-documented models and mirror what you find. dbt projects vary widely; infer and follow the local house style rather than a generic template. Determine:

  • YAML layout — one shared schema file per folder (named after the folder), one .yml per model, or a single project-wide file? Add new entries where existing ones live. Only create a new file (version: 2 + models:) if the folder has none.
  • Description mechanism — inline description: strings, or {% docs %} blocks referenced with {{ doc('...') }}? Follow whichever the project uses.
  • Description shape — do descriptions lead with grain ("One row per …")? State the primary key, key foreign keys, and upstream sources? Single-line for simple staging models vs. folded blocks (description: >) for models with caveats? Copy the observed pattern.
  • Column coverage — which columns get documented (all, vs. keys + derived only)? Match the neighbours' depth.
  • Test placement — inline tests:/data_tests:, and on which columns?

If the project has no documented models yet (greenfield), fall back to dbt best practice: grain-first model descriptions ("One row per …"), then PK, key FKs, and upstream ref()/source()s; document keys and any non-obvious/derived columns.

Workflow

  1. Audit. Generate the manifest, then run the coverage script against it. The audit reads target/manifest.json, so dbt has already resolved every description — the result is correct regardless of YAML layout or {% docs %} blocks. Keep your working directory at the dbt project root (so dbt parse writes target/manifest.json there and the script finds it), and invoke the script by its full path in the skill directory:

    dbt parse                                        # (re)generate target/manifest.json — no warehouse needed
    python3 <SKILL_BASE_DIR>/audit_coverage.py           # whole-project coverage summary (models + columns)
    python3 <SKILL_BASE_DIR>/audit_coverage.py <folder>  # one folder: undocumented models + models missing column docs
    

    Replace <SKILL_BASE_DIR> with this skill's actual base directory (the path provided when the skill is loaded); audit_coverage.py lives there, not in the project. The script reads target/manifest.json relative to your current directory, so stay at the project root. Pass --manifest <path> if the manifest is elsewhere. Prefer MCP/CLI conventions from the running-dbt-commands skill for invoking dbt (pick the right executable). dbt parse alone regenerates target/manifest.json, which is everything this audit reads — no warehouse connection needed. Column coverage therefore counts only columns declared in YAML: columns that exist in the warehouse but aren't declared yet are out of scope here (the audit reads the manifest, not the catalog). If you also want to surface those, run dbt docs generate (not --empty-catalog, which skips the warehouse and yields an empty catalog) and inspect target/catalog.json separately. If the user named a folder, go straight to it; otherwise show the summary and confirm which folder to start with (biggest gap or product area first). If the audit shows 0 gaps, report full coverage and stop.

  2. Understand each undocumented model. For every undocumented model in the folder, before writing a word:

    • Read the SQL (or Python). Identify the grain (GROUP BY / DISTINCT / window partitions / join fan-out), the primary key, and the columns actually selected.
    • Resolve every ref() and source(). Read the upstream model's existing YAML description so column meanings and wording stay consistent; reuse the upstream wording for a passed-through column.
    • Check dbt_project.yml vars and macros/ if the SQL uses them.
    • Do not guess a column's meaning from its name — trace it to its source.
  3. Draft the YAML entry in the project's conventions (see above). Keep models in a sensible order within the file (staging → intermediate → marts, matching neighbours).

  4. Write to the appropriate schema file following the project's layout.

  5. Validate. Re-run dbt parse to c

阅读完整来源 ↗