Claude Skills Examples: 8 SKILL.md Files for Data Work, Validated (2026)

monthly-kpi-report/
├── SKILL.md              ← required: front matter + instructions
├── references/
│   └── metrics.md        ← read only when the instructions point to it
└── assets/
    └── report-template.md

---
name: sql-style-guide
description: Applies the team's SQL style rules when writing, reviewing or reformatting SQL for PostgreSQL, BigQuery or Snowflake. Use when the user asks for a query, pastes SQL to clean up, or asks why a query is hard to read.
license: Apache-2.0
metadata:
  owner: data-team
  version: "1.0"
---
 
# SQL style guide
 
Apply these rules to every query you write or edit. When reviewing someone else's SQL, list each rule it breaks with the line it breaks it on, then give the corrected query.
 
## Layout
 
- Keywords in lowercase: `select`, `from`, `left join`, `group by`.
- One clause per line. Each selected column on its own line, indented four spaces, with trailing commas.
- Use CTEs (`with ... as`) instead of subqueries nested more than one level deep.
- Name each CTE for what it holds: `paid_orders`, not `t1` or `cte2`.
 
## Names
 
- snake_case for tables, columns and aliases.
- Alias every table in a join with a short, meaningful name: `o` for orders is fine, `a` and `b` are not.
- Booleans start with `is_` or `has_`. Timestamps end with `_at`. Dates end with `_date`.
 
## Joins and filters
 
- Always write the join type (`inner join`, `left join`). Never use comma joins.
- Once more than one table is involved, qualify every column with its table alias.
- Filters that define the population go in `where`. Filters that define one metric go in `count(*) filter (where ...)` (PostgreSQL) or `countif(...)` (BigQuery) or `count_if(...)` (Snowflake).
 
## Safety
 
- No `select *` in anything saved, scheduled or shared.
- Never write `delete` or `update` without a `where` clause, and show the matching row count first.
- Filter timestamps with half-open ranges: `created_at >= '2026-10-01' and created_at < '2026-11-01'`. Never use `between` on timestamps.
 
## Example
 
Before:
 
    SELECT * FROM orders a, customers b WHERE a.customer_id = b.id AND a.created_at BETWEEN '2026-10-01' AND '2026-10-31'
 
After:
 
    select
        o.order_id,
        o.created_at,
        o.amount,
        c.country
    from orders as o
    inner join customers as c
        on o.customer_id = c.customer_id
    where o.created_at >= '2026-10-01'
        and o.created_at < '2026-11-01'

---
name: monthly-kpi-report
description: Builds the monthly KPI report from the analytics warehouse, comparing the closed month with the prior month and the same month last year. Use when the user asks for the monthly report, month-end KPIs, a monthly business review, or month-over-month and year-over-year numbers.
license: Apache-2.0
metadata:
  owner: finance-analytics
  version: "1.2"
---
 
# Monthly KPI report
 
## Steps
 
1. Confirm the month. Default to the last fully closed calendar month. Never report a month that is still in progress.
2. Read [references/metrics.md](references/metrics.md) and compute every metric listed there exactly as defined. Do not add metrics or change a definition. If a metric cannot be computed, say which one and why.
3. For each metric, get three values: the report month, the prior month, and the same month a year earlier. Compute the month-over-month and year-over-year change in percent.
4. Flag any metric that moved more than 20% month over month in either direction. Before calling it a business change, check for a data cause: missing days, a source that loaded late, or duplicated rows.
5. Fill in [assets/report-template.md](assets/report-template.md), keeping its section order.
6. End with the exact queries you ran, so a reviewer can rerun them.
 
## Formatting
 
- Thousands separators on every number. Currency with no decimals. Percentages with one decimal.
- State the time zone used for month boundaries: UTC unless the user says otherwise.
- If the prior-year month has no data, write "n/a", never 0.

# Metric definitions
 
All metrics use UTC month boundaries and exclude rows where `customers.is_test = true`.
 
| Metric | Definition | SQL expression (PostgreSQL) |
| --- | --- | --- |
| Revenue | Sum of paid order amounts, net of refunds, in the month the order was paid | `sum(o.amount) - coalesce(sum(r.amount), 0)` over `orders o left join refunds r using (order_id)` where `o.paid_at` is in the month |
| New customers | Customers whose first paid order falls in the month | `count(*)` of customers where `min(o.paid_at)` is in the month |
| Active customers | Customers with at least one paid order in the month | `count(distinct o.customer_id)` where `o.paid_at` is in the month |
| Churn rate | Active customers last month with no paid order this month, divided by active customers last month | `1 - (retained / active_last_month)` |
| Average revenue per active customer | Revenue divided by active customers | `revenue / nullif(active_customers, 0)` |
 
Do not compute any other metric for this report.

---
name: chart-style
description: Applies house chart conventions (chart type, colours, titles, axis labels, number formats) to any chart made in matplotlib, Plotly, Vega-Lite or a BI tool. Use when the user asks for a chart, plot, graph or dashboard tile, or asks to make charts look consistent.
license: Apache-2.0
---
 
# Chart style
 
## Pick the chart type
 
- Change over time: line chart. Bars only for 12 or fewer periods.
- Comparing categories: horizontal bar chart, sorted largest first.
- Parts of a whole: stacked bar. A pie chart only for two or three parts.
- Distribution of one measure: histogram or box plot.
- Relationship between two measures: scatter plot.
 
## Text
 
- The title states the finding ("Revenue grew 12% in October"), not the axes ("Revenue by month").
- The subtitle gives the metric definition, unit, date range and data source.
- Label axes with units. Drop an axis label that only repeats the title.
- Label the last point of each line directly instead of relying on a legend.
 
## Colour
 
- One highlight colour, `#2563EB`, for the series that matters. Grey, `#9CA3AF`, for context series.
- At most six categorical colours, in this order: `#2563EB`, `#F59E0B`, `#10B981`, `#EF4444`, `#8B5CF6`, `#6B7280`.
- Never make red and green the only difference between two series.
 
## Numbers
 
- Bar chart value axes start at zero.
- Thousands as 12.3K, millions as 4.5M. Percentages with one decimal.
 
## matplotlib
 
Load the house style before plotting: `plt.style.use("assets/house.mplstyle")`, with the path resolved from this skill's folder. It sets the fonts, the colour cycle and the grid; the rules above still apply.

---
name: data-dictionary-lookup
description: Looks up what a warehouse table or column means, its grain, its source system and its known caveats before any query is written. Use when the user names a table or column, asks where a number comes from, or asks which table holds a field such as revenue, plan, signup date or churn.
license: Apache-2.0
---
 
# Data dictionary lookup
 
Before writing SQL against the warehouse, find each table you plan to use in the files below and read its entry. Read only the file for the domain you need.
 
| Domain | Tables | File |
| --- | --- | --- |
| Sales | orders, refunds | [references/sales.md](references/sales.md) |
| Customers | customers, subscriptions | [references/customers.md](references/customers.md) |
| Product usage | events | [references/product-usage.md](references/product-usage.md) |
 
## Rules
 
- Respect each table's grain. Never join two tables at different grains without aggregating one of them first.
- Apply every caveat listed for a table, such as excluding test accounts.
- If a table or column isn't in the dictionary, say so and ask. Don't infer its meaning from its name.

## refunds
 
- Grain: one row per refund. An order can have several.
- Source: the billing system, loaded hourly.
- Key columns: `refund_id`, `order_id`, `amount`, `refunded_at`.
- Caveats: aggregate to one row per `order_id` before joining to `orders`, or revenue double-counts.

---
name: csv-cleaning-checklist
description: Profiles and cleans a CSV or TSV file before analysis, covering encoding, delimiter, header row, column types, missing values, duplicates and inconsistent categories, and reports every change made. Use when the user uploads or points to a CSV, says a file is messy, or a load or query on file data fails.
license: Apache-2.0
compatibility: Requires Python 3.9 or later; uses the standard library only
---
 
# CSV cleaning checklist
 
## 1. Profile before changing anything
 
Run the profiler from this skill's folder:
 
    python scripts/profile_csv.py path/to/file.csv
 
It prints the detected encoding and delimiter, row count, duplicate rows, and for each column: missing values, distinct values, inferred type, values with stray spaces, and categories that differ only by letter case. Show the user this profile before cleaning.
 
## 2. Work through the checklist in order
 
1. Encoding: re-save as UTF-8 if the profile says otherwise.
2. Header: exactly one header row; rename columns to snake_case.
3. Whitespace: trim leading and trailing spaces in every text column.
4. Types: convert each column to its inferred type. List the values that fail conversion instead of silently dropping them.
5. Missing values: treat empty strings, `NA`, `N/A`, `null` and `-` as missing. Don't fill them unless the user says how.
6. Categories: merge values that differ only by case or spacing ("Paid", "paid ", "PAID").
7. Duplicates: remove exact duplicate rows only. Report near-duplicates without removing them.
 
## 3. Report and save
 
- Write the cleaned data next to the original with `.clean.csv` added to the name. Never overwrite the original.
- End with a table of every change: step, column, rows affected.

---
name: analysis-writeup
description: Writes up an ad-hoc data analysis as a one-page brief with the question, the answer, the evidence, the method, the caveats and the next step, in that order. Use when the user asks to summarise findings, write up an analysis, or turn query results into a note for a stakeholder.
license: Apache-2.0
---
 
# Analysis write-up
 
Use this structure and keep it to one page. Lead with the answer; the reader may stop after the first two sections.
 
```markdown
# [The question, phrased as the stakeholder asked it]
 
## Answer
[One or two sentences with the number and what it means. No hedging words unless a caveat below requires them.]
 
## Evidence
[A table or chart of the numbers behind the answer, with units and date range.]
 
## How we got it
[Data sources, filters, time zone, and the definition of every metric used. Link or paste the queries.]
 
## Caveats
[What could make the answer wrong: missing data, small samples, definitions that differ from other reports.]
 
## Next step
[The one decision or follow-up this enables.]
```
 
## Rules
 
- Every number in the Answer must appear in the Evidence.
- Round to the precision the decision needs: "about 18%", not "17.94%", unless the reader asked for exact figures.
- If the data can't answer the question, say so in the Answer section and explain why in Caveats.

---
name: dbt-model-conventions
description: Enforces the project's dbt conventions for model layers, file names, materializations, tests and documentation when creating or editing dbt models. Use when working on files under models/ or when the user asks for a new staging, intermediate or mart model.
paths:
  - "models/**/*.sql"
  - "models/**/*.yml"
allowed-tools: Bash(dbt compile *) Bash(dbt build --select *) Bash(dbt ls *)
---
 
# dbt model conventions
 
## Layers and names
 
| Layer | Folder | File name | Materialization |
| --- | --- | --- | --- |
| Staging | `models/staging/<source>/` | `stg_<source>__<entity>.sql` | view |
| Intermediate | `models/intermediate/` | `int_<entity>_<verb>.sql` | ephemeral |
| Marts | `models/marts/<domain>/` | `fct_<event>.sql` or `dim_<entity>.sql` | table, or incremental above 10 million rows |
 
- Staging models select from exactly one `source()` and only rename, cast and filter deleted rows. No joins.
- Marts select only from staging or intermediate models through `ref()`, never from `source()`.
- One model per file. The file name is the model name.
 
## Every model needs
 
- A primary key with `unique` and `not_null` tests in the model's `.yml` file.
- A one-line `description` for the model and for every column a mart exposes.
- `relationships` tests on foreign keys in fact tables.
 
## Before you finish
 
Run `dbt build --select <model_name>+` and fix every failing test. Report the command and its result.

---
name: query-review
description: Reviews a SQL query for correctness before it is shared or scheduled, checking grain, join fan-out, filters, NULL handling, time zones and cost.
argument-hint: "[path-to-sql-file]"
disable-model-invocation: true
context: fork
agent: Explore
---
 
# Query review
 
Review the SQL in $ARGUMENTS. Read the file, and any files it includes, before judging it.
 
Check each item and report it as OK or as a problem with the line number and a fix:
 
1. Grain: state what one output row represents. Flag any join that can multiply rows (one-to-many without aggregation first).
2. Filters: test accounts excluded, date ranges half-open, no filter on the right-hand table of a left join that silently turns it into an inner join.
3. NULLs: aggregates and comparisons that drop or miscount NULLs, such as `count(column)` where `count(*)` was meant, or `not in` against a column that can be NULL.
4. Time zones: every timestamp converted to one stated time zone before grouping by day or month.
5. Cost: full scans of large tables without a partition or date filter, and `select *` against wide tables.
 
End with a one-line verdict: ready to share, or the problems to fix first.