dbt-skillz: Stop Claude Code from Breaking Your Data Models

When you ask Claude Code to write a SQL query against your dbt project, it's working blindfolded. It doesn't know your table names, column types, transformation logic, or business rules. The result? Broken queries, incorrect aggregations, and wasted debugging time.

dbt-skillz solves this by compiling your entire dbt project into structured Markdown that Claude Code can ingest as context. It's like giving your AI agent a data dictionary before it starts coding.

What It Does — Structured Context for Data Work

dbt-skillz analyzes your dbt project's YAML files, SQL models, and macros, then generates a comprehensive skill with multiple sub-skills:

docs/
├── SKILL.md              # Agent-ready overview (the main skill file)
└── ref/
    ├── sources.md        # Source tables (databases, schemas, tables)
    ├── staging.md        # Staging models (cleaned & typed)
    ├── intermediate.md   # Intermediate models (business logic)
    ├── marts.md          # Mart tables (analytics-ready)
    ├── macros.md         # dbt macro reference
    └── lineage.md        # Mermaid dependency graph

The SKILL.md file becomes the entry point Claude Code reads. It contains:

• Project architecture overview
• Model inventory by layer (staging → intermediate → marts)
• Navigation links to detailed references
• Mermaid lineage diagrams showing dependencies

Setup — Two Minutes to Data-Aware Claude Code

Install via pip, uv, or pipx:

# pip
pip install dbt-skillz

# uv
uv tool install dbt-skillz

# pipx
pipx install dbt-skillz

Generate the skill directly into your Claude Code skills directory:

dbt-skillz compile --project-dir ./analytics --output ./.claude/skills/data-analytics

Or generate it elsewhere and attach manually:

dbt-skillz compile --project-dir ./analytics --output ./docs

When To Use It — Four Concrete Workflows

1. Reliable Query Generation

Instead of: "Claude, write a query to get monthly revenue" (and hoping it guesses the right table/columns)

Now: Claude Code reads SKILL.md, knows revenue_report exists in the marts layer, understands revenue_amount is a decimal column, and writes correct SQL immediately.

2. Safe dbt Development

When adding a new model, Claude Code can reference existing transformations and avoid breaking downstream dependencies. The lineage diagram in ref/lineage.md shows what depends on what.

3. CI/CD Integration

Add to your pipeline to regenerate the skill on every PR or merge:

# .github/workflows/update-skill.yml
- name: Update dbt-skillz
  run: |
    pip install dbt-skillz
    dbt-skillz compile --project-dir ./analytics --output ./.claude/skills/data-analytics

4. Onboarding & Documentation

New team members get the same architecture overview the AI uses. SKILL.md is human-readable documentation that stays in sync with your codebase.

Configuration Options That Matter

# Include actual SQL snippets in documentation
dbt-skillz compile --include-sql

# Limit SKILL.md size for token efficiency
dbt-skillz compile --max-skill-lines 600

# Add extra documentation (workflow guides, business context)
dbt-skillz compile --extras-dir ./docs/business-context

The --max-skill-lines flag is crucial for Claude Code's context window management. At 600 lines, you get the essential structure without token bloat.

Why This Beats Manual Context

You could manually paste table schemas into each Claude Code conversation. But:

1. It's tedious — you'd need to update it constantly
2. It's incomplete — you'll forget column descriptions or business rules
3. It's inconsistent — different team members provide different context

dbt-skillz automates the complete, consistent, up-to-date context Claude Code needs to work effectively with your data.

gentic.news Analysis

This tool arrives as AI Agents are crossing what industry leaders call a "critical reliability threshold" (December 2026). The problem dbt-skillz solves—agents working blind in complex codebases—is exactly the type of reliability issue holding back wider adoption.

It follows a pattern we've seen with other Claude Code enhancements: structured context generation. Similar to how CLAUDE.md files provide project-specific instructions (covered in our March 25 article "Stop Wasting Your CLAUDE.md Instruction Budget"), dbt-skillz provides data-specific context. This aligns with the broader trend of MCP servers (Model Context Protocol) extending Claude Code's capabilities, though dbt-skillz uses Markdown files instead of the MCP protocol.

The tool's compatibility with Claude Code, Workshop, and Cursor reflects the multi-agent ecosystem emerging around Anthropic's models. As Claude Agent (Anthropic's multi-agent framework) gains traction, tools that create portable, structured context will become increasingly valuable across different agent platforms.

For data teams already using Claude Code, this represents a concrete step toward the "hands-off agent teams" vision we explored in our March 25 coverage of Loop CLI. Instead of agents guessing at data structures, they now have authoritative references—reducing the 25+ navigation actions per code edit that current benchmarks show.