documenting-dbt-models

Name: documenting-dbt-models
Author: AltimateAI

29installs7forks

How to install documenting-dbt-models?

altimateai/data-engineering-skills/documenting-dbt-models

$npx -y skills add AltimateAI/data-engineering-skills --skill documenting-dbt-models

Installs into the current project.

Summary

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, gra

Files · 1

View on GitHub

SKILL.md

1	# dbt Documentation
2
3	Document the WHY, not just the WHAT. Include grain, business rules, and caveats.
4
5	## Workflow
6
7	### 1. Study Existing Documentation Patterns
8
9	CRITICAL: Match the project's documentation style before adding new docs.
10
11	```bash
12	# Find all schema.yml files with documentation
13	find . -name "schema.yml" \| head -5
14
15	# Read well-documented models to learn patterns
16	cat models/marts/schema.yml \| head -150
17	cat models/staging/schema.yml \| head -150
18	```
19
20	Extract from existing documentation:
21	- Description length (brief vs detailed)
22	- Formatting style (plain text vs markdown with headers)
23	- Information included (grain? business rules? caveats?)
24	- Column description depth (all columns vs key columns)
25	- Use of meta tags or custom properties
26
27	### 2. Read Model SQL
28
29	```bash
30	cat models/<path>/<model_name>.sql
31	```
32
33	Understand: transformations, business logic, joins, filters.
34
35	### 3. Check Existing Documentation for This Model
36
37	```bash
38	# Find existing schema.yml
39	find . -name "schema.yml" -exec grep -l "<model_name>" {} \;
40
41	# Read existing docs
42	cat models/<path>/schema.yml \| grep -A 100 "<model_name>"
43	```
44
45	### 4. Identify Documentation Needs
46
47	For each model, document:
48	- Model description: Purpose, grain, key business rules
49	- Column descriptions: Business meaning, not just data type
50
51	For each column, consider:
52	- What business concept does this represent?
53	- Are there any caveats or special values?
54	- What is the source of this data?
55
56	### 5. Write Documentation
57
58	Match the style discovered in step 1. Example format (adapt to project):
59
60	```yaml
61	version: 2
62
63	models:
64	- name: orders
65	description: \|
66	Order transactions at the order line item grain.
67	Each row represents one product in one order.
68
69	Business Rules:
70	- Revenue recognized on ship_date, not order_date
71	- Cancelled orders excluded (status != 'cancelled')
72	- Returns processed as negative line items
73
74	Grain: One row per order_id + product_id combination
75
76	columns:
77	- name: order_id
78	description: \|
79	Unique identifier for the order.
80	Source: orders.id from Stripe webhook
81
82	- name: customer_id
83	description: \|
84	Foreign key to customers table.
85	NULL for guest checkouts (pre-2023 only)
86
87	- name: revenue
88	description: \|
89	Net revenue for this line item in USD.
90	Calculation: unit_price * quantity - discount_amount
91	Excludes tax and shipping
92
93	- name: order_status
94	description: \|
95	Current status of the order.
96	Values: pending, processing, shipped, delivered, cancelled, returned
97	```
98
99	### 6. Generate Docs
100
101	```bash
102	dbt docs generate
103	dbt docs serve # Optional: preview locally
104	```
105
106	## Documentation Patterns
107
108	Note: These are default templates. Always adapt to match project's existing style.
109
110	### Model Description Template
111
112	```yaml
113	description: \|
114	[One sentence: what this model contains]
115
116	Grain: [What does one row represent?]
117
118	Business Rules:
119	- [Key rule 1]
120	- [Key rule 2]
121
122	Caveats:
123	- [Important limitation or edge case]
124	```
125
126	### Column Description Patterns
127
128	\| Column Type \| Documentation Focus \|
129	\|-------------\|---------------------\|
130	\| Primary key \| Source system, uniqueness guarantee \|
131	\| Foreign key \| What it joins to, NULL handling \|
132	\| Metric \| Calculation formula, units, exclusions \|
133	\| Date \| Timezone, what event it represents \|
134	\| Status/Category \| All possible values, business meaning \|
135	\| Boolean/Flag \| What true/false means in business terms \|
136
137	### Documenting Calculated Fields
138
139	```yaml
140	- name: gross_margin
141	description: \|
142	Gross margin percentage.
143	Calculation: (revenue - cogs) / revenue * 100
144	NULL when revenue = 0 to avoid division by zero
145	```
146
147	## Anti-Patterns
148
149	- Adding documentation without checking existing project patterns
150	- Using different formatting style than existing documentation
151	- Describing WHAT (e.g., "The order ID") instead of WHY/context
152	- Missing grain documentation
153	- Not documenting NULL handling
154	- Leaving columns undocumented
155	- Copy-pasting column names as descriptions

People who liked this also viewed

6 picks

Type

documenting-dbt-models

29installs7forks

View on GitHub

How to install documenting-dbt-models?

altimateai/data-engineering-skills/documenting-dbt-models

$npx -y skills add AltimateAI/data-engineering-skills --skill documenting-dbt-models

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# dbt Documentation
2
3	Document the WHY, not just the WHAT. Include grain, business rules, and caveats.
4
5	## Workflow
6
7	### 1. Study Existing Documentation Patterns
8
9	CRITICAL: Match the project's documentation style before adding new docs.
10
11	```bash
12	# Find all schema.yml files with documentation
13	find . -name "schema.yml" \| head -5
14
15	# Read well-documented models to learn patterns
16	cat models/marts/schema.yml \| head -150
17	cat models/staging/schema.yml \| head -150
18	```
19
20	Extract from existing documentation:
21	- Description length (brief vs detailed)
22	- Formatting style (plain text vs markdown with headers)
23	- Information included (grain? business rules? caveats?)
24	- Column description depth (all columns vs key columns)
25	- Use of meta tags or custom properties
26
27	### 2. Read Model SQL
28
29	```bash
30	cat models/<path>/<model_name>.sql
31	```
32
33	Understand: transformations, business logic, joins, filters.
34
35	### 3. Check Existing Documentation for This Model
36
37	```bash
38	# Find existing schema.yml
39	find . -name "schema.yml" -exec grep -l "<model_name>" {} \;
40
41	# Read existing docs
42	cat models/<path>/schema.yml \| grep -A 100 "<model_name>"
43	```
44
45	### 4. Identify Documentation Needs
46
47	For each model, document:
48	- Model description: Purpose, grain, key business rules
49	- Column descriptions: Business meaning, not just data type
50
51	For each column, consider:
52	- What business concept does this represent?
53	- Are there any caveats or special values?
54	- What is the source of this data?
55
56	### 5. Write Documentation
57
58	Match the style discovered in step 1. Example format (adapt to project):
59
60	```yaml
61	version: 2
62
63	models:
64	- name: orders
65	description: \|
66	Order transactions at the order line item grain.
67	Each row represents one product in one order.
68
69	Business Rules:
70	- Revenue recognized on ship_date, not order_date
71	- Cancelled orders excluded (status != 'cancelled')
72	- Returns processed as negative line items
73
74	Grain: One row per order_id + product_id combination
75
76	columns:
77	- name: order_id
78	description: \|
79	Unique identifier for the order.
80	Source: orders.id from Stripe webhook
81
82	- name: customer_id
83	description: \|
84	Foreign key to customers table.
85	NULL for guest checkouts (pre-2023 only)
86
87	- name: revenue
88	description: \|
89	Net revenue for this line item in USD.
90	Calculation: unit_price * quantity - discount_amount
91	Excludes tax and shipping
92
93	- name: order_status
94	description: \|
95	Current status of the order.
96	Values: pending, processing, shipped, delivered, cancelled, returned
97	```
98
99	### 6. Generate Docs
100
101	```bash
102	dbt docs generate
103	dbt docs serve # Optional: preview locally
104	```
105
106	## Documentation Patterns
107
108	Note: These are default templates. Always adapt to match project's existing style.
109
110	### Model Description Template
111
112	```yaml
113	description: \|
114	[One sentence: what this model contains]
115
116	Grain: [What does one row represent?]
117
118	Business Rules:
119	- [Key rule 1]
120	- [Key rule 2]
121
122	Caveats:
123	- [Important limitation or edge case]
124	```
125
126	### Column Description Patterns
127
128	\| Column Type \| Documentation Focus \|
129	\|-------------\|---------------------\|
130	\| Primary key \| Source system, uniqueness guarantee \|
131	\| Foreign key \| What it joins to, NULL handling \|
132	\| Metric \| Calculation formula, units, exclusions \|
133	\| Date \| Timezone, what event it represents \|
134	\| Status/Category \| All possible values, business meaning \|
135	\| Boolean/Flag \| What true/false means in business terms \|
136
137	### Documenting Calculated Fields
138
139	```yaml
140	- name: gross_margin
141	description: \|
142	Gross margin percentage.
143	Calculation: (revenue - cogs) / revenue * 100
144	NULL when revenue = 0 to avoid division by zero
145	```
146
147	## Anti-Patterns
148
149	- Adding documentation without checking existing project patterns
150	- Using different formatting style than existing documentation
151	- Describing WHAT (e.g., "The order ID") instead of WHY/context
152	- Missing grain documentation
153	- Not documenting NULL handling
154	- Leaving columns undocumented
155	- Copy-pasting column names as descriptions

People who liked this also viewed

6 picks

Type