exmergo/dex / skills/transform
transform
VerifiedUse this to author and change a dbt project or a semantic layer: bootstrap a project (`transform init`), write or refactor models from staging to marts, add tests and docs, and define semantic models, entities, dimensions, and metrics in MetricFlow, Apache Ossie or SLayer YAML. Reach for it instead of editing model files by hand whenever a change spans more than one file or must stay consistent with the project: it validates the edit against the real schema, returns a reviewable diff with a plan id, and catches what otherwise fails at `dbt run`, such as wrong columns or broken refs. Bug-fix tickets count: "this model returns wrong numbers, fix it" is a transform task. Also for "build a staging model for this table", "define a revenue metric", "add a dimension to this entity". Warehouse builds are dev-target only, gated, and cost-surfaced first. If you have not verified the source tables' columns or grain, use explore first. For a project that drifted from the warehouse, use maintain.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 51.6 KB |
| evals/evals.json | config | 14.5 KB |
| references/commands.md | markdown | 87.2 KB |
| references/declarations.md | markdown | 88.5 KB |
| references/edit-kinds.md | markdown | 5.9 KB |
| references/feature-retirement.md | markdown | 11.7 KB |
| references/feature-toggles.md | markdown | 12.2 KB |
| references/incremental-repairs.md | markdown | 9.9 KB |
| references/init-and-dev-target.md | markdown | 6.4 KB |
| references/macros.md | markdown | 5.9 KB |
| references/model-versions.md | markdown | 9.0 KB |
| references/prerequisite-repairs.md | markdown | 18.0 KB |
| references/semantic-layer.md | markdown | 24.7 KB |
| references/test-strength.md | markdown | 5.8 KB |
| scripts/run.py | script | 31.8 KB |
references/edit-kinds.md
View on GitHub# The edits payload and every edit kind
You author the file content; the engine validates it, computes the diffs, and
stores the proposal as a plan. What you must and must not do is in `SKILL.md`;
this file is the payload's shape and each kind's rules.
## The payload
Hand content over with `--edits-file <path>` (or `-` to read stdin):
```json
{"edits": [
{"path": "models/staging/stg_orders.sql", "kind": "model_sql", "content": "..."},
{"path": "models/staging/stg_orders.yml", "kind": "schema_yml", "content": "..."},
{"path": "snapshots/snap_orders.sql", "kind": "snapshot_sql", "content": "..."},
{"path": "seeds/country_vat.csv", "kind": "seed_csv", "content": "..."},
{"path": "tests/assert_totals_reconcile.sql", "kind": "test_sql", "content": "..."},
{"path": "analyses/email_skew.sql", "kind": "analysis_sql", "content": "..."},
{"path": "models/marts/dim_orders.sql", "kind": "model_sql", "op": "delete"}
]}
```
Beside `edits`, `transform plan` also takes `declarations`
([declarations.md](declarations.md)) and a `toggle` contract for a flag that
stays live ([feature-toggles.md](feature-toggles.md)). `transform remove var`
takes a `retirement` contract instead
([feature-retirement.md](feature-retirement.md)). A command that does not read a
contract refuses it rather than dropping it, and one payload never carries both.
## Kinds and what each must be
A new version of an existing model is a `model_sql` edit for the version's file
and a `schema_yml` edit giving the model a `versions:` list. It is never a second
plain model named `<model>_v2`. Recipe: [model-versions.md](model-versions.md).
| Kind | Where | Must be |
|---|---|---|
| `model_sql` | model paths | a single read-only SELECT once its jinja is stripped |
| `schema_yml` | beside a model, snapshot, seed, test, or analysis | YAML dbt accepts |
| `semantic_yml` | model paths | validated against MetricFlow's schemas, cross-reference-checked, and parsed by dbt; optional on `semantic define\|update\|plan`, which imply it |
| `macro_sql` | macro paths | only macro definitions and jinja comments |
| `snapshot_sql` | snapshot paths | exactly one `{% snapshot %}` block whose `config()` names a `unique_key` and a `strategy` of `timestamp` (with `updated_at`) or `check` (with `check_cols`), with a single read-only SELECT body |
| `seed_csv` | seed paths | CSV with a named, duplicate-free header and one field per column on every row, under 5,000 data rows and 1 MiB |
| `test_sql` | test paths | either `{% test %}` blocks only (a generic test definition, balanced, plus jinja comments) or a single read-only SELECT (a singular test) |
| `analysis_sql` | analysis paths | a single read-only SELECT, even though dbt only compiles it |
| `packages_yml` | project root | the guarded way to declare a dbt package |
| `project_yml` | project root `dbt_project.yml` | keeps a `name` |
| `profiles_yml` | project root `profiles.yml` | every secret as exactly `{{ env_var('NAME') }}` (an empty default at most); a literal credential, a non-empty default, or anything beside the reference is refused so none reaches the diff |
Config kinds, snapshots, and seeds are all parsed by dbt at plan time.
Each kind is confined to its own family of paths, and filing one in the wrong
family is refused naming both fixes. `schema_yml` is the exception, because that
is where dbt expects a snapshot's tests, a seed's column types, a singular test's
severity, and an analysis's description.
A seed past the row or size limit is data rather than a lookup: load it into the
warehouse and `source()` it. A seed whose header names a column that looks like
personal data is refused, and the refusal names the `pii_overrides` entry a human
can add. A seed file the plan creates warns instead where the column's strongest
flag is exactly at the threshold and comes from its header name alone (a `*_note`
column read as free text), naming the same entry; a column a profile flagged, a
rewrite of an existing seed, and any stronger flag still refuse.
A singular test that names no `ref()` or `source()` is warned about, not refused:
it runs against nothing and passes unconditionally.
## Three things called a test
- **Generic tests** are declared inside a `schema.yml` (`data_tests:` on a model
or a column).
- **Unit tests** come from `transform test --scaffold <model>`, which writes a
`unit_tests:` block, also `schema_yml`.
- **Singular tests and generic test definitions** are files under `test-paths`,
and `test_sql` is their kind.
`transform test --mutate <model>` measures all three at once (and, with
`--downstream`, the tests of the models that read it), since a defect has
to get past every one of them to reach production.
## Building what you authored
`dbt build` runs seeds, snapshots, and singular tests natively, so
`transform build` after an apply is all it takes. A snapshot writes a table and a
test runs a scanning SELECT, so both are priced in the cost handshake; a seed
scans nothing and an analysis is never built, so neither is. A singular test and
an analysis build no relation and nothing can `ref()` either, so neither enters
`maintain`'s drift baseline, and deleting one raises no dangling-reference guard.
## `op`: upsert and delete
`op` is `upsert` (the default: create or update, carrying `content`) or `delete`
(remove the file, no `content`). A delete is a reviewable diff like any other, so
a refactor is one plan rather than a plan plus a manual `rm`.
Deletes are guarded: the plan is refused if any surviving file still `ref()`s a
deleted model, naming the offenders. Deleting a project override of a package
model, in the same plan that removes its `+enabled: false`, is accepted: the
package's model answers the name again. Carry the edits that remove those
references in the same plan, so the post-change project is validated as one
unit. A surviving reference Dex cannot resolve statically is warned about rather
than refused. An unconfirmed delete against a file a human edited after planning
surfaces as `needs_confirmation`, never a silent removal.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |