Skip to main content
This agent automatically keeps your dbt model documentation synchronized with code and data changes. When a model is modified in a pull request, the agent profiles the model in your warehouse, updates the YAML documentation to reflect the current structure, validates the changes, and commits the updated docs directly to the PR.

​
Simple Example

name: docs-updater
description: Auto-update model documentation on PRs

triggers:
  - type: pull_request
    on_changed_files: "models/**/*.sql"

tools:
  preset: standard  # Needs write access

prompt: |
  When a model changes:
  1. Profile the model (row count, columns, types)
  2. Update the YAML file with current structure
  3. Run dbt parse to validate
  4. If valid: commit changes
  5. If invalid: comment with error

​
More Robust Example

Production-ready with full profiling and documentation standards: 
name: docs-updater
description: Keep model documentation synchronized with code and data

triggers:
  - type: pull_request
    on_changed_files: "models/**/*.sql"
    branches: ["main", "staging"]

tools:
  preset: standard  # Can read, write, run SQL

restrictions:
  files:
    allow: ["models/", "macros/"]

prompt: |
  For each changed model in this PR:
  
  ## 1. Detect change type
  - New model (no existing YAML): Generate full docs
  - Existing model: Update only what changed
  - Deleted model: Remove YAML (if exists)
  
  ## 2. Profile the model
  Use the warehouse to get:
  - Total row count (approximate is fine)
  - Column list with data types
  - Null percentage per column
  - For categoricals (<20 unique): list common values
  - For numerics: typical range (min/max/median)
  
  ## 3. Generate/update documentation
  Follow our standards:
  - Model description: Include purpose, grain, ~row count
  - Column descriptions: Business meaning + data type
  - Note null rates if > 5%
  - Use sentence case, end with period
  - Preserve any existing descriptions that are still accurate
  
  ## 4. Validate
  Run `dbt parse` to check YAML syntax.
  
  ## 5. Take action based on result
  If validation passes:
    - Commit changes to PR branch
    - Add comment: "📝 Updated docs for [model_names]"
  
  If validation fails:
    - Do NOT commit
    - Comment on PR with validation error
    - Suggest fix if possible
  
  ## 6. Summary
  At the end, comment with:
  - How many models were documented
  - How many columns were described
  - Any issues encountered