New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

dbt Model Documentation

by AltimateAI in AltimateAI/data-engineering-skills

Writes model and column descriptions in dbt schema.yml files, matching the project's existing documentation style and recording grain, business rules and caveats.

MITAuto-check passedData & Analytics

Install dbt Model Documentation

skills CLI
$ npx skills add AltimateAI/data-engineering-skills --skill documenting-dbt-models -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install AltimateAI/data-engineering-skills documenting-dbt-models --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/AltimateAI/data-engineering-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/dbt/documenting-dbt-models .claude/skills/documenting-dbt-models && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
documenting-dbt-models
GitHub stars
128
Token cost
~1.2k tokens
SKILL.md length
255 words
Files
1
Skills in repo
12
Repo updated
First seen
Licence
MIT

At a glance

Writes model and column descriptions in dbt schema.yml files, matching the project's existing documentation style and recording grain, business rules and caveats.

  • Works in 6 steps: Study Existing Documentation Patterns → Read Model SQL → Check Existing Documentation for This… → …
  • Adding model descriptions and column definitions to schema.yml
  • SKILL.md covers Workflow, Documentation Patterns and Anti-Patterns
  • Calls dbt

What it does

Existing documentation conventions come first: how long descriptions are, whether they use plain text or markdown, whether they mention grain, rules and caveats, how deep column coverage goes, and whether meta tags appear. The agent then reads the model's SQL to understand transformations, joins and filters, and checks whether the model already has an entry in a schema.yml.

Descriptions cover purpose, grain and key business rules for the model, and business meaning for columns instead of data types. Column patterns differ by kind: primary keys note the source and uniqueness, foreign keys what they join to and how nulls behave, metrics their formula and units, dates their timezone and event, and flags what true and false mean. It finishes with dbt docs generate, optionally dbt docs serve, and warns against writing docs without checking local conventions.

When your agent uses it

  • Adding model descriptions and column definitions to schema.yml
  • Explaining the grain and business rules of a dbt model
  • Improving model discoverability before running dbt docs generate

Example prompts

  • “Document the fct_orders model in schema.yml, including its grain and business rules.”
  • “Add column descriptions to the customers staging model in the same style as our other docs.”

Requirements

  • A dbt project with schema.yml files
  • dbt installed to generate docs

Workflow steps

6 steps, taken from the step headings in SKILL.md.

  1. Study Existing Documentation Patterns
  2. Read Model SQL
  3. Check Existing Documentation for This Model
  4. Identify Documentation Needs
  5. Write Documentation
  6. Generate Docs

What it can do on your machine

Read from SKILL.md and the folder at commit 705c68b. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • dbt

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

dbt Model Documentation loads about 1.2k tokens when it runs. Until then it costs about 121 tokens; SKILL.md has 255 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~121
When it runs · the whole SKILL.md, loaded when a task matches
~1.2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from AltimateAI/data-engineering-skills at commit 705c68b, republished under its MIT licence (© AltimateAI). 255 words, ~1,166 tokens.

Download SKILL.mdSave it as .claude/skills/documenting-dbt-models/SKILL.md (or your agent's skills folder).
name
documenting-dbt-models
description
Documents dbt models and columns in schema.yml. Use when working with dbt documentation for: (1) Adding model descriptions or column definitions to schema.yml (2) Task mentions "document", "describe", "description", "dbt docs", or "schema.yml" (3) Explaining business context, grain, meaning of data, or business rules (4) Preparing dbt docs generate or improving model discoverability Matches existing project documentation style and conventions before writing.

dbt Documentation

Document the WHY, not just the WHAT. Include grain, business rules, and caveats.

Workflow

1. Study Existing Documentation Patterns

CRITICAL: Match the project's documentation style before adding new docs.

bash
# Find all schema.yml files with documentation
find . -name "schema.yml" | head -5

# Read well-documented models to learn patterns
cat models/marts/schema.yml | head -150
cat models/staging/schema.yml | head -150

Extract from existing documentation:

  • Description length (brief vs detailed)
  • Formatting style (plain text vs markdown with headers)
  • Information included (grain? business rules? caveats?)
  • Column description depth (all columns vs key columns)
  • Use of meta tags or custom properties
2. Read Model SQL
bash
cat models/<path>/<model_name>.sql

Understand: transformations, business logic, joins, filters.

3. Check Existing Documentation for This Model
bash
# Find existing schema.yml
find . -name "schema.yml" -exec grep -l "<model_name>" {} \;

# Read existing docs
cat models/<path>/schema.yml | grep -A 100 "<model_name>"
4. Identify Documentation Needs

For each model, document:

  • Model description: Purpose, grain, key business rules
  • Column descriptions: Business meaning, not just data type

For each column, consider:

  • What business concept does this represent?
  • Are there any caveats or special values?
  • What is the source of this data?
5. Write Documentation

Match the style discovered in step 1. Example format (adapt to project):

yaml
version: 2

models:
  - name: orders
    description: |
      Order transactions at the order line item grain.
      Each row represents one product in one order.

      **Business Rules:**
      - Revenue recognized on ship_date, not order_date
      - Cancelled orders excluded (status != 'cancelled')
      - Returns processed as negative line items

      **Grain:** One row per order_id + product_id combination

    columns:
      - name: order_id
        description: |
          Unique identifier for the order.
          Source: orders.id from Stripe webhook

      - name: customer_id
        description: |
          Foreign key to customers table.
          NULL for guest checkouts (pre-2023 only)

      - name: revenue
        description: |
          Net revenue for this line item in USD.
          Calculation: unit_price * quantity - discount_amount
          Excludes tax and shipping

      - name: order_status
        description: |
          Current status of the order.
          Values: pending, processing, shipped, delivered, cancelled, returned
6. Generate Docs
bash
dbt docs generate
dbt docs serve  # Optional: preview locally

Documentation Patterns

Note: These are default templates. Always adapt to match project's existing style.

Model Description Template
yaml
description: |
  [One sentence: what this model contains]

  **Grain:** [What does one row represent?]

  **Business Rules:**
  - [Key rule 1]
  - [Key rule 2]

  **Caveats:**
  - [Important limitation or edge case]
Column Description Patterns
Column TypeDocumentation Focus
Primary keySource system, uniqueness guarantee
Foreign keyWhat it joins to, NULL handling
MetricCalculation formula, units, exclusions
DateTimezone, what event it represents
Status/CategoryAll possible values, business meaning
Boolean/FlagWhat true/false means in business terms
Documenting Calculated Fields
yaml
- name: gross_margin
  description: |
    Gross margin percentage.
    Calculation: (revenue - cogs) / revenue * 100
    NULL when revenue = 0 to avoid division by zero

Anti-Patterns

  • Adding documentation without checking existing project patterns
  • Using different formatting style than existing documentation
  • Describing WHAT (e.g., "The order ID") instead of WHY/context
  • Missing grain documentation
  • Not documenting NULL handling
  • Leaving columns undocumented
  • Copy-pasting column names as descriptions

© AltimateAI, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/dbt/documenting-dbt-models of AltimateAI/data-engineering-skills.

Open the folder on GitHubat commit 705c68b

Compare with similar skills

dbt Model Documentation next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

dbt Model Documentation compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
dbt Model Documentation this skillAltimateAI/data-engineering-skills128—~1.2kAutomated safety check: PassMIT
Dbt Databricks PR Readydatabricks/dbt-databricks380—~2.8kAutomated safety check: PassApache-2.0
Mz Dbt ReleaseMaterializeInc/materialize6.4k—~1.2kAutomated safety check: PassCustom licence
Erd Studio Setupliam-machine/erd-studio165—~8.5kAutomated safety check: PassCustom licence
PR Verifydocglow/docglow148—~1.5kAutomated safety check: PassMIT
Migrating Dagster To Airflowastronomer/agents451—~3.8kAutomated safety check: PassApache-2.0

Similar skills

  • Dbt Databricks PR Ready

    databricks/dbt-databricks

    Official

    A skill your agent uses for an open dbt-databricks pull request, including your own PR or a fork PR, to assess merge readiness and optionally repair selected gaps on the PR head branch.

    380 GitHub stars~2.8k tokensUpdated today
    Data & AnalyticsAuto-check passed

  • Mz Dbt Release

    MaterializeInc/materialize

    Cut a dbt-materialize PyPI release: bump the version in version.py and setup.py, date the Unreleased CHANGELOG entry, and open the release PR with a Ship: <url body.

    6.4k GitHub stars~1.2k tokensUpdated today
    Data & AnalyticsAuto-check passed

  • Erd Studio Setup

    liam-machine/erd-studio

    Friendly, step-by-step setup for ERD Studio in an existing dbt project, for people who may be new to dbt or data modelling.

    165 GitHub stars~8.5k tokensUpdated today
    Data & AnalyticsAuto-check passed

  • PR Verify

    docglow/docglow

    Verify a Docglow change actually works before submitting or merging a PR.

    148 GitHub stars~1.5k tokensUpdated 11 days ago
    Data & AnalyticsAuto-check passed

  • Migrating Dagster To Airflow

    astronomer/agents

    Guide for migrating Dagster projects to Apache Airflow 3 on Astro.

    451 GitHub stars~3.8k tokensUpdated today
    Data & AnalyticsAuto-check passed

  • Dbt Parser Refresh

    yu-iskw/dbt-artifacts-parser

    Refreshes dbt artifact schemas from dbt-labs/dbt-core and regenerates Pydantic parser classes.

    118 GitHub stars~716 tokensUpdated yesterday
    Data & AnalyticsAuto-check passed

More from AltimateAI/data-engineering-skills

All 12 skills in this repo

  • Altimate Data Warehouse Delegate

    AltimateAI/data-engineering-skills

    Delegates dbt and warehouse tasks such as lineage, migrations and cost attribution to the altimate-code CLI agent and relays its answer back.

    128 GitHub stars~1.4k tokensUpdated 6 days ago
    Auto-check passed

  • dbt Model Builder

    AltimateAI/data-engineering-skills

    Creates or modifies dbt models in line with a project's own conventions, then runs dbt build and dbt show to check the output instead of stopping at compile.

    128 GitHub stars~890 tokensUpdated 6 days ago
    Auto-check passed

  • dbt Error Debugging

    AltimateAI/data-engineering-skills

    Walks through fixing dbt compilation, database and test errors: read the full error, check upstream models, apply a fix, then verify with dbt build and a data preview.

    128 GitHub stars~1.1k tokensUpdated 6 days ago
    Auto-check passed

  • dbt Incremental Models

    AltimateAI/data-engineering-skills

    Helps choose an incremental strategy, design a reliable unique_key and debug failing dbt incremental models, and says when a plain table is the better choice.

    128 GitHub stars~2.3k tokensUpdated 6 days ago
    Auto-check passed

  • Expensive Snowflake Query Finder

    AltimateAI/data-engineering-skills

    Ranks the costliest, slowest or heaviest-scanning Snowflake queries from query history and suggests how to optimize them.

    128 GitHub stars~662 tokensUpdated 6 days ago
    Auto-check passed

  • Migrating SQL To Dbt

    AltimateAI/data-engineering-skills

    Converts legacy SQL to modular dbt models. An agent skill from AltimateAI/data-engineering-skills.

    128 GitHub stars~762 tokensUpdated 6 days ago
    Auto-check passed

Works with

Categories

Questions about dbt Model Documentation

What does dbt Model Documentation do?

Writes model and column descriptions in dbt schema.yml files, matching the project's existing documentation style and recording grain, business rules and caveats. Existing documentation conventions come first: how long descriptions are, whether they use plain text or markdown, whether they mention grain, rules and caveats, how deep column coverage goes, and whether meta tags appear.yml.

When should I use dbt Model Documentation?

dbt Model Documentation fits situations like: adding model descriptions and column definitions to schema.yml; explaining the grain and business rules of a dbt model; improving model discoverability before running dbt docs generate.

How do I install dbt Model Documentation in Claude Code?

Run `npx skills add AltimateAI/data-engineering-skills --skill documenting-dbt-models -a claude-code`. Or copy the skill folder (skills/dbt/documenting-dbt-models in AltimateAI/data-engineering-skills) into .claude/skills/documenting-dbt-models in your project. Claude Code loads it when a task matches its description.

How do I install dbt Model Documentation in Codex?

Run `npx skills add AltimateAI/data-engineering-skills --skill documenting-dbt-models -a codex`. Or copy the skill folder (skills/dbt/documenting-dbt-models in AltimateAI/data-engineering-skills) into .agents/skills/documenting-dbt-models in your project. Codex loads it when a task matches its description.

Can I use dbt Model Documentation in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add AltimateAI/data-engineering-skills --skill documenting-dbt-models -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/documenting-dbt-models, .gemini/skills/documenting-dbt-models, .github/skills/documenting-dbt-models and .opencode/skills/documenting-dbt-models in your project.

What does dbt Model Documentation need to run?

Going by SKILL.md and its folder, dbt Model Documentation needs the command-line tools its instructions call (dbt). Our summary lists: A dbt project with schema.yml files; dbt installed to generate docs.

Does dbt Model Documentation access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is dbt Model Documentation safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does dbt Model Documentation use?

dbt Model Documentation is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does dbt Model Documentation use?

About 1.2k tokens (SKILL.md is roughly 4.7k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to dbt Model Documentation?

Skills that share tags, products or a category with dbt Model Documentation: Dbt Databricks PR Ready (databricks/dbt-databricks, 380 stars), Mz Dbt Release (MaterializeInc/materialize, 6.4k stars), Erd Studio Setup (liam-machine/erd-studio, 165 stars) and PR Verify (docglow/docglow, 148 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains dbt Model Documentation?

AltimateAI (a GitHub organization) maintains it in AltimateAI/data-engineering-skills, which has 128 GitHub stars. The repository holds 12 skills in this directory. The repository was last updated on October 1, 2026.

Source: AltimateAI/data-engineering-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.