Agent Skills › AltimateAI/altimate-code › dbt-docs

dbt-docs

GitHub

用于为dbt模型和列添加业务上下文描述，提升文档可发现性。支持生成模型级说明、列级定义及共享文档块，指导Agent阅读SQL与现有schema.yml以编写高质量业务文档。

.opencode/skills/dbt-docs/SKILL.md AltimateAI/altimate-code

Trigger Scenarios

用户希望添加或改进schema.yml中的模型描述用户需要编写具有业务上下文的列级描述用户想要创建可复用的共享文档块用户希望改善dbt文档站点的整体内容

Install

npx skills add AltimateAI/altimate-code --skill dbt-docs -g -y

More Options

Non-standard path

npx skills add https://github.com/AltimateAI/altimate-code/tree/main/.opencode/skills/dbt-docs -g -y

Use without installing

npx skills use AltimateAI/altimate-code@dbt-docs

指定 Agent (Claude Code)

npx skills add AltimateAI/altimate-code --skill dbt-docs -a claude-code -g -y

安装 repo 全部 skill

npx skills add AltimateAI/altimate-code --all -g -y

预览 repo 内 skill

npx skills add AltimateAI/altimate-code --list

SKILL.md

Frontmatter

{
    "name": "dbt-docs",
    "description": "Document dbt models and columns in schema.yml with business context — model descriptions, column definitions, and doc blocks. Use when adding or improving documentation for discoverability. Powered by altimate-dbt."
}

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