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.

4. Validate

altimate-dbt compile --model <name>    # ensure YAML is valid

Common Mistakes

Mistake	Fix
Restating the column name as the description	"order_id: The order ID" → describe business meaning
Empty descriptions	Every column should have a description. If unsure, describe the source.
Not reading the SQL before documenting	Read the model to understand derivation logic
Duplicating descriptions across models	Use doc blocks for shared definitions
Writing implementation details instead of business context	Describe what it means to the business, not how it's computed

Reference Guides

Guide	Use When
references/altimate-dbt-commands.md	Need the full CLI reference
references/documentation-standards.md	Writing high-quality descriptions