Menu
Populate the knowledge base from dbt project research. Proposes entries across all 6 categories at org, project, and connection scopes.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Load when task involves dbt snapshots, SCD Type 2, or tracking data changes over time. Covers strategy selection, column casing, verification, and common pitfalls.
Load when task involves adding, writing, or fixing dbt unit tests. Covers unit_tests YAML format, given/expect blocks, edge-case coverage, and the difference between unit tests and schema tests.
Load when task involves dbt model versioning, creating v2 of a model, or backward-compatible model changes. Covers versions YAML config, defined_in, latest_version, and ref() with version pins.
Load FIRST before any dbt project work. Covers the full 8-step dbt workflow: project scanning, skill loading, validation, macro discovery, research, technical spec, SQL writing, and verification. Also covers output shape inference, incremental model handling, and what to trust in YML.
Generates an HTML report summarizing dbt project work: decisions, SQL, queries, verifier results, and visual charts. Only load when explicitly requested.
| name | dbt-knowledgebase |
| description | Populate the knowledge base from dbt project research. Proposes entries across all 6 categories at org, project, and connection scopes. |
| allowed-tools | Bash(dbt *) Bash(python3 *) Bash(map-columns *) |
Populate the knowledge base with structured entries from your research. After completing exploration (Steps 1-5 of the workflow), propose entries across ALL categories and scopes below. Every category MUST have at least one entry after this step - even if it is an initial summary based on what you observed.
Scope: org AND project. Always loaded at the start of every run.
The 30-second briefing a new analyst needs before touching anything.
At org level (scope="org"): company terminology, fiscal calendar,
universal join keys, database engine. If no org-level understanding exists,
create one summarizing what you can infer from this project - the database
type, general data domain, naming patterns.
At project level (scope="project"): what the pipeline models, key
entities, data flow, how many models, what the task is about.
Example: "This project models Reddit post and comment data from paranormal subreddits. Two mart models join posts to comments via post URL. Source data is in DuckDB with 3 raw tables."
Scope: org AND project. Always loaded alongside understanding docs.
How this team writes SQL and organizes models. Not data facts - patterns about how to work with data.
At org level: database-wide SQL patterns (e.g., materialization strategy, column casing). If nothing exists, create one from what you observe in this project's existing models.
At project level: project-specific patterns from sibling models - JOIN types used, aggregation functions, column naming prefixes/suffixes, macro usage patterns, how existing models handle NULLs.
Example: "All sibling models use LEFT JOIN for dimension tables." / "Macro extract_hour(col) produces hour_ - used in existing models."
Scope: project only. Searchable by sub-agents.
Per-model reasoning from your research. Why this grain, why this driving table, why this join type, why this filter. Document the reasoning that saves the next agent from re-deriving the same logic.
One entry per model or per significant cross-model decision.
Example: "prod_posts_ghosts drives from stg_reddit_posts (250 rows). LEFT JOIN not needed - single source model, no joins." / "Join path between posts and comments is post_url, not post_id - post_id format differs between tables (t3_ prefix in comments)."
Scope: org or project. Searchable by sub-agents.
Business rules encoded in the data that you cannot discover from schema alone. These come from column values, status flags, data patterns.
Example: "comment score can be negative (downvoted)." / "NULL post text means link-only post, not missing data." / "l_returnflag values: A=accepted, N=new, R=returned."
Scope: project only. Searchable when agent hits errors.
Hard-won lessons from exploration - errors encountered during validation, parse issues, data quality problems found.
Example: "dbt parse warns about 36 unused config paths - safe to ignore." / "DuckDB BIGINT overflow on SUM of large integers - cast to DOUBLE."
Scope: connection only. Loaded when working with that connection.
Tied to a specific database instance. Data type mismatches, unexpected NULLs, format oddities.
Example: "post_id in comments has t3_ prefix but posts table has bare integer IDs." / "price column stores costs as negative values."
After research, create a task for EACH category below. Mark each
in_progress when you start proposing for that category and completed
when done.
For each category: call search_knowledge first to check if an entry
already exists. If it does, skip it. If it does not, propose one.
propose_knowledge(
scope="project",
scope_ref="<project_name>",
category="decisions",
title="<short-kebab-case-slug>",
body="<detailed body with evidence>"
)
For org-level entries, use scope="org" and scope_ref=None.
For connection-level entries, use scope="connection" and
scope_ref="<connection_name>".
Titles MUST be lowercase kebab-case slugs.
Body MUST include:
The body MUST be purely descriptive. State what EXISTS, not what to DO.
BAD IMPACT (prescriptive): "Do not add macro columns unless YML lists them." GOOD (descriptive): "Macros produce hour_created_at and normalized_created_at columns. These columns are not in the current YML contract."
The reader (a future builder agent) decides what to do with the fact. You only document what you found.