exmergo/dex / claude/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 | 50.2 KB |
| evals/evals.json | config | 14.5 KB |
| references/commands.md | markdown | 81.4 KB |
| references/declarations.md | markdown | 68.5 KB |
| references/edit-kinds.md | markdown | 5.7 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 | 2.1 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.0 KB |
references/init-and-dev-target.md
View on GitHub# Bootstrapping a project and preparing the dev target
What you must and must not do is in `SKILL.md`; this file is the per-connector
detail.
## Complete setup with `init`
Use `init` through this skill's `scripts/run.py` wrapper for complete onboarding.
`init <name> --connector <c>` creates a dbt-backed Dex project.
`init <name> --mode demo` adds the local seeded DuckDB warehouse.
`init --mode adopt` adopts existing dbt without replacing its configuration or
profiles, and `init --mode explore` configures exploration without creating dbt.
A standalone semantic
setup is preserved. When several projects exist, select `--project-dir <path>`.
The repository root holds `.dex/`, the README, and agent instructions. Named dbt
projects live below it; `.` or `--in-place` uses the root. Existing configuration
changes require the returned diff to be confirmed. Reruns preserve authored
content and update only managed README/procedure sections. Initialization verifies
the connection, reports `data.readiness`, and names missing inputs and recovery
steps. It never explores data, builds models, or answers spending questions.
Installing skills does not necessarily install a `dex` executable.
## Legacy `transform init "<name>" --connector <c>`
The engine renders the whole skeleton (`dbt_project.yml`, `models/staging/` and
`models/marts/`, a `profiles.yml` with a single `dev` target and no secrets) and
records `connector`, `dbt_project_dir`, and `dbt_target: dev` in
`.dex/config.yml`. Init never assumes a connector: it errors rather than
defaulting, and a `connector:` already committed in `.dex/config.yml` also
counts. Init refuses if any dbt project already exists.
| Connector | Dev target and auth |
|---|---|
| DuckDB | needs a warehouse path (`--path`, or `duckdb.path` in config) |
| BigQuery | needs a GCP project (usually `bigquery.project`; confirm it with the user); builds go to `bigquery.dev_dataset` (default `dbt_dev`); auth is Application Default Credentials (`gcloud auth application-default login`) |
| Snowflake | builds go to `snowflake.dev_database` / `dev_schema` on the pinned warehouse |
| Databricks | builds go to `databricks.dev_catalog` / `dev_schema` on the pinned SQL warehouse; missing credentials: `databricks auth login` |
| Postgres | builds go to `postgres.dev_schema` (default `dbt_dev`); the password reaches dbt only through `PGPASSWORD` |
| Redshift | builds go to `redshift.dev_schema` (default `dbt_dev`); with `redshift.workgroup` pinned the profile renders IAM auth (temporary credentials from the AWS chain), otherwise the password reaches dbt only through `REDSHIFT_PASSWORD` |
| ClickHouse | builds go to `clickhouse.dev_database` (default `dbt_dev`), rendered as the profile's `schema:` because dbt-clickhouse has no `database:` key; the password reaches dbt only through `CLICKHOUSE_PASSWORD`; the profile's `custom_settings` block turns the confirmed budget into a per-statement server-side cap |
| Trino | builds go to `trino.dev_catalog`.`dev_schema` (default `dbt_dev`); dbt creates the schema but never the catalog, so `dev_catalog` must exist and be writable (a `tpch`, `tpcds`, `jmx`, `system` or `faker` catalog is refused; `memory` and `blackhole` warn); the user, password or token reach dbt only through `TRINO_USER`, `TRINO_PASSWORD` or `TRINO_JWT_TOKEN`; the profile's `session_properties` block turns the confirmed budget into a per-statement server-side cap |
Every connector discovers its connection and refuses with the fix named when
none resolves.
### `--in-place`
The default layout scaffolds into a `<name>/` subdirectory. Pass `--in-place` to
scaffold directly into the current directory instead (useful when the repository
root is itself the dbt project).
### `--layered-schemas`
When the user wants staging, intermediate, and marts isolated in their own
datasets or schemas (common when the warehouse is shared with unrelated work),
`--layered-schemas` also scaffolds `models/intermediate/`, a
`generate_schema_name` override, and per-folder `+schema:` config, so builds land
in `staging_dev`, `intermediate_dev`, and `marts_dev`. An existing project can
adopt it later with `transform macro generate_schema_name`. dbt warns about
"unused configuration paths" until the first model lands in each layer folder;
that resolves itself.
### The namespace warning
Init checks, free and metadata-only, whether each namespace the project would
build into already holds content, and warns naming the namespace and a few
object names. A "could not check" note means no connection was reachable at init
time.
## Preparing the dev target
Before the cost gate, and for free, `transform build` refuses two things and
names the fix for each, so both surface on the unconfirmed call.
**Config that has drifted from the profile.** `transform init` renders
`.dex/config.yml` into `profiles.yml`, and dbt reads only the profile from then
on. If a later config edit never reached it (a retargeted `dev_database`, a
different warehouse), the build refuses and names both values and both files.
The engine never rewrites `profiles.yml`, which may legitimately be hand-edited.
Retarget the config side with `dex config set snowflake.dev_database <name>` (or
the connector's own key), which shows the diff before writing; the profile
still has to be changed to match.
**A dev target that does not exist.**
- Snowflake: dbt creates schemas but never databases, so a missing
`dev_database` is refused with the `CREATE DATABASE` statement to run.
- Postgres, Redshift, ClickHouse: dbt creates the dev namespace only if the
profile's user may, so the missing privilege is refused with the
`CREATE SCHEMA` / `GRANT` statement to run. On ClickHouse the check can come
back with no verdict when the server hides another user's grants; it then warns
and the build proceeds with dbt's own error as the backstop.
- Trino: dbt creates the dev schema but never the catalog, so a missing
`dev_catalog`, or one whose connector cannot be written, is refused before
dbt runs. Write permission is not checked: Trino exposes no grant table, so
dbt's own error is the backstop.
- DuckDB: the dev target is a database file, and dbt would create an empty one,
then fail every `source()` relation with a confusing catalog error. Copy the
shared source warehouse to the dev target path (for example
`cp shared/f1.duckdb <project>/dev.duckdb`), or point the dev target at an
existing file. A project without sources just gets a warning and an empty
database, which is fine for model-only builds.
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: 197k | Updated | Claude CodeCodex | Verified | Install |