dbt-docs

dbt Documentation

Requirements

Agent: builder or migrator (requires file write access) Tools used: bash (runs altimate-dbt commands), read, glob, write, edit

When to Use This Skill

Use when the user wants to:

• Add or improve model descriptions in schema.yml
• Write column-level descriptions with business context
• Create shared doc blocks for reusable definitions
• Improve dbt docs site content

Do NOT use for:

• Adding tests → use dbt-test
• Creating new models → use dbt-develop
• Generating sources.yml from scratch → use dbt-develop

Workflow

1. Understand the Model

altimate-dbt columns --model <name>                    # what columns exist
altimate-dbt parents --model <name>                    # what feeds this model
altimate-dbt children --model <name>                   # who consumes it
altimate-dbt compile --model <name>                    # see the rendered SQL

Read the model SQL to understand the transformations:

glob models/**/<name>.sql
read <model_file>

2. Read Existing Documentation

Check what's already documented:

glob models/**/*schema*.yml models/**/*_models.yml
read <yaml_file>

3. Write Documentation

See references/documentation-standards.md for quality guidelines.

Model-Level Description

Cover: What (business entity), Why (use case), How (key transforms), When (materialization).

- name: fct_daily_revenue
  description: >
    Daily revenue aggregation by product category. Joins staged orders with
    product dimensions and calculates gross/net revenue. Materialized as
    incremental with unique key on (date_day, category_id). Used by the
    finance team for daily P&L reporting.

Column-Level Description

Describe business meaning, derivation formula, and caveats:

columns:
  - name: net_revenue
    description: >
      Total revenue minus refunds and discounts for the day.
      Formula: gross_revenue - refund_amount - discount_amount.
      Can be negative if refunds exceed sales.