Teaching Claude Code the Art of Data Engineering: Introducing Altimate Skills

---

Today, we're open-sourcing Altimate Skills — a collection of Claude Code skills specifically designed for analytics engineers. We are starting with skills for dbt and Snowflake. These encode the workflows and best practices that transform AI from a basic code generator into a capable data engineering assistant.

Key Results:

• +25% improvement on model creation tasks (40% → 65%)

• +22% faster execution (TPC-H 1TB) with 100% logically equivalent queries generated for SQL optimization.

• 53% accuracy on ADE-bench (43 real-world dbt tasks)

• Skills that actually teach Claude how to work, not just what to write

# Get started in 30 seconds
/plugin marketplace add AltimateAI/data-engineering-skills
/plugin install dbt-skills@data-engineering-skills

GitHub: https://github.com/AltimateAI/data-engineering-skills and ⭐ the repo.

---

Solving the Context and Workflow Issue

If you've used Claude Code, Cursor, or any AI coding assistant for dbt development, you've experienced the frustration:

The task: "Create a staging model for the Stripe payment source."

What you expect:

-- models/staging/stripe/stg_stripe__payments.sql
{{
  config(
    materialized='view',
    schema='staging'
  )
}}

with source as (
    select * from {{ source('stripe', 'payments') }}
),

renamed as (
    select
        id as payment_id,
        amount_cents / 100.0 as amount,
        currency,
        status,
        created_at
    from source
)

select * from renamed

What you get:

SELECT * FROM {{ source('stripe', 'payments') }}

No stg_ prefix. No {{ source() }} reference. No config block. No CTEs. No understanding of your project's conventions.

Why This Happens

The core issue isn't that LLMs lack knowledge — Claude knows dbt syntax perfectly well. The problem is context and workflow:

1. No project awareness — Claude doesn't know your naming conventions, folder structure, or existing patterns

2. No verification loop — Claude declares "done" after writing code, without running dbt build

3. No convention discovery — Claude guesses at patterns instead of reading existing models first

4. Compile ≠ Success — dbt compile passes, but the model produces the wrong output

This leads to a frustrating cycle: AI writes code → You review and fix → AI loses context → Repeat.

---

What Are Claude Code Skills?

Anthorpic introduced Claude Skills in October 2025. Skills are markdown files that teach Claude how to approach tasks, not just what syntax to use. Think of them as encoding the workflow an experienced analytics engineer follows.

Skills matter because they make Claude more reliable and specialized: you can standardize repeatable work (like formatting outputs, following internal conventions, or running a known process) and reuse it across projects. Claude can also load Skills progressively, starting with lightweight metadata and pulling in deeper instructions only when needed, giving you targeted behavior without bloating context.

Practically, a Skill is typically packaged as a small folder of structured instructions (and optionally templates, scripts, or reference files) that define how Claude should approach a workflow. See our data-engineering-skills repo folders as an example.

A skill has two parts:

1. Trigger conditions — When should this skill activate?

---
name: creating-dbt-models
description: |
  Guide for creating dbt models. ALWAYS use this skill when:
  (1) Creating ANY new model (staging, intermediate, mart)
  (2) Task mentions "create", "build", "add" with model/table
  (3) Modifying model logic or columns
---

2. Workflow instructions — What steps should Claude follow?

# dbt Model Development

**Read before you write. Build after you write. Verify your output.**

## Critical Rules
1. ALWAYS run `dbt build` after creating models - compile is NOT enough
2. ALWAYS verify output after build using `dbt show`
3. If build fails 3+ times, stop and reassess your approach

## Workflow
### 1. Understand Requirements
- What columns are needed?
- What is the grain (one row per what)?
- What calculations are required?

### 2. Discover Project Conventions
cat dbt_project.yml
find models/ -name "*.sql" | head -20
Read 2-3 existing models to learn patterns...

When Claude encounters a task that matches the trigger conditions, it automatically applies the skill's workflow.

---

The Skills We Built

dbt Skills

Snowflake Skills

---

Deep Dive: How creating-dbt-models Changes Claude's Behavior

Let's trace through a real task from our benchmark to see the difference.

Task: "Create a model called dim_customer that renames id to customer_id and makes it a unique primary key."

Without Skills (Baseline Claude)

Claude's approach:

1. Write the SQL immediately:

SELECT
  id AS customer_id,
  *
FROM customers

1. Run dbt compile → passes

2. Declare done

Outcome: Model compiles, but:

• Wrong table reference (raw table vs staging model)

• No config block matching project patterns

• No verification that the output is correct

• No unique test added for primary key

With creating-dbt-models Skill

(See the specific SKILL.md file here)

Claude's approach:

Step 1: Understand Requirements

• Columns needed: customer_id (renamed from id), plus all other columns

• Grain: One row per customer

• Constraint: Must be unique on customer_id

Step 2: Discover Project Conventions

$ cat dbt_project.yml
# Shows model-paths, naming conventions

$ find models/ -name "*.sql" | head -10
models/staging/stg_customers.sql
models/staging/stg_products.sql
models/marts/dim_products.sql

$ cat models/marts/dim_products.sql
# Learns: CTEs named 'source' and 'final', config blocks, column naming

Step 3: Find Upstream Models

$ cat models/staging/stg_customers.sql
# Discovers the correct source to reference

Step 4: Write Model (following discovered patterns)

-- models/marts/dim_customer.sql
{{
  config(
    materialized='table'
  )
}}

with source as (
    select * from {{ ref('stg_customers') }}
),

final as (
    select
        id as customer_id,
        name,
        email,
        created_at
    from source
)

select * from final

Step 5: Update schema.yml with test

models:
  - name: dim_customer
    columns:
      - name: customer_id
        tests:
          - unique
          - not_null

Step 6: Build and Verify

$ dbt build --select dim_customer
# Actually runs the model and tests

$ dbt show --select dim_customer --limit 5
# Verifies output looks correct

Outcome: Model matches project conventions, has proper tests, output verified.

---

Benchmarking: ADE-bench Results

We evaluated our skills using ADE-bench, a framework for evaluating AI agents on analytics engineering tasks created by dbt Labs.

Test Setup

• 43 tasks across 5 projects (Airbnb reviews, F1 racing, Asana projects, Analytics engineering, Intercom conversations)

• Task types: Model creation, bug fixing, debugging, refactoring, data analysis

• Model: Claude Sonnet 4.5

• Database: Snowflake

• Evaluation: Automated tests comparing model output to expected results

Task Difficulty Distribution

Overall Results

Results by Task Category

What Worked

Model creation saw the biggest improvement. The creating-dbt-models skill's workflow of "discover conventions → write → build → verify" catches errors that baseline Claude misses:

1. Convention discovery prevents wrong naming/structure

2. Mandatory dbt build catches runtime errors that compile misses

3. Output verification ensures the model produces correct data

Example success — Task analytics_engineering003:

"Create a model called 'dim_customer' that renames id to customer_id, and makes that row a unique primary key."

• Baseline: Created model but wrong column reference, no test

• With skills: Discovered existing staging model, matched project patterns, and added proper unique test

What Didn't Work

Complex analysis tasks remain challenging. Tasks requiring deep reasoning about data behavior (like identifying which queries have non-deterministic results due to ties) still need human insight.

Example failure — Task f1003:

"Identify which top-N tables have inconsistent results due to ties in the data"

This task requires:

1. Understanding the semantic meaning of "ties"

2. Analyzing actual data values across 8 models

3. Reasoning about SQL ordering behavior

Skills can't encode this kind of domain reasoning — they work best for workflow guidance, not analytical judgment.

---

The Overhead Trade-off

Skills add overhead. The "discover conventions" step takes 15-30 seconds of additional LLM calls. Is it worth it?

Our conclusion: The 30-second overhead is worth it because:

1. Successful tasks need no human review

2. Failed tasks fail faster (3-failure rule)

3. Time saved on human review >> time spent on convention discovery

Benchmarking: SQL Query Optimization

We evaluated the optimizing-query-text skill on TPC-H SF1000 (1TB dataset).

Test Setup

• 10 queries from TPC-H benchmark

• Model: Claude Sonnet 4.5

• Evaluation: Automated comparison of query results + execution time

Overall Results

What Failed Without Skills

Baseline failed 2 queries by making "optimizations" that changed what the query returned:

• Changed deduplication behavior, returning extra rows

• Renamed columns, breaking downstream compatibility

---

Installation & Usage

Add the Marketplace

/plugin marketplace add AltimateAI/data-engineering-skills

Install Skills

You can browse and install via the CLI, or directly install plugins:

# Install dbt skills
/plugin install dbt-skills@data-engineering-skills

# Install Snowflake skills
/plugin install snowflake-skills@data-engineering-skills

After installing, skills activate automatically when you mention relevant tasks.

Available Skills

dbt Skills:

• creating-dbt-models — Model creation with convention discovery

• debugging-dbt-errors — Systematic error troubleshooting

• testing-dbt-models — Schema tests and data quality

• documenting-dbt-models — Generate descriptions in schema.yml

• migrating-sql-to-dbt — Convert legacy SQL to dbt models

• refactoring-dbt-models — Safe restructuring with impact analysis

Snowflake Skills:

• optimizing-query-text — Optimize SQL you provide

• optimizing-query-by-id — Optimize using query ID from history

• finding-expensive-queries — Find top cost/time queries

Usage

Skills activate automatically based on your request:

---

Combining Skills with Altimate MCP Tools

Skills become even more powerful when combined with Altimate's MCP server. The MCP server provides real-time access to your dbt project and data warehouse:

Example: Skills + MCP workflow

User: "The daily_revenue model is producing wrong numbers."

Claude (with skills + MCP):

1. debugging-dbt-errors skill activates

2. Uses dbt_model_details to get model SQL and dependencies

3. Uses dbt_compile to check for errors

4. Queries upstream models to verify input data

5. Identifies the issue (e.g., missing WHERE clause)

6. Fixes and rebuilds

7. Uses dbt show to verify the correct output

---

What We Learned Building This

1. Workflow > Knowledge

The biggest wins came from encoding workflows, not facts. Claude already knows dbt syntax — what it lacks is the discipline to:

• Check existing patterns before writing

• Run dbt build instead of dbt compile

• Verify output after build

2. The 3-Failure Rule

We added this to every skill:

"If build fails 3+ times, STOP. Step back and reassess your entire approach."

This prevents Claude from making tiny tweaks hoping they work. Instead, it forces a fundamental rethink.

3. Skills Can't Replace Domain Expertise

Skills work best for procedural tasks with clear success criteria. They struggle with:

• Tasks requiring business context

• Ambiguous requirements ("make this better")

• Deep analytical reasoning about data behavior

4. Convention Discovery Is Essential

The #1 source of Claude errors was mismatched conventions. Simply adding "read 2-3 existing models first" eliminated most of these.

---

What's Next

We're actively developing:

• Airflow skills — DAG development, debugging, testing

• Cross-platform migration — dbt ↔ SQL Server, Oracle

• Snowflake cost optimization — Warehouse sizing, query patterns

• Data quality workflows — Anomaly detection, freshness checks

Contributing

Altimate Skills is open source (MIT License). We welcome:

• New skills for workflows we haven't covered

• Improvements to existing skills based on your team's patterns

• Benchmark results on different datasets

GitHub: https://github.com/AltimateAI/data-engineering-skills

---

Try It Now

# Add the marketplace
/plugin marketplace add AltimateAI/altimate-skills

# Install the plugins you need
/plugin install dbt-skills@altimate-skills
/plugin install snowflake-skills@altimate-skills

Resources:

• GitHub Repository and ⭐ the repo.

• Altimate MCP Server Docs

• ADE-bench Framework

• dbt Slack #tools-dbt-power-user

---

Built by the team at Altimate AI — Making data engineering delightful.