# Databricks Solution Builder > Generate comprehensive specification files for building Databricks assets, demos or end 2 end projects. Use when users want to create a new demo, design a demo story, or need help structuring demo components, create an entire project. This skill creates prompts that another agent will execute to build the actual demo. - Skill: `databricks-solutions/databricks-solution-builder` (Agent Skill, multi-file: 269 files) - Install (CLI): `npx skillmds@latest add databricks-solutions/databricks-solution-builder` - Raw SKILL.md: https://api.skillmd.com/api/skills/databricks-solutions/databricks-solution-builder/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: databricks-solutions (https://skillmd.com/u/databricks-solutions) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/databricks-solutions/databricks-solution-builder --- # Databricks Demo Generator A skill for creating and building compelling Databricks demos that Technical Solution Architects will show to enterprise customers across any industry. ## Purpose Generate a **coherent demo package** — a business story that showcases Databricks capabilities. The story must be compelling (a clear protagonist, challenge, and resolution in $), and the technical components must connect end-to-end (data → pipeline → dashboard → agent all align). One key value of this skill: everything generated is fully coherent — the synthetic data serves the story and works as input for every downstream consumer (dashboards, apps, Genie spaces, agents). ## How this skill is organized The main loop lives in this file (SKILL.md) — it describes **the flow**: stages, gates, what each stage produces, when to stop for user input. For **how to execute** a given stage, read the matching `DEMO_SKILL_DIR/stages/NN-*.md` at the moment you enter it. Keep SKILL.md in your context at all times — pull in a stage file **only** when you're actively executing that stage. | Stage | What | User gate at end | Execution guide | |-------|------|------------------|-----------------| | **0. Capture Intent** | Understand request, browse domain/pattern blocks, propose story ideas if vague | — (flows into stage 1) | Inline in SKILL.md | | **1. Design Story** | Write `resources.json` + `README.md` (batched in one message) | ✅ *"Approve the story?"* | `stages/01-design-story.md` | | **2. Write Specs** | Write `01-lakeflow.md`, then the other top-level specs, then the app spec (if app needed), coherence review | ✅ *"Ready to build?"* | `stages/02-write-specs.md` | | **3. Build** — *pick ONE fork (by mode):* | | | | |   ↳ **3.1 Build resources** *(default)* | Provision the Databricks resources via Databricks Agent Skills (DAS) | — (build completes) | `stages/03.1-build.md` | |   ↳ **3.1r Build on real tables** *(grounded / "use existing data")* | Build DIRECTLY on the user's real UC tables, **READ-ONLY** — no data generation | — (build completes) | `stages/03.1r-build-on-real.md` | |   ↳ **3.2 Build a workshop** *(workshop mode)* | Instead of provisioning, generate a notebook workshop (build-it-live via Genie Code) | — (package ready) | `stages/03.2-workshop.md` | | **4. Package as a DAB** (opt) | On user request only, post-build | — | `references/dab/dab.md` | **Cross-cutting (not a stage):** - **App creation** — folded into stages 2 + 3: `DEMO_SKILL_DIR/app/app.md` ### Three entry flows The opening message tells you which of three flows the user started (from the home page's tabs). The stages above are the **default**; two variants change where the run starts or how Build forks. **A — Build the resources (default).** Run stages 0→3.1: design the story, write specs, then **provision the real Databricks resources** (`stages/03.1-build.md`). Deployable demo; DAB optional only if the user asks at the end. > **"Use existing data" variant (build READ-ONLY on the user's real UC tables).** If the opening message says the user picked existing tables (and **`PROJECT/specifications/source-tables.md` exists**), that file holds the selected real tables' **fully-qualified names + schema (column names, types, comments)** — schema only. **Read it FIRST.** You **profile the tables yourself** at build time (read-only, off a warehouse) to get distinct counts / ranges / top values and derive the data capability signals (time columns, measures, dimensions, cross-table join keys) — see `references/grounding-table-stats.md`. If **`PROJECT/specifications/data-discovery.md`** also exists, **read it too** — it records what the user learned exploring these tables during data discovery: the use case they **already chose** (with its data-fit rationale), the alternatives they set aside, and the capability reasoning. Treat that use case as **AGREED SCOPE** — build it; do NOT re-pitch it, swap it for another idea, or contradict the fit findings. The demo is built **DIRECTLY on those real tables, READ-ONLY** — you query them **in place**; you do **NOT** generate synthetic data, do **NOT** copy or re-create them in another catalog, and you **NEVER** write to, alter, or drop them. Then: > - Derive **ONE** coherent **read-only analytics** use case that the real data actually supports. If `data-discovery.md` records a chosen use case, **that IS the one** — build it (don't re-derive a different one); the opening message may also include the user's own text and/or a story they picked — honor it. Ground it in the real column names / distributions in `source-tables.md`; do NOT invent a catalyst or columns the data doesn't have. > - Point **every** component (dashboards, Genie space, metric views, read-only AI functions) at the exact `catalog.schema.table` names from `source-tables.md`. The default capability set is read-only analytics — no ingest/SDP, no write-back app, no Lakebase, no ML training. > - **Build forks to 3.1r:** do NOT run `stages/03.1-build.md`; run **`stages/03.1r-build-on-real.md`** (verify the real tables are readable, then build the read-only components on them). > > **Data-write opt-in.** If — and only if — the opening message / `source-tables.md` header says the user opted into letting the demo add its own supporting data, you MAY generate **auxiliary** tables into the demo's **OWN** catalog/schema (clearly separated) so write-needing capabilities work. **Even then, the user's real tables above remain strictly READ-ONLY — never written to.** Absent that opt-in, create no tables at all. **B — Build a workshop** The SAME demo, delivered as prompts instead of resources: you generate a **package of clean notebooks whose cells are Genie Code prompts** that an SA (or customer) pastes into the Databricks Genie Assistant to build the demo **live, step by step** — raw data (Volume) → SDP → dashboard → Genie space. - **Stages 0–2 UNCHANGED** — story, `resources.json` + `README.md`, specs, as normal. (Capabilities are pre-scoped to workshop-ready ones — no ML/app/KA/MAS in V1.) - **Build forks to 3.2:** do NOT run `stages/03.1-build.md`; run **`stages/03.2-workshop.md`** — notebook workshop + volume-writing data-gen + Genie context, patterned on **`references/example-luxebeauty-workshop`**. - **Deliverable = the downloadable package** (notebooks + data-gen + specs + context), not a deployed demo. No DAB. **C — Architecture first** *(alternate start).* The user wants to draw the architecture before any story. Their text may be a brief, pasted meeting notes, or a transcript. - **Skip stages 0–1** — no story/`resources.json`/`README.md`/specs/build yet. - Read the **`databricks-architecture` skill** (`.claude/skills/databricks-architecture/SKILL.md`) — flat `nodes`/`edges` schema + component catalog + reference diagrams. - **Extract the components** the text implies (sources, pipeline, serving, dashboards/apps, agents), map each to a real catalog id. Start from the minimal example in that skill's **The format** section (or `reference/architecture-complete.jsonc` for the full platform) when intent matches, then patch in the named sources. - **Write ONLY `architecture.md`** at the project root (schema in a fenced ```json block), then **stop** with a one-liner inviting review/edit on the Architecture tab. The story comes later — the user clicks "Generate the solution from this architecture", which kicks off stage 1 *constrained to* the components they kept. ## Paths Your system prompt defines `PROJECT`, `SKILLS`, `DEMO_SKILL_DIR`, and `DEMO_SKILL` as absolute paths. This skill refers to sibling files like `DEMO_SKILL_DIR/stages/*.md`, `DEMO_SKILL_DIR/app/app.md`, `DEMO_SKILL_DIR/references/*`. **When spawning subagents**, substitute every placeholder (`DEMO_SKILL_DIR/…`, `PROJECT/…`, `SKILLS/…`) with its real absolute path before sending — the subagent has no system prompt defining them. The full spawn prompt is in `DEMO_SKILL_DIR/stages/03.1-build.md` → Step 2. --- ## Usage tracking Each stage fires one tracking event so we can see how the skill is used. Calls are inlined per stage below — run them as a single Bash command, ignore the result, move on. Opt out via `DBDEMOS_TRACKER_DISABLED=1`. --- ## Efficiency Batch independent tool calls into one message — the harness runs them concurrently, saving LLM round-trips. Load all reference blocks together; write independent files together. Don't overthink mechanical work (writing files, generating data) — call the real tools and execute, don't narrate when you think. **Subagent policy.** A subagent is used in Stage 3.1 (build) **for the App** — it's the longest task (~5 min) and runs in parallel while the parent builds everything else on main. Stages 0, 1, 2, and 4 run entirely on the main loop, and within Stage 3 only the App is delegated. The full spawn prompt is in `DEMO_SKILL_DIR/stages/03.1-build.md` → Step 2. ### Telling the user where you are Between phases, drop a one-liner so the user always knows where you are in the flow. Examples: - *"Story approved — writing all specs now (~2 min on the main loop)."* - *"Specs ready. Ready to build when you say go."* - *"Stage 3 building. Genie + dashboard subagent running, app subagent running. Continuing with governance meanwhile."* No drawn-out status dumps — one line, then the work continues. ### Output discipline Between tool calls, write about the **problem**, not the file you're about to create. If a sentence describes what the file will contain, put it in the file (comments, code) instead — don't preview it in chat. Don't narrate the act of writing ("writing the script…", "finishing the join…", "still generating…", "Building the materialized view...", Building the query output..." "Writing the daily aggregation view" etc.) — the tool call does that. When spawning a subagent or handing off context, **point at files, don't paraphrase them.** Listing absolute paths is cheaper than summarizing what's inside — your paraphrase costs tokens and goes stale, the subagent's read is fast. Don't pre-digest the spec or the README so the subagent "doesn't have to re-read" — that's the wrong economy. Reading is cheap for them; rewriting is expensive for you. Real thinking (surprising results, tradeoffs, ambiguity, errors) is welcome. File previews and progress updates aren't. --- ## Project Structure ``` ./README.md # Story overview, products showcased, walkthrough ./architecture.md # Architecture diagram schema (JSON) — built on demand (see Architecture Diagram), not by default ./resources.json # Selected capabilities + created resource IDs ./specifications/ # Detailed specs per component — the exact files depend on what the demo includes; there is no fixed list ``` ### resources.json Source of truth for what capabilities the demo includes. Created during spec phase with capabilities, updated during build with resource IDs. Structure mirrors `DEMO_SKILL_DIR/references/example-luxebeauty/resources.json`. You must keep this exact naming convention. **`created_resources` starts empty `{}` and grows one key at a time.** Add a resource's ID key **only after that resource is actually created and validated** (Stage 3, build loop step 5). **Never pre-seed a key** — not with a placeholder like ``, not with `""`, not by copying the example file's keys wholesale. The reference example below shows the *final* shape of a fully-built demo; it is a naming reference, **not a scaffold to paste in up front**. The UI's resource-link builder renders a clickable link for any present, non-empty ID, so a pre-seeded `dashboard_id`/`genie_space_id` becomes a dead link to a resource that doesn't exist yet. **After build** (populated with created resource IDs — do not add links here). **Use these exact key names**; the UI's resource-link builder is wired to them. Skip a section entirely when the demo doesn't include that capability, but do NOT rename keys. Authoritative reference: `DEMO_SKILL_DIR/references/example-luxebeauty/resources.json`. Lakebase sub-keys are defined in `DEMO_SKILL_DIR/app/app.md`. ```json { "capabilities": { "buildable": [...], "talking_track": [...] }, "created_resources": { "workspace_folder": "/Workspace/Users//luxebeauty_demo", "catalog": "luxebeauty", "schema": "demo_c360", "warehouse_id": "abc123def456...", "pipeline_id": "12ab34cd-5678-...", "metric_view_name": "luxebeauty.demo_c360.mv_returns", "dashboard_id": "01efab12cd34...", "genie_space_id": "abc123...", "knowledge_assistant_id": "ka-456...", "knowledge_assistant_endpoint": "ka-15956b19-endpoint", "multi_agent_supervisor_id": "mas-789...", "multi_agent_supervisor_endpoint": "mas-15956b19-endpoint", "ml_model_name": "luxebeauty.demo_c360.customer_premium_classifier", "mlflow_experiment_path": "/Workspace/Users//luxebeauty/experiments/premium_classifier", "app": { "name": "luxebeauty-demo", "id": "app-luxebeauty-1234", "deployment_note": "Deployed via `databricks apps deploy` — see app.md Step 6" }, "lakebase_project_id": "", "lakebase_project_slug": "dbdemos-asset-generator", "lakebase_database": "dbgen_luxebeauty" } } ``` Notes on the trickier keys: - **Multiple resources of the same type (e.g. a 2nd dashboard added when iterating).** Add another key that ENDS IN THE SAME CANONICAL SUFFIX with a descriptive prefix — e.g. a second dashboard is `labor_economics_dashboard_id` (NOT `dashboard_2` or `second_dashboard`), a second Genie space is `pipeline_health_genie_space_id`, a second job is `recovery_job_id`. The suffix (`_dashboard_id`, `_genie_space_id`, `_job_id`, …) is what the UI link-builder AND the cross-workspace ownership reconcile match on — a key that doesn't end in the canonical suffix is invisible to both, so the resource gets no link/tile and is NEVER re-homed to you (it stays owned by the deployer SP). This is essential on ITERATE turns: when you add a resource to an already-built demo, record it with a suffix-matching key so it's granted to the triggering user like everything else. - **`mlflow_experiment_path`** — required when the demo trains an ML model. Full workspace path passed to `mlflow.set_experiment(...)`. Without it the MLflow Experiment tile never appears in the resources grid (the UI resolves the path → numeric experiment_id via the SDK). - **`app` is nested** (`app.name`, `app.id`, `app.deployment_note`). **Record `app.name` as soon as the app's initial setup is done (scaffold + config) — do NOT wait for deploy.** `app.name` alone marks the app capability "built" in the UI, so a preview-only app that never deploys still counts as complete. Add `app.id`/`app.url` later, only after `databricks apps deploy`. If the deploy fails or is intentionally skipped, keep `app.name` and put the explanation in `deployment_note`. - **Lakebase keys are three flat fields**, not nested. See `app.md` for `lakebase_setup_db.sh` which prints them. - **buildable**: capabilities that require actual Databricks resources (pipelines, dashboards, agents, apps, etc.) - **talking_track**: capabilities mentioned in the demo narrative but don't require resource creation - **created_resources**: filled during build phase — keys match the resource type (e.g., `pipeline_id`, `dashboard_id`, `genie_space_id`) Capability IDs come from `DEMO_SKILL_DIR/references/platform_architecture.md`. When the user provides exact capabilities, use those directly — don't override with pattern suggestions. ### Architecture Diagram Don't write `./architecture.md` by default. Build it **on demand** — when the user asks for an architecture diagram (or starts architecture-first) — always by reading the **`databricks-architecture` skill** (`.claude/skills/databricks-architecture/SKILL.md`). --- ## Context Blocks & Platform Architecture **Always start by reading `DEMO_SKILL_DIR/references/platform_architecture.md`** — it shows the complete Databricks platform capabilities with dependencies, all product IDs and categories, and when to use each capability. `DEMO_SKILL_DIR/references/blocks/capabilities` details Databricks products — selling points, positioning, how to showcase unique value, common pitfalls. Read them when you need deeper product knowledge for story or spec writing (typically dashboards or ML model training) --- ## Storytelling Fundamentals The demo is a **Databricks Pitch**. Keep it simple. Regardless of pattern, every demo needs a great story. A great demo has: - **A clear protagonist** — Named persona with a business role and a challenge - **Business metrics in $** — "$500K at risk" lands; "720 records" doesn't - **A wow moment** — The point where the platform does something impressive (root cause in 60 seconds, prediction prevents downtime, NL question returns a complete answer) - **A clear value statement** — "Days → minutes", "$2M saved annually" ### Keep It Simple - **Accessible domains** — Retail, manufacturing, healthcare, finance. Everyone gets "returns went up" or "this machine is about to fail." - **Business language** — Revenue, cost, customers (in $). Not technical jargon. - **One clear challenge** — Focused narrative, easy to follow. **The rule**: if you have to explain the business domain before the demo, pick a simpler domain. --- ## Modifying an Existing Project When the project already has files (`README.md`, `resources.json`, `specifications/`), don't restart from stage 0. Instead: 1. **Read existing state** — `README.md`, `resources.json`, and any `specifications/*.md` files. 2. **Understand the user's request** — what they want to change (story, capabilities, a specific spec, a built resource). 3. **Check the story still holds** — does the existing README + data support the new ask? If the new component needs data or a story beat that isn't there yet, the story comes first: update `README.md` and the upstream specs (typically `01-lakeflow.md` for data, `02-uc-governance.md` for permissions) BEFORE writing the new component spec. 4. **Make targeted changes** — update only the affected files. Keep everything else consistent. 5. **Propagate changes downstream** — if you change the story or data schema, update all specs that reference those values. If you change a spec, update the built resource if it exists (regenerate data, restart the SDP pipeline, refresh the dashboard, re-run training, etc.). Then update `resources.json` with any new IDs. 6. **App changes** — **if the user asks about anything app-related (adding a page, changing an agent tool, updating theming, data model, re-generating, debugging, deploying), read `DEMO_SKILL_DIR/app/app.md` FIRST.** Don't improvise from memory. Non-negotiable principles while working on the app: - **Don't start the app.** The Demo Prompt Generator UI supervises the app's process; a separate `./start.sh` collides with it. - **One-shot smoke tests only** — if you must run it to validate a change, run it once on a random port, then kill it immediately (see `app.md` Step 5 for the exact pattern). Leaving it running is a bug. - **Never deploy the app on your own.** "Deploy resources" / "deploy the demo" means everything except the app. Deploy the app **only** when the user says "deploy the app" / "push the app" / similar explicit wording. The flow is in `app.md` Step 6. 7. **Spec-writing standards**: if you're editing `specifications/*.md`, read `DEMO_SKILL_DIR/stages/02-write-specs.md` for the standards (functional specs, temporal realism, coherence contracts, etc.). The coherence contract still applies: every change must ripple through all dependent files. ### Worked example — user asks to add a component the project doesn't have Generic pattern when adding a new capability (app, ML model, dashboard, etc.) to a project that didn't originally include it: 1. **Find example** — check `DEMO_SKILL_DIR/references/blocks/capabilities/.md` if you need to know more about it and always `DEMO_SKILL_DIR/references/example-luxebeauty/specifications/` for an existing spec of the same capability. Mirror its shape if you don't have a lot of instructions. 2. **Story fit** — does the existing demo arc justify this component? If no, extend the README story beat before writing the spec. 3. **Upstream prerequisites** — does this need new data, a new column, a new dashboard viz, a new model output? If so, patch the upstream specs (`01-lakeflow.md`, etc.) first, regenerate the data, update and re run the sdp pipeline if required and only then write the new component spec. 4. **Write the new component spec when required** — under `specifications/`, following the standards in `stages/02-write-specs.md`. 5. **Build it** — follow `stages/03.1-build.md` for the build order (data → pipeline → consumption layers). 6. **App-specific path** — if the new component is an app, ALSO read `DEMO_SKILL_DIR/app/app.md` end-to-end (it walks the clone-template → specialize → deploy flow that's specific to the React/Node app, not the rest of the demo). 7. **Update `resources.json`** — add the new resource's IDs / endpoints / paths to `created_resources` so the UI tiles light up and the capabilities after the addition/changes. --- ## Brand personalization (`brand/brand.json`) To personalize a demo to a **real company**, if the user gives you one, search the web for its official website, proper name, and main color palette, and write `brand/brand.json` (everything brand-related lives in the `brand/` folder at the project root): ```json { "company": "Rolls-Royce", "palette": ["#10069F", "#C0A062"], "website": "https://www.rolls-roycemotorcars.com", "company_logo": "company_logo.svg", "company_official_website_screenshot": "website.png" } ``` `company_logo` and `company_official_website_screenshot` (both optional) are **bare filenames relative to the `brand/` folder** (i.e. `brand/company_logo.svg`, `brand/website.png`) — the app builder uses the logo in the app header and the screenshot as visual inspiration. The user can ask you to skip this whole step and fill in the info themselves — then just read `brand/brand.json` if it's present. No `brand/brand.json` = not brand-personalized; that's fine. The app builder consumes it at the end of app generation (see `DEMO_SKILL_DIR/app/app.md`). **When brand-personalized, weave the company name into the story too** — the app's big title, the README persona/company, and the narrative should name the real company (e.g. " Returns Console", not "LuxeBeauty"). The demo should read as *that company's* solution end to end, not a generic story with a recolored app. The full app-side brand match (palette across all tokens, logo in header + favicon + title, real-site-driven layout) is the LAST step of `DEMO_SKILL_DIR/app/app.md`. --- ## Stage 0 — Capture Intent **Before assessing anything, check for a captured brief.** If `context/source-brief.md` exists (the user pasted a substantial spec on the home page) OR there are files under `context/uploads/`, **read them in full first** — that content is the authoritative statement of intent, higher-fidelity than any summary you'd write. When a real brief is present: - **Treat it as "Detailed"** (below) unless it's genuinely thin — the user has already done the thinking; don't re-ideate or propose alternatives. - **Lossless intake is the rule.** Preserve the brief's specifics — named entities, personas, metrics, numbers, data sources, requirements, and phrasing — through every stage. Your job is to *realize* the spec, not to compress it into a tidier story. A long, careful spec must produce a correspondingly rich demo; if you find yourself dropping details to fit the README template, the template yields, not the spec. - **`context/source-brief.md` stays the source of truth.** The `README.md` you write in Stage 1 is a *derived* artifact (a presenter's summary), not a replacement for the brief. At every later stage, if the README and the brief disagree or the README is thinner, **re-read `context/source-brief.md`** and defer to it. Never let your own summary become the thing you build from. First, assess the user's input — how much is already decided? **Vague** ("retail demo", "something with IoT"): full ideation needed. 1. Propose 2–3 story ideas combining domain terminology with the pattern's arc. Title format: "[Domain]'s [challenge]". Keep it brief. If the user does a followup, consider you're now a Moderate ``` 1. **Regional bank's fraud spike** — VP of Fraud Ops sees card fraud losses jump 3x. Traces it to compromised POS terminals at a merchant chain. 2. **Hospital system's readmission surge** — CMO investigates why heart failure patients keep returning within 30 days. Uncovers a discharge protocol gap. 3. **Auto manufacturer's quality mystery** — Plant director sees defect rates climb on one line. Traces it to a worn bearing in Station 7. Suggested stack: synthetic-data-gen, sdp, aibi-dashboards, genie + lakeflow-connect, genie-code, genie-one, unity-catalog Pick one, combine ideas, or describe something else / add capabilities. ``` **Moderate** ("fraud detection demo for a bank using data from xx, with dashboards + Genie to investigate suspicious transactions"): story direction is clear but needs fleshing out. 1. Propose a short story (~3-5 sentences, see below). Confirm it against `platform_architecture.md`, ask questions if something isn't clear — no need to propose alternatives. **Detailed** (full PRD with protagonist, catalyst, narrative arc already defined): the user has done the thinking. Skip ideation — go straight to stage 1, making sure you have the right capabilities in mind. ## Stage 1 — Design Story **Read `DEMO_SKILL_DIR/stages/01-design-story.md` now** and follow it. Outputs: `resources.json`, `README.md` at the project root (don't create the architecture file unless asked for it). **Gate — ask the user before continuing, unless instructed otherwise:** ``` I've created the demo story in README.md. Narrative: [VERY VERY brief summary the narrative, easy to read] **Should I go ahead and generate the detailed specification files?** Reply "yes" to continue, or let me know what to change. ``` Wait for confirmation before starting stage 2. **Track this stage:** run `python3 DEMO_SKILL_DIR/tools/track.py STORY_APPROVED ` after the user approves; ignore the result and move on. ## Stage 2 — Write Specs **Read `DEMO_SKILL_DIR/stages/02-write-specs.md` now** and follow it. Outputs: `specifications/*.md`. Includes the coherence pass at the end. **Mental model before you start:** write `01-lakeflow.md` first (everything else depends on it). Then write the remaining top-level specs (02 / 03 / 04 / 05, only the ones this demo uses). Then, if the demo includes a Databricks App, write `specifications/app/*.md`. Sequential — one Write per file. **Don't ruminate, don't say "now I'll write X" — open the Write tool and write.** Coherence review at the end. **Track this stage:** run `python3 DEMO_SKILL_DIR/tools/track.py SPECS_WRITTEN ` once specs are all written; ignore the result and move on. **Gate — ask the user before continuing unless instructed otherwise:** Say for example (don't mention / describe all the files) ``` Demo specifications are ready in `./specifications/` . Would you like me to build the demo resources now? Reply "yes" to start building, or "no" to stop here. ``` ## Stage 3 — Build If the user confirms, **read `DEMO_SKILL_DIR/stages/03.1-build.md` now** and follow it. It covers: build-order gates, subagent parallelization, how to spawn a build subagent, app generation, and sync rules between specs and built resources. **Mental model before you start:** build time dominates this stage. The pipeline is the only sequential gate (raw data → SDP → tables exist). Once tables exist, fan out — Genie/Dashboard, KA/MAS, and the App all run as parallel subagents. Never loop through resources one at a time on the main thread. **Track this stage:** run `python3 DEMO_SKILL_DIR/tools/track.py BUILD_COMPLETE ` once `resources.json.created_resources` is populated; ignore the result and move on. ## Stage 4 — Package as a DAB (optional) When the user asks you to create a DAB, read `DEMO_SKILL_DIR/references/dab/dab.md` and create the DAB specification. **Author + verify only — don't deploy.** Write the bundle, scripts, and `dab_instructions.md` and validate them; do NOT run `bundle deploy` / `bundle run` or the deploy scripts unless the user explicitly asks to deploy (they mutate a workspace). --- ## Reference Materials Browse `DEMO_SKILL_DIR/references/` for worked examples showing file format, detail level, and how files connect. Two examples ship — pick the one that matches the build's capability set: - **`example-luxebeauty/`** — full-stack reference (SDP bronze→silver→gold, metric view, ML premium classifier, KA, MAS, app with tiered offers). Use when the build includes any of `sdp` / `metric-views` / `ml-training-serving` / `knowledge-assistant` / `supervisor-agent`. - **`example-luxebeauty-simple/`** — Simple-tab set (in-script synth → raw→silver→gold, no SDP; AI/BI + Genie; optional App + Lakebase; no ML/KA/MAS). Use when the build sticks to that subset. Ships two **syntax-reference** artifacts (rewrite fully per demo — they show shape, not content): `data_generation/generate_data.py` (self-contained Spark: `spark.range` + `F.when` + broadcast joins → raw Delta → `spark.sql` CTAS for silver/gold/constraints) and `dashboard/dashboard.json` (populated Lakeview: 5-stop palette, frame descriptions, sankey top-N, color pins). Adapt the structure, don't copy the narrative. Every story, schema, widget, position, color, and description must be rewritten for the current demo — the artifacts only show what a working file *looks like*, not what to put in one. --- ## Key Principles 1. **Story first** — Start with "what question does the protagonist ask?" not "what components do we need?" 2. **Coherence above all** — Data, pipeline, dashboard, Genie, agents must all align: data must support the story and the story must be visible in the components (dashboard, genie etc). One broken link ruins the demo. 3. **5-second test** — The key insight must be obvious at a glance on any dashboard. The story must be compelling ("something clearly happened" and we clearly see it) 4. **Business metrics in $** — Revenue, cost, impact. Not row counts. 5. **Match products to moments** — Every showcased product earns a clear beat in the walkthrough 6. **Functional specs** — Describe outcomes, not implementation. No API calls or code in spec files. --- ## Handling Unknown Components When the user requests a Databricks feature you're not familiar with: 1. Check if a capability block exists in `DEMO_SKILL_DIR/references/blocks/capabilities/`. 2. If not, fetch documentation from `https://docs.databricks.com/llms.txt`. 3. Understand what value it adds to the demo. 4. Write functional specs (what it should do, inputs, outputs). Don't refuse — learn and adapt. --- ## Flexibility Everything in this skill is a **default**. The user is in control: - User wants different components? Follow their lead. - User wants a different story pattern? Do it. - User wants to skip the walkthrough? Fine. - User has specific requirements that contradict these defaults? User wins. **Your job**: help the user create a great demo, whatever that looks like for them.