Data Context Extractor Skill

Extract tribal knowledge from data analysts and encode it into a reusable skill file that helps Claude understand your warehouse, metrics, conventions, and business logic. The output is a SKILL.md file that any team member can use.

Workflow

Step 1: Determine the Mode

Bootstrap Mode -- Creating a new context skill from scratch:

• No existing skill file
• Starting with a blank slate
• Need to interview the analyst to gather context

Enhancement Mode -- Improving an existing context skill:

• There is an existing SKILL.md with some context
• Need to fill gaps, add new tables, or refine metric definitions
• May have learned new things from recent analysis work

Step 2: Gather Warehouse Context

Ask the analyst these questions in a conversational interview format. Do not dump all questions at once -- ask in logical groups.

Group 1: Warehouse Basics

• What data warehouse do you use? (Snowflake, BigQuery, Databricks, Redshift, Postgres)
• What is the default database/project and schema?
• What SQL dialect conventions does your team follow?
• Are there any warehouse-specific features you rely on (e.g., Snowflake FLATTEN, BigQuery UNNEST)?

Group 2: Key Tables

For each important table, capture:

• Full qualified name (database.schema.table)
• Purpose: What does this table represent?
• Grain: What does one row represent?
• Key columns: Primary key, foreign keys, commonly used columns
• Gotchas: Anything surprising or non-obvious about the data
• Freshness: How often is it updated? What is the typical lag?
• Row count order of magnitude: Thousands, millions, billions?

Group 3: Metric Definitions

For each important business metric:

• Name: What does the team call it?
• Definition: Exact calculation (SQL expression or formula)
• Filters: Standard exclusions (test users, internal traffic, refunds)
• Dimensions: Common breakdowns (by channel, region, product)
• Caveats: Known issues, edge cases, or misuse patterns

Group 4: Business Logic and Conventions

• How do you define an "active user"?
• What date fields are used for reporting (created_at, event_date, invoice_date)?
• What timezone does the data use?
• Are there standard exclusion filters (test accounts, bots, internal users)?
• How are deleted/cancelled records handled (soft delete, status field, separate table)?
• What fiscal calendar do you use?

Group 5: Common Queries and Patterns

• What are the 5 most common queries your team runs?
• Are there standard CTEs or subqueries that get reused?
• What joins are commonly needed? Are there tricky join conditions?
• What performance considerations matter (partitioning, clustering, materialized views)?

Group 6: Gotchas and Tribal Knowledge

• What mistakes do new analysts commonly make?
• Are there tables that look similar but serve different purposes?
• Are there columns that are misleading or named poorly?
• What data quality issues are known and accepted?
• Are there tables that should never be joined directly?

Step 3: Generate the Context Skill

Structure the output SKILL.md file with these sections:

---
name: [company]-data-context
description: |
  Context skill for [Company]'s data warehouse. Provides table schemas,
  metric definitions, SQL conventions, and tribal knowledge for accurate analysis.
---

# [Company] Data Context

## Warehouse
- **Platform**: [Snowflake/BigQuery/etc.]
- **Default database**: [database.schema]
- **Timezone**: [UTC/US-Pacific/etc.]
- **Fiscal calendar**: [Jan-Dec / Feb-Jan / etc.]

## Standard Filters
Always apply these unless explicitly told otherwise:
- Exclude test accounts: `WHERE account_id NOT IN (SELECT id FROM test_accounts)`
- Exclude internal traffic: `WHERE is_internal = FALSE`
- [Additional standard filters]

## Key Tables

### [table_name]
- **Path**: `database.schema.table_name`
- **Grain**: One row per [entity] per [time period]
- **Updated**: [frequency]
- **Key columns**:
  - `column_a` -- [description]
  - `column_b` -- [description]
- **Gotchas**: [non-obvious behaviors]

[Repeat for each table]

## Metric Definitions

### [Metric Name]
- **Definition**: [SQL expression or formula]
- **Standard filters**: [What to include/exclude]
- **Common breakdowns**: [dimensions]
- **Caveats**: [edge cases]

[Repeat for each metric]

## Common Patterns

### [Pattern Name]
[Description and reusable SQL snippet]

## Gotchas
1. [Common mistake and how to avoid it]
2. [Another common mistake]

Step 4: Validate

After generating the skill file:

1. Read it back to the analyst and ask: "Does this accurately capture how your team works?"
2. Test with a sample question: Try answering a typical data question using only the context in the skill file.
3. Identify gaps: What questions could you not answer? Add those to the skill.
4. Check for contradictions: Ensure metric definitions are consistent with each other.

Step 5: Iterate

The context skill is a living document. Improve it by:

• Adding new tables as they are created
• Refining metric definitions when edge cases are discovered
• Documenting new gotchas as analysts encounter them
• Adding example queries that have been validated

Output Format

A complete SKILL.md file with valid YAML frontmatter that can be placed in the skills directory and immediately used by Claude for data analysis tasks.

Examples

Example 1: E-commerce Warehouse

Covers orders, customers, products, sessions tables. Defines GMV, conversion rate, AOV, repeat rate. Documents the distinction between gross and net revenue.

Example 2: SaaS Product Analytics

Covers events, users, subscriptions, feature_usage tables. Defines DAU/WAU/MAU, activation rate, retention cohorts. Documents event taxonomy and naming conventions.

Example 3: Financial Reporting

Covers general_ledger, chart_of_accounts, journal_entries. Defines EBITDA, burn rate, runway. Documents fiscal calendar and intercompany elimination rules.

Best Practices

1. Be specific about SQL. Include actual column names, not just descriptions. revenue = SUM(amount) WHERE type = 'charge' AND status = 'settled' is better than "sum of charges."
2. Document the grain. The most common source of errors is misunderstanding what one row represents.
3. Capture the negative space. What should be excluded is as important as what should be included.
4. Use real examples. Include sample values for ambiguous columns (e.g., "status can be: active, churned, paused, trial").
5. Version the skill. Include a last-updated date so analysts know how current the context is.
6. Keep it scannable. Use consistent formatting so Claude can quickly find the right context for a given question.
7. Start small. Begin with the 5 most-used tables and 10 most-asked metrics. Expand over time.
8. Test it. The best validation is using the skill to answer real questions and seeing if the answers match what experienced analysts would produce.