A profiles.yml copied into the repository for CI with the warehouse password still in it, or a packages.yml that installs a private package from https://[email protected], hands your warehouse or GitHub access to everyone who can read the repo. Quieter mistakes break the numbers instead: an incremental model without a unique_key stores late rows twice, and a model with no unique test on its key lets a bad join multiply rows. This skill finds those and the other dbt mistakes below, and tells you how to fix each one.

Your agent runs a scanner on your dbt project: dbt_project.yml, every profiles.yml in the folder (also .dbt/profiles.yml), packages.yml, dependencies.yml, and the SQL models and YAML properties files in your model-paths. It knows dbt's Jinja (ref(), source(), config(), env_var(), is_incremental()), both tests: and data_tests:, freshness and loaded_at_field under config: (dbt 1.9 and 1.10), configs set in config(), a properties file or a dbt_project.yml folder block, and your .gitignore. It follows dbt's own style guide, so import CTEs, select from final and select from a ref() are not reported. It never runs dbt or connects to your warehouse. It returns BLOCK, REVIEW, or NOT FLAGGED, with the file, line, reason, and a safer approach. Secrets are never printed.

What it checks

BLOCK (fix before shipping)

• D01: literal passwords, tokens, private keys, keyfile_json, client secrets, refresh tokens and AWS secret keys in profiles.yml (also real-looking secrets used as env_var() defaults)

• D02: a profiles.yml with literal credentials in a git repository that no .gitignore rule or .git/info/exclude entry covers

• D03: git tokens or passwords in packages.yml and dependencies.yml URLs, and key-like secret vars written in dbt_project.yml

REVIEW (check before release)

• D11: models with no unique + not_null test pair on a key column (or no properties file at all); time-spine models are skipped

• D12: a final select (or a lone t.) that passes every raw column of a source() or a named table straight through

• D13: sources whose tables have no freshness with warn_after or error_after

• D14: database.schema.table or schema.table written out instead of ref() or source()

• D15: incremental models without a unique_key (append, insert_overwrite, microbatch and Databricks replace_where are fine)

• D16: env_var() fallbacks to a well-known default password such as postgres or changeme in profiles.yml

What's included

• The scanner (Python 3.9+, standard library only)

• A rules guide with the reason and safer approach for each rule

• A risky and a safe example dbt project, and the real report the scanner produces on the risky one

Limits

It reads files as written. Jinja is not rendered, so models built by macros or loops, configs set from var() or env_var(), and adapter defaults are not evaluated. A profiles.yml in ~/.dbt/ is checked only when you name it, and a global git excludes file is not read. Python models, seeds, snapshots, analyses, singular tests and installed packages in dbt_packages/ are not checked. A primary_key constraint alone does not count as a key test, because most warehouses do not enforce it. NOT FLAGGED is not a guarantee.

Contents

One ZIP file with 29 files: SKILL.md, the scanner in scripts/ (6 Python files), references/rules.md (every rule with its reason and safer approach), and examples/ (20 example files plus report.md, the real scanner output on the risky example).

How to use: This is an agent skill: a folder with a SKILL.md file and Python scripts that an AI coding agent such as Claude Code, Cursor, or Codex CLI can run. Unzip it into your agent's skills folder (for Claude Code: ~/.claude/skills/), then ask your agent to check your project. The scripts also run on their own with Python 3.9 or newer, with nothing to install. They read your files only: no network access, and nothing is sent anywhere.