You Can Teach Claude.
Here's How.

Every team I talk to has the same frustration. Claude is brilliant in isolation. The moment you need it to fit into your stack — your naming conventions, your coding patterns, your org's definition of "done" — you're typing the same context over and over again. Session after session. Prompt after prompt.

There's a better way. It's called Claude Skills. And once you understand the mechanism, you'll never go back to vanilla prompting.

What Is a Claude Skill?

A Skill is a Markdown file (.md) that you author and maintain. It tells Claude exactly how to behave for a specific task — which tools to use, which patterns to follow, which traps to avoid.

Think of it as the onboarding document you wish every new hire actually read. Except Claude reads it every single time, perfectly, before doing anything.

The Skill file is loaded before Claude formulates its response. Your conventions become Claude's conventions. Your stack becomes Claude's known context. Your guardrails become Claude's first instincts.

The Real-World Case: Building a Data Lake

Let's make this concrete. You're at an enterprise, building a data lake on Databricks + Delta Lake with Unity Catalog for governance and Terraform for infra. This is a real build — not a toy demo.

Without a Skill, every Claude session starts from zero. You have to explain: "We use Delta Lake. Not Hive tables. Partition by ingestion_date. Always add mergeSchema. Use Unity Catalog. Log errors to audit.ingestion_errors…" — every. single. time.

Step-by-Step: Creating Your First Skill

Good Skill boundaries look like this:

• "Create PySpark ingestion pipelines for our Bronze layer"
• "Generate Terraform modules for Databricks cluster configs"
• "Write data quality checks using Great Expectations"

Bad Skill boundaries look like this:

• "Do all data engineering things" ← too broad
• "Fix bugs" ← no context, no structure

---
name: data-lake-ingestion
description: >
  Use this skill when building PySpark ingestion pipelines
  for the Bronze layer of our Delta Lake on Databricks.
  Triggers: mentions of ingestion, raw data, Bronze layer,
  PySpark jobs, cloudFiles, Auto Loader, or Delta writes.
---

# Data Lake Ingestion Skill

## Our Stack
- Platform: Databricks on Azure (Unity Catalog enabled)
- Format: Delta Lake ONLY — never raw Parquet
- Namespace: catalog.schema.table (3-level, always)
- Orchestration: Apache Airflow (DAGs in /dags/)

## Naming Conventions
- Bronze tables: bronze_{source}_{entity}
  e.g. bronze_salesforce_accounts
- Partition column: ingestion_date (always, no exceptions)
- PII columns: suffix with _pii (e.g. email_pii)

## Required Code Patterns
Always use:
- spark.read.format("cloudFiles") for Auto Loader
- .option("mergeSchema", "true") on all reads
- delta.enableChangeDataFeed = true on all Bronze tables
- MERGE INTO (never overwrite mode)

Never use:
- spark.read.csv() directly — always via Auto Loader
- .mode("overwrite") — data loss risk
- Hive metastore — Unity Catalog only

## Error Handling
- Log failures to: audit.ingestion_errors
- Wrap all writes in try/except with structured error objects
- Emit metrics to Datadog pipeline monitor

## Output Format
Always return ALL THREE of:
1. The PySpark script (production-ready)
2. Databricks notebook cell breakdown
3. Unity Catalog DDL for the target table

What Makes a Great Skill

The Numbers That Matter

7 Ways Teams Get Skills Wrong

Most Skills failures aren't Claude's fault. They're authoring failures — the same structural mistakes repeated across orgs, roles, and use cases. Here they are, with exactly what to do instead.

The Trigger Description: Your Most Important 3 Sentences

This is the field most people write in 30 seconds and never revisit. It is, in practice, the most load-bearing part of your entire Skill file. Get it wrong, and the Skill never activates. Get it too broad, and it stomps all over your other Skills.

Rules Claude Cannot Infer. You Must State Them.

A common mistake is assuming Claude can deduce your conventions from a few examples. It can't — not reliably, not consistently. These categories of knowledge must be explicitly stated in every production Skill:

The Silent Failure You Won't See Coming

There's a class of Skill failure more dangerous than a crash or an error: confident wrongness. Claude produces output that looks production-ready, passes a quick review, and gets merged — but violates your standards in a subtle way you only catch three sprints later.

CLAUDE.md Done Wrong vs. Done Right

The session-level config file is where teams cause the most systemic damage. Here's what separates a Skills architecture that scales from one that quietly degrades:

The Bigger Picture

Skills aren't just convenience. They're about encoding your organization's knowledge in a way that's queryable, evolvable, and AI-native.

A well-maintained Skills library is faster than documentation (Claude acts on it directly), more consistent than tribal knowledge (it doesn't live in one senior engineer's head), and easier to audit than code comments (plain English, version-controlled in Git).

Each file represents a job Claude can now do to your standards. Combine enough of them, and you've built something genuinely powerful: an AI operator that knows your enterprise as well as your best engineer does — and never forgets it.