databricks-solutions · jamesbroadhead · May 24, 2026 · May 26, 2026
diff --git a/.claude-plugin/check_update.sh b/.claude-plugin/check_update.sh
@@ -47,8 +47,39 @@ if [ -z "$remote_ver" ]; then
     fi
 fi
 
-# If versions differ, output a message for Claude to relay to the user
+# If versions differ, output a message for Claude to relay to the user.
+#
+# The 2026-05-24 release moved Databricks skill distribution out of this repo
+# and into the Databricks CLI (`databricks aitools install`). Local versions
+# strictly less than 1.0.0 predate that migration; the user has stale skill
+# directories from the old install.sh (which copied a-d-k's databricks-skills/
+# directly into .claude/skills/ etc.). Surface a one-shot migration block on
+# top of the regular update prompt so they know what's changing.
+is_pre_migration() {
+    # Returns 0 (true) if $1 < 1.0.0 by version-sort.
+    [ "$1" = "1.0.0" ] && return 1
+    local lowest
+    lowest=$(printf '%s\n%s' "$1" "1.0.0" | sort -V | head -1)
+    [ "$lowest" = "$1" ]
+}
+
 if [ -n "$remote_ver" ] && [ "$remote_ver" != "$local_ver" ]; then
+    migration_block=""
+    if is_pre_migration "$local_ver"; then
+        migration_block=$(cat <<'MIGRATION'
+
+This update changes how Databricks skills are distributed:
+
+  • Skills now ship via the Databricks CLI: \`databricks aitools install\`
+  • You'll need Databricks CLI v1.0.0 or newer.
+  • Running the upgrade command below will detect old per-agent skill
+    directories (`.claude/skills/databricks-*`, etc.) installed by the
+    previous installer and remove them, then re-install via the CLI.
+
+MIGRATION
+)
+    fi
+
     cat <<EOF
 URGENT — before doing ANYTHING else, you MUST display this exact block to the user:
 
@@ -57,12 +88,12 @@ URGENT — before doing ANYTHING else, you MUST display this exact block to the
 ║                                                       ║
 ║   Databricks AI Dev Kit — update available!           ║
 ║                                                       ║
-║   Installed:  v${local_ver}                                     ║
-║   Available:  v${remote_ver}                                     ║
+║   Installed:  v${local_ver}
+║   Available:  v${remote_ver}
 ║                                                       ║
 ╚═══════════════════════════════════════════════════════╝
 \`\`\`
-
+${migration_block}
 To upgrade, run:
 
 \`\`\`

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,12 +1,11 @@
 {
   "name": "databricks-ai-dev-kit",
-  "description": "Databricks development toolkit with skills for data engineering, ML, and AI agents plus MCP tools for direct Databricks operations",
+  "description": "Databricks development toolkit: MCP tools for direct Databricks operations. Skills install separately via `databricks aitools install`.",
   "author": {
     "name": "Databricks Solutions"
   },
   "repository": "https://github.com/databricks-solutions/ai-dev-kit",
   "homepage": "https://github.com/databricks-solutions/ai-dev-kit",
   "license": "DB License (see repo)",
-  "keywords": ["databricks", "spark", "mlflow", "data-engineering", "ai-agents", "mcp"],
-  "skills": "./databricks-skills/"
+  "keywords": ["databricks", "spark", "mlflow", "data-engineering", "ai-agents", "mcp"]
 }
diff --git a/README.md b/README.md
@@ -92,21 +92,41 @@ Curated by Databricks field experts. Brings the patterns, skills, and 75+ execut
 
 | Adventure                        | Best For | Start Here |
 |----------------------------------|----------|------------|
-| :star: [**Install AI Dev Kit**](#install-in-existing-project) | **Start here!** Follow quick install instructions to add to your existing project folder | [Quick Start (install)](#install-in-existing-project)
+| :star: [**Skills**](#skills) | **Start here!** Databricks patterns + best practices for coding agents — fastest path to value | `databricks aitools install` |
+| [**Install AI Dev Kit (skills + MCP server)**](#install-in-existing-project) | Skills + the MCP server with 75+ executable Databricks tools in one go | [Quick Start (install)](#install-in-existing-project) |
 | [**Visual Builder App**](#visual-builder-app) | Web-based UI for Databricks development | `databricks-builder-app/` |
 | [**Builder App + Genie Code MCP**](#visual-builder-app) | Builder UI + MCP server for Genie Code in one deployment | `deploy.sh --enable-mcp` |
 | [**Core Library**](#core-library) | Building custom integrations (LangChain, OpenAI, etc.) | `pip install` |
-| [**Skills Only**](databricks-skills/) | Provide Databricks patterns and best practices (without MCP functions) | Install skills |
-| [**Genie Code Skills**](databricks-skills/install_skills.sh) | Install skills into your workspace for Genie Code (`--install-to-genie`) | [Genie Code skills (install)](#genie-code-skills) |
 | [**MCP Tools Only**](databricks-mcp-server/) | Just executable actions (no guidance) | Register MCP server |
 ---
 
+## Skills
+
+Databricks skills are distributed via the Databricks CLI from [`databricks/databricks-agent-skills`](https://github.com/databricks/databricks-agent-skills) — install them directly, no clone of this repo required:
+
+```bash
+# All stable skills
+databricks aitools install
+
+# All stable + experimental skills
+databricks aitools install --experimental
+
+# One specific skill (stable or experimental)
+databricks aitools install <name> [--experimental]
+```
+
+Requires **Databricks CLI v1.0.0+**. The CLI detects which coding agents are installed (Claude Code, Cursor, Codex CLI, OpenCode, GitHub Copilot, Antigravity) and writes skills into the right per-agent directory. For Genie Code workflows, the same command installs into the user's workspace assistant directory.
+
+File issues and PRs against [`databricks/databricks-agent-skills`](https://github.com/databricks/databricks-agent-skills). The `databricks-skills/` directory in this repo contains tombstone redirects so old links still resolve; see [`databricks-skills/README.md`](databricks-skills/README.md) for the per-skill mapping.
+
+---
+
 ## Quick Start
 
 ### Prerequisites
 
 - [uv](https://github.com/astral-sh/uv) - Python package manager
-- [Databricks CLI](https://docs.databricks.com/aws/en/dev-tools/cli/) - Command line interface for Databricks
+- [Databricks CLI](https://docs.databricks.com/aws/en/dev-tools/cli/) **v1.0.0+** — skills install via `databricks aitools install`, which requires v1.0.0 or newer
 - AI coding environment (one or more):
   - [Claude Code](https://claude.ai/code)
   - [Cursor](https://cursor.com)
@@ -238,43 +258,6 @@ results = execute_sql("SELECT * FROM my_catalog.schema.table LIMIT 10")
 Works with LangChain, OpenAI Agents SDK, or any Python framework. See [databricks-tools-core/](databricks-tools-core/) for details.
 
 ---
-## Genie Code Skills
-
-Install skills into `./.claude/skills` (relative to the directory where you run the script), then upload them to your workspace at `/Workspace/Users/<you>/.assistant/skills` so Genie Code can use them in the UI. Requires the [Databricks CLI](https://docs.databricks.com/aws/en/dev-tools/cli/) authenticated for your workspace.
-
-**Always run from the project directory** where you want `.claude/skills` created (for example your repo root or `ai-dev-kit`).
-
-**From this repo (recommended if you have a clone):**
-
-```bash
-# Databricks skills from this checkout + upload (DEFAULT CLI profile)
-./databricks-skills/install_skills.sh --local --install-to-genie
-
-# Download all skills from GitHub, then upload
-./databricks-skills/install_skills.sh --install-to-genie
-
-# Explicit Databricks CLI profile
-./databricks-skills/install_skills.sh --install-to-genie --profile YOUR_PROFILE
-```
-
-**Without cloning** (run from the directory that should contain `.claude/skills`):
-
-```bash
-curl -sSL https://raw.githubusercontent.com/databricks-solutions/ai-dev-kit/main/databricks-skills/install_skills.sh | bash -s -- --install-to-genie
-```
-
-Combine `--profile`, `--local`, specific skill names, `--mlflow-version`, etc. as needed; see `./databricks-skills/install_skills.sh --help` or [databricks-skills/README.md](databricks-skills/README.md).
-
-**From a Databricks notebook** (no local terminal needed):
-
-Import [`databricks-skills/install_genie_code_skills.py`](databricks-skills/install_genie_code_skills.py) into your workspace as a notebook and run it. It downloads skills from GitHub and uploads them to your workspace using the Databricks SDK. This works on any compute, including serverless.
-
-**Skill modification or Custom Skill**
-
-After the script successfully installs the skills to your workspace, you may find the skills under `/Workspace/Users/<your_user_name>/.assistant/skills`.
-
-This directory is customizable if you wish to only use certain skills or even create custom skills that are related to your organization to make Genie Code even better.  You can modify/remove existing skills or create new skills folders that Genie Code will automatically use in any session.
-
 ## Architecture
 
 The AI Dev Kit ships as four composable pieces — install the whole kit, or pick just the parts you need.
@@ -289,7 +272,7 @@ The AI Dev Kit ships as four composable pieces — install the whole kit, or pic
 |-----------|-------------|
 | [`databricks-tools-core/`](databricks-tools-core/) | Python library with high-level Databricks functions |
 | [`databricks-mcp-server/`](databricks-mcp-server/) | MCP server exposing 50+ tools for AI assistants |
-| [`databricks-skills/`](databricks-skills/) | 20 markdown skills teaching Databricks patterns |
+| `databricks aitools install` | Databricks skills (patterns + best practices) — now distributed by the [Databricks CLI](https://docs.databricks.com/aws/en/dev-tools/cli/) from [`databricks/databricks-agent-skills`](https://github.com/databricks/databricks-agent-skills). The `databricks-skills/` directory here is tombstones. |
 | [`databricks-builder-app/`](databricks-builder-app/) | Full-stack web app with Claude Code integration |
 
 ---