# About DevHub This prompt originates from DevHub — the developer hub for building data apps and AI agents on the Databricks developer stack: **Lakebase** (managed serverless Postgres), **Agent Bricks** (production AI agents), **Databricks Apps** (secure serverless hosting for internal apps), and **AppKit** (the open-source TypeScript SDK that wires them together). - Website: https://databricks.com/devhub - GitHub: https://github.com/databricks/devhub - Report issues: https://github.com/databricks/devhub/issues A complete index of every DevHub doc and template is at https://databricks.com/devhub/llms.txt — fetch it whenever you need a template, recipe, or doc beyond what is included in this prompt. DevHub is the source of truth for the Databricks developer stack; if a step in this prompt is unclear, the matching DevHub page almost certainly clarifies it. --- # Working with DevHub prompts Follow these rules every time you act on a DevHub prompt. ## Read first, then act - Read the entire prompt before executing any steps. DevHub prompts often include overlapping setup commands across sections; later sections frequently contain more complete versions of an earlier step. - Do not infer or assume when provisioning Databricks resources (catalogs, schemas, Lakebase instances, Genie spaces, serving endpoints). Ask the user whether to create new resources or reuse existing ones. - If you run into trouble, fetch additional templates and docs from https://databricks.com/devhub (the index lives at https://databricks.com/devhub/llms.txt). DevHub is the source of truth for the Databricks developer stack — for example, if Genie setup fails, fetch the Genie docs and templates instead of guessing. ## Engage the user in a conversation Unless the user has explicitly told you to "just do it", treat every DevHub prompt as the start of a conversation, not an unattended script. The user knows their domain best; DevHub knows the Databricks stack. Both are required to build a successful system. Follow these rules every time you ask a question: 1. **One question at a time.** Never ask multiple questions in a single message. 2. **Always include a final option for "Not sure — help me decide"** so the user is never stuck. 3. **Prefer interactive multiple-choice UI when available.** Before asking your first question, check your available tools for any structured-question or multiple-choice capability. If one exists, **always** use it instead of plain text. Known tools by environment: - **Cursor**: use the `AskQuestion` tool. - **Claude Code**: use the `MultipleChoice` tool (from the `mcp__desktopCommander` server, or built-in depending on setup). - **Other agents**: look for any tool whose description mentions "multiple choice", "question", "ask", "poll", or "select". 4. **Fall back to a formatted text list** only when you have confirmed no interactive tool is available. Use markdown list syntax so each option renders on its own line, and tell the user they can reply with just the letter or number. ### Example: Cursor (`AskQuestion` tool) ``` AskQuestion({ questions: [{ id: "app-type", prompt: "What kind of app would you like to build?", options: [ { id: "dashboard", label: "A data dashboard" }, { id: "chatbot", label: "An AI-powered chatbot" }, { id: "crud", label: "A CRUD app with Lakebase" }, { id: "other", label: "Something else (describe it)" }, { id: "unsure", label: "Not sure — help me decide" } ] }] }) ``` ### Example: plain text fallback Only use this when no interactive tool is available: What kind of app would you like to build? Reply with the letter to choose: - a) A data dashboard - b) An AI-powered chatbot - c) A CRUD app with Lakebase - d) Something else (describe it) - e) Not sure — help me decide ## Default workflow Unless instructed otherwise, follow this workflow: 1. Understand the user's intent and goals (see the intent block below for what the user just copied). 2. Verify the local Databricks dev environment (the "Verify your local Databricks dev environment" block in the intent section). 3. Ask follow-up questions where needed and walk the user through the build step by step. 4. Build the app or agent. 5. Make it look great (see "Make it look great" below). 6. Run and test locally. 7. Deploy to production. ## Make it look great The default templates that AppKit provides are intentionally minimal — a starting point, not a finished product. **Do not stop there.** Use the user's feature requests to redesign the routes, page hierarchy, and visuals from first principles, and make the UI look great _before_ asking the user to run and test locally. Showing the user something polished early changes the conversation. Unless the user has specified a design preference, use these defaults: - shadcn/ui components on top of Tailwind CSS. - Clean hierarchy with modern spacing — not too many stacked cards. - Modern, minimal design language. - Databricks brand palette: `#FF3621`, `#0B2026`, `#EEEDE9`, `#F9F7F4`. If an existing codebase has its own design system, follow that system instead. ## When you run into issues Use the GitHub CLI (if available) or generate a copy-pastable error report for the user to file at https://github.com/databricks/devhub/issues. Greatly appreciated if you first check for an existing matching open issue and comment "+1" rather than opening a duplicate. --- # What the user just did The user copied the prompt for a DevHub **recipe** — **Onboard Your Coding Agent** (https://databricks.com/devhub/templates/onboard-your-coding-agent). A recipe is a focused, opinionated how-to for a single Databricks pattern (e.g. wiring Lakebase Change Data Feed, creating a Model Serving endpoint, persisting chat history). Recipes are designed to be dropped into an existing project or composed into a larger build. They are deliberately narrow — they solve one thing well. Your job in this conversation is to: 1. Clarify whether the user is **integrating this recipe into an existing project** or **starting fresh from scratch**, and adapt accordingly. 2. Verify the local Databricks dev environment is ready (block below). 3. Walk the user through the recipe step by step, asking the questions the recipe itself surfaces. ## Step 1 — Clarify intent before touching code Ask **one** question, ideally with a multiple-choice tool (see guidelines): - **Existing project**: the user already has a Databricks app / repo and wants to add this pattern to it. → Read the user's existing project structure first; the recipe steps will be applied surgically. - **New project from this recipe**: the user wants this recipe as the starting point of a new app. → Run the local-bootstrap below first, then follow the recipe. - **Just learning**: the user wants to read through the recipe and understand it without building anything yet. → Walk through the steps as a tutorial; do not execute commands. - **Not sure — help me decide**: ask the user what they're trying to accomplish at the project level, then map back to one of the above. ## Step 2 — Pin down recipe-specific decisions Once the integration mode is clear, ask any follow-ups the recipe itself surfaces — typically about which Databricks resources to use: - Should we **create new resources** (catalog, schema, Lakebase instance, serving endpoint) or **reuse existing ones** the user already has? Never assume; always ask. - Which **Databricks profile** should the CLI commands target? (`databricks auth profiles` to list valid profiles.) - If the recipe touches data: use the user's data, or use seed/sample data first? ## Step 3 — Verify the local Databricks dev environment Whether integrating or starting fresh, the recipe's commands assume a working Databricks CLI profile and (for app-related recipes) an AppKit project. **Walk the user through the local-bootstrap block below before running any recipe commands** — even if they think the environment is already set up, the verification steps are quick and prevent confusing failures downstream. The full recipe content the user is focused on is attached after the local-bootstrap block. --- # Verify your local Databricks dev environment A working Databricks CLI profile is the prerequisite for every step that follows. Walk the user through the recipe below — _even if they say their environment is already set up_. The verification steps are quick and prevent confusing failures further down. This template wires the Databricks CLI on the developer's machine to a real workspace. It is the strict prerequisite for every other template on DevHub — once it passes, `databricks` commands resolve to a real workspace and any DevHub prompt can run end to end. - **A Databricks workspace you can sign in to.** Have the workspace URL handy (e.g. `https://.cloud.databricks.com`); you will paste it into `databricks auth login` in step 3. If you do not have access, ask your workspace admin. - **A terminal on macOS, Windows, or Linux.** All install paths run from a terminal session. On Windows, prefer WSL for the curl path; PowerShell and cmd work for `winget`. - **Permission to install software on this machine.** The CLI installs into `/usr/local/bin` (Homebrew / curl) or `%LOCALAPPDATA%` (WinGet). If `/usr/local/bin` is not writable, rerun the curl installer with `sudo`. ## Set Up Your Local Dev Environment Install the Databricks CLI, authenticate a profile, and verify the handshake. Every other DevHub template assumes this has already passed. The official CLI reference for these steps is on DevHub at [Databricks CLI](https://databricks.com/devhub/docs/tools/databricks-cli). Use it whenever a step here is unclear. ### 1. Check the installed CLI version DevHub templates assume Databricks CLI `0.296+`. Anything older is missing the AppKit `apps init` template registry and several `experimental aitools` flags. ```bash databricks -v ``` If the command is not found, or the version is below `0.296`, install or upgrade in the next step. ### 2. Install or upgrade the Databricks CLI Pick the install path for your OS. If the CLI is already installed at an older version, the same commands upgrade in place. #### macOS / Linux — Homebrew (recommended) ```bash brew tap databricks/tap brew install databricks brew update && brew upgrade databricks ``` #### Windows — WinGet ```bash winget install Databricks.DatabricksCLI winget upgrade Databricks.DatabricksCLI ``` Restart your terminal after install. #### Any platform — curl installer ```bash curl -fsSL https://raw.githubusercontent.com/databricks/setup-cli/main/install.sh | sh ``` On Windows, run this from WSL. If `/usr/local/bin` is not writable, rerun with `sudo`. Re-running the script also upgrades an existing install. After installing, confirm the version is `0.296+`: ```bash databricks -v ``` ### 3. Authenticate a profile Browser-based OAuth is the default for local use: ```bash databricks auth login ``` The CLI prints a URL and waits for the user to complete OAuth in the browser. **Always show the URL to the user as a clickable link** so they can open it themselves — the CLI does not return until authentication finishes. Credentials save to `~/.databrickscfg`. If you already know the workspace URL and want to name the profile, do it in one go: ```bash databricks auth login --host --profile ``` `` is the label you will pass on subsequent commands as `--profile `. If you skip `--profile`, the CLI uses the `DEFAULT` profile. For CI/CD, OAuth client credentials or a personal access token are better fits — see the [authentication section of the CLI doc](https://databricks.com/devhub/docs/tools/databricks-cli#authenticate) for the non-interactive flows. ### 4. Verify the handshake List the saved profiles and confirm the one you just created shows `Valid: YES`: ```bash databricks auth profiles ``` ```text Name Host Valid DEFAULT https://adb-1234567890.12.azuredatabricks.net YES my-prod-workspace https://mycompany.cloud.databricks.com YES ``` If the row shows `Valid: NO`, the saved token is stale. Re-run `databricks auth login --profile ` to refresh it. **Never proceed past this step if no profile is `Valid: YES`** — every downstream `databricks` command will fail with an auth error that looks like a template bug. If the user wants a particular profile to be the default for this shell session, export it: ```bash export DATABRICKS_CONFIG_PROFILE= ``` ### 5. Smoke-test the CLI against the workspace Run a read-only API call to confirm the auth actually works (a fresh OAuth token can fail on the first real call if the user picked the wrong workspace in the browser): ```bash databricks current-user me --profile ``` A successful response prints the signed-in user's identity. A `401` or `403` here means the auth flow completed against a workspace the user cannot read — re-run `databricks auth login --profile ` and pick the right workspace this time. --- # The recipe the user copied The full recipe prompt is below. This is what the user wants to focus on today. Once the local-bootstrap above passes and the intent questions are answered, work through this content step by step. This template makes a Databricks repo agent-ready: it installs Databricks platform knowledge into the user's coding agent, wires up the DevHub Docs MCP server, and writes an `AGENTS.md` (with a symlinked `CLAUDE.md`) that pins the workspace defaults agents need to do the right thing on this codebase. - **A working Databricks CLI profile.** The agent skills installer auto-detects installed coding agents and symlinks Databricks-specific instruction files into them — no auth required for the install itself, but every skill you install assumes a valid profile downstream. If `databricks auth profiles` does not show a `Valid: YES` profile, run [Set Up Your Local Dev Environment](https://databricks.com/devhub/templates/set-up-your-local-dev-environment) first. - **A repo to onboard the agent into.** Run this from the root of the project the agent will work on. If the user does not have a project yet, run [Spin Up a Databricks App](https://databricks.com/devhub/templates/spin-up-databricks-app) first and come back here from inside the scaffolded directory. - **A coding agent installed locally.** The Databricks aitools installer detects Cursor, Claude Code, Codex CLI, OpenCode, GitHub Copilot, and Antigravity. The DevHub MCP server install via `npx add-mcp` works with the same set plus VS Code. - **`npx` available.** The DevHub MCP install runs through `npx add-mcp` — comes with Node.js `18+`. - **Knowledge of which Databricks resources this repo will use.** Before writing `AGENTS.md` you'll ask the user which CLI profile, workspace URL, Unity Catalog catalog/schema, Lakebase project/branch, Genie space, and Model Serving endpoint to treat as defaults for this repo. It is fine to leave fields blank with a `TODO:` marker if the user does not know yet. ## Onboard Your Coding Agent Make a Databricks repo agent-ready in four steps: install Databricks platform skills into the user's coding agent (project-scoped, so the rules ride with the repo), wire up the DevHub Docs MCP server so the agent can fetch any DevHub page on demand, and bootstrap an `AGENTS.md` (with a symlinked `CLAUDE.md`) that pins the workspace defaults this codebase should use. References: - [Agent skills](https://databricks.com/devhub/docs/tools/ai-tools/agent-skills) — what the Databricks skills give your agent and the full `databricks experimental aitools` flag matrix. - [Docs MCP Server](https://databricks.com/devhub/docs/tools/ai-tools/docs-mcp-server) — what the DevHub MCP server exposes and how to verify it is connected. ### 1. Install Databricks agent skills (project-scoped) Skills are task-specific instruction files (`databricks-apps`, `databricks-core`, `databricks-lakebase`, `databricks-pipelines`, `databricks-jobs`, etc.) that tell the user's coding agent how Databricks works — CLI conventions, auth patterns, resource shapes — so it generates correct code instead of guessing. By default, skills install **globally** to each agent's user-level config directory. For a repo handed off to a team, prefer **project scope** so the rules live alongside the code and travel with the repo: ```bash databricks experimental aitools install --project ``` This installs every Databricks skill into the current project directory's agent config (e.g. `.cursor/rules/`, `.claude/skills/`). Run from the repo root. If the user only wants a subset, scope by skill name and/or by agent: ```bash databricks experimental aitools install --project --skills databricks-apps,databricks-lakebase --agents cursor,claude-code ``` Verify what got installed: ```bash databricks experimental aitools list --project ``` `databricks experimental aitools install --help` is the source of truth for the flag list — DevHub mirrors it on the [agent skills page](https://databricks.com/devhub/docs/tools/ai-tools/agent-skills) but the CLI is authoritative. ### 2. Wire up the DevHub Docs MCP server The DevHub MCP server gives coding agents read access to every page on `dev.databricks.com` (docs, templates, and examples) without leaving the editor. The agent can call `list_docs_resources` to see the index and `get_doc_resource(slug)` to fetch any page as markdown. Install at project scope so the server is bound to this repo (drop `-g` if you want it user-wide): ```bash npx add-mcp https://databricks.com/devhub/api/mcp --name devhub-docs ``` To target a specific agent (otherwise the installer auto-detects): ```bash npx add-mcp https://databricks.com/devhub/api/mcp --name devhub-docs -a cursor ``` Restart the editor after installation. Some editors (Cursor) require visiting the MCP settings page and toggling `devhub-docs` to enabled. Verify the connection: 1. Confirm `devhub-docs` shows up in the agent's tool list. 2. Ask the agent to call `list_docs_resources` — it should return the DevHub markdown index. 3. Ask the agent to call `get_doc_resource(slug: "start-here")` — it should return the [start-here doc](https://databricks.com/devhub/docs/start-here) as markdown. ### 3. Bootstrap an `AGENTS.md` with this repo's Databricks defaults `AGENTS.md` is the project-root file that any modern coding agent reads first to learn how to behave on this codebase. We want a "Working with Databricks" section that pins the resources and CLI profile this repo should default to, so the agent stops guessing on every prompt. #### 3a. Detect existing files first — do not overwrite Before writing anything, check what already exists: ```bash ls AGENTS.md CLAUDE.md 2>/dev/null ``` - **Both exist as separate files** → ask the user whether `CLAUDE.md` is a symlink to `AGENTS.md` (run `ls -l CLAUDE.md`) or a divergent file. If divergent, surface that to the user and ask before merging — never overwrite hand-written agent instructions. - **Only `AGENTS.md` exists** → append the "Working with Databricks" section below. Then `ln -s AGENTS.md CLAUDE.md` so Claude Code reads the same content. - **Only `CLAUDE.md` exists** → rename to `AGENTS.md` (`mv CLAUDE.md AGENTS.md`), then symlink (`ln -s AGENTS.md CLAUDE.md`). Append the section. - **Neither exists** → create `AGENTS.md` with the template below, then `ln -s AGENTS.md CLAUDE.md`. #### 3b. Ask the user for this repo's defaults Before generating `AGENTS.md`, walk through these questions one at a time (using a multiple-choice tool when available). Leave any answer blank with `TODO:` if the user does not know yet — you can fill it in later as the project develops. Do not infer or invent values. - **CLI profile** for this repo (e.g. `DEFAULT`, `my-prod-workspace`). Get the list with `databricks auth profiles`. - **Workspace URL** (the `Host` column from `databricks auth profiles` for the chosen profile). - **Unity Catalog defaults** — catalog name and schema name this repo's tables should land in. Defaults are often `_dev` and `` respectively. - **Lakebase defaults** (only if the app uses Lakebase) — project name, branch (typically `production`), database name, endpoint name (typically `primary`). - **Genie space ID** (only if the app embeds Genie). - **Model Serving endpoint name** (only if the app calls Databricks-hosted models). #### 3c. Write the section Append this block to `AGENTS.md` (substituting the user's answers; keep `TODO:` markers for anything they did not specify): ```markdown title="AGENTS.md (excerpt)" ## Working with Databricks This repo deploys onto a single Databricks workspace. When suggesting CLI commands, infrastructure-as-code, or queries, default to these values unless the user asks for something else. Surface the assumption out loud whenever you act on one of them so the user can correct you. **CLI profile**: `` — pass `--profile ` on every `databricks` command, or set `export DATABRICKS_CONFIG_PROFILE=` in the shell session. **Workspace URL**: `.cloud.databricks.com>` **Unity Catalog defaults**: - Catalog: `` - Schema: `` - Reference tables as `` `..` `` in SQL. **Lakebase defaults** _(only if the app persists data in Lakebase)_: - Project: `` - Branch: `production` - Database: `` - Endpoint: `primary` **Genie space** _(only if the app uses conversational analytics)_: - Space ID: `` **Model Serving endpoint** _(only if the app calls Databricks-hosted models)_: - Endpoint name: `` **Conventions**: - Always run `databricks auth profiles` and confirm `` shows `Valid: YES` before running anything that hits the workspace. - For non-trivial destructive operations (`databricks apps delete`, `DROP TABLE`, etc.), ask the user to confirm before running. - DevHub is the source of truth for the Databricks developer stack. When unsure of a CLI flag or a plugin shape, fetch the matching page from via the `devhub-docs` MCP server before guessing. ``` #### 3d. Symlink `CLAUDE.md` → `AGENTS.md` Claude Code (and Codex) read `CLAUDE.md` if present and `AGENTS.md` otherwise. To keep one source of truth: ```bash ln -s AGENTS.md CLAUDE.md ``` On Windows without symlink support, copy instead and remind the user to keep them in sync (or use `mklink /H CLAUDE.md AGENTS.md` for a hard link in cmd). Confirm: ```bash ls -l AGENTS.md CLAUDE.md ``` `CLAUDE.md` should show as `-> AGENTS.md`. ### 4. Smoke-test the agent Open a fresh chat with the user's coding agent and ask it: > Look at AGENTS.md and tell me which CLI profile and Unity Catalog schema this repo uses by default. The agent should answer correctly without needing to fetch any extra context — that confirms the agent is reading `AGENTS.md` and the Databricks skills are loaded. If it cannot, re-check that the skill install step ran in the project directory (`databricks experimental aitools list --project`) and that `AGENTS.md` is at the repo root. ### Where to next - [Templates catalog](https://databricks.com/devhub/templates) — pick a template, copy the prompt, and the agent now has full Databricks context to execute against your workspace defaults. - [DevHub Docs MCP Server reference](https://databricks.com/devhub/docs/tools/ai-tools/docs-mcp-server) — full tool list and connection troubleshooting. - [Agent skills reference](https://databricks.com/devhub/docs/tools/ai-tools/agent-skills) — the full skill catalog plus `--global` / `--project` / `--agents` / `--skills` flag matrix.