Skip to content

Install most skills from databricks-agent-skills via databricks aitools#562

Draft
dustinvannoy-db wants to merge 14 commits into
mainfrom
install-from-databricks-agent-skills
Draft

Install most skills from databricks-agent-skills via databricks aitools#562
dustinvannoy-db wants to merge 14 commits into
mainfrom
install-from-databricks-agent-skills

Conversation

@dustinvannoy-db

@dustinvannoy-db dustinvannoy-db commented Jun 11, 2026

Copy link
Copy Markdown
Collaborator

Summary

Reworks both installers (install.sh / install.ps1) so that most Databricks skills are sourced from databricks/databricks-agent-skills by delegating to databricks aitools install (Databricks CLI v1.0.0+), instead of bundling them in this repo. Implements .local/implementation_plan_INSTALL_DAS.md.

New skill source map

Source Skills Mechanism
databricks/databricks-agent-skills 26 skills (9 stable + 17 experimental; databricks-execution-compute excluded from defaults) databricks aitools install --scope … --agents … --skills …
This repo (bundled) databricks-genie copy, as before
mlflow/skills 8 MLflow skills raw fetch @ main (MLFLOW_REF override)
databricks-solutions/apx databricks-app-apx raw fetch @ latest stable tag, currently v0.3.8 (APX_REF override)

The agent-skills inventory is discovered live via databricks aitools list -o json (so new upstream skills flow into the all profile automatically), with a hardcoded v0.2.3 snapshot as offline fallback.

Key behaviors

  • CLI gate: agent skills require Databricks CLI v1.0.0+. Interactive installs get a guided upgrade loop (run upgrade / re-check / skip / abort); silent installs fail with instructions.
  • Ownership: aitools owns the agent skills after install (aitools list|update|uninstall). The installer manifest only tracks skills it installs directly. Profile changes uninstall dropped agent skills via aitools uninstall.
  • Stale-copy cleanup: aitools will not overwrite a pre-existing real directory with the same skill name (verified against CLI v1.0.0), so the manifest cleanup removes old bundled copies of now-agent-managed names before delegating. Upgrades from older installs were validated end to end.
  • Gemini CLI / Windsurf / Kiro (not supported by aitools): skills are symlinked from the aitools canonical store (.databricks/aitools/skills); if no aitools-supported tool is selected, a throwaway temp-dir install stages the files for copying so no unselected agent dirs are touched. Windows falls back to copying when symlink creation is not permitted.
  • Renames (breaking): adopts upstream names — databricks-bundles → databricks-dabs, databricks-spark-declarative-pipelines → databricks-pipelines; databricks-config replaced by databricks-core, databricks-lakebase-autoscale/-provisioned by databricks-lakebase. Explicit --skills requests for old names are migrated with a warning; unknown names fail loudly.
  • Ref resolution: apx latest resolves to the highest stable semver tag via git ls-remote (no GitHub API rate limits; INCLUDE_PRERELEASES=1 to allow -rc tags). New env vars: APX_REF, MLFLOW_REF, SKILLS_CHANNEL, INCLUDE_PRERELEASES.
  • New --dry-run prints resolved refs, the exact aitools command, and the delivery plan, then exits without changes. A skills.lock in the scope-local state dir records resolved refs/SHAs and the aitools release.
  • Profiles, --list-skills, the interactive custom picker, and help text are reworked around the new names/sources.

Deviations from the plan (evidence-driven)

  1. Copilot agent token is copilot, not github-copilot (verified against the CLI).
  2. Added the stale-copy cleanup above — required because aitools silently skips existing real dirs.
  3. Tag/SHA resolution uses git ls-remote instead of the GitHub tags API after hitting 403 rate limits during testing.
  4. Old skill names warn-and-migrate on explicit requests instead of silently not matching, so saved profiles and scripted installs survive the rename.
  5. Inventory drift since the plan was written (v0.2.1 → v0.2.3): databricks-vector-search is now stable and databricks-lakeflow-connect exists; handled by the dynamic discovery.

Testing

  • install.sh: full silent project installs in sandbox dirs (claude+gemini and gemini-only), profile-change cleanup incl. aitools uninstall, stale-copy upgrade replacement, rename migration, unknown-skill failure, --dry-run, --list-skills against the live 0.2.3 inventory, apx tag resolution to v0.3.8, lockfile contents.
  • install.ps1: parses clean (PowerShell 7.5.4 parser), --list-skills and silent --dry-run produce output identical to bash on macOS pwsh. Not yet executed on real Windows — the symlink-privilege fallback and winget upgrade path need a Windows smoke test before merge.

Follow-ups (out of scope)

  • Remove the now-unbundled skill directories from databricks-skills/.
  • Update old skill names mentioned in databricks-builder-app/README.md and databricks-mcp-server/README.md.

This pull request and its description were written by Isaac.

@dustinvannoy-db
Install most skills from databricks-agent-skills
1077a4d
@dustinvannoy-db
Make MCP server opt-in/deprecated and clean up both installers
7f0662e 
Delegate the MCP venv build to databricks-mcp-server/setup.{sh,ps1} (new
canonical setup scripts) instead of inlining it in the installers. MCP now
defaults off with an experimental-style "Deprecated MCP Server" opt-in prompt
and a --mcp flag.

Also fixes the verified bash/PowerShell divergences from review:
- Claude global MCP path -> ~/.claude.json on Windows (was ~/.claude\mcp.json)
- $script:Profile_ typo in the Cursor-global message
- remove dead check_sdk_version (SDK check moved into setup scripts)
- add the Claude update-check SessionStart hook on Windows
- defer_loading parity; consolidate the three MCP-JSON writers into one
- env-var parity (DEVKIT_* + DEVKIT_BRANCH/AIDEVKIT_BRANCH alias)
- prompt_channel uses is_interactive; scope prompt reuses the shared selector
- generate the custom-skills picker from the live inventory
- PowerShell JSON writers init $existing and merge independent of the venv

Co-authored-by: Isaac
@dustinvannoy-db
Fix silent installer abort when MCP opt-in prompt is declined
e049bc6 
prompt_mcp_install ended with `[ "$selected" = "yes" ] && INSTALL_MCP=true`,
which returns exit code 1 when the user picks "Do not install" (the default).
Called bare under `set -e`, that aborted the installer before any skills were
installed — with no error and no files written. Only triggered interactively;
silent/non-interactive runs return earlier. Use an if-block so it returns 0.

Co-authored-by: Isaac
@dustinvannoy-db
Shorten scope-prompt hints so they don't wrap and corrupt the redraw
56a365b 
The scope radio prompt's hints ("Install in current directory (.cursor/,
.claude/, .gemini/)") exceeded the terminal width once the arrow, dot, and
padded label were added, wrapping to two physical lines. The cursor-up redraw
in radio_select / Select-Radio counts logical lines, so each arrow press
stacked another copy of the menu. Shorten both installers' scope hints.

Co-authored-by: Isaac
@dustinvannoy-db
Harden interactive selectors against line wrapping
e723c8d 
Long hints could wrap past the terminal width, desyncing the cursor-relative
redraw in the arrow-key selectors (each keypress stacked another copy of the
menu). Make the selectors structurally immune regardless of content:

- bash (checkbox_select, radio_select, skill-profile picker): disable line
  wrap (DECAWM, ESC[?7l) while drawing and restore it (ESC[?7h) on exit and in
  the EXIT trap, so the terminal clips overlong lines to one physical row.
- PowerShell (Select-Checkbox, Select-Radio, skill-profile picker): truncate
  each hint to the remaining window width before printing.

Co-authored-by: Isaac
@dustinvannoy-db
Deliver agent skills to every selected tool, not just gemini/windsurf…
c9b7a85 
…/kiro

`databricks aitools install` only fans out to a subset of agents — at project
scope it installs for Claude Code and Cursor and explicitly skips Copilot,
Codex, OpenCode, and Antigravity ("does not support project-scoped skills"),
while still populating the canonical store. Previously the installer only
symlinked the store into gemini/windsurf/kiro, so those skipped tools got no
skills.

Generalize delivery to symlink the canonical store into every selected tool's
skills dir, leaving entries aitools already created (e.g. Claude/Cursor) to
aitools. The temp-dir staging + copy fallback still applies when no
aitools-supported agent is selected. Mirrored in install.ps1; dropped the now
-unused UNSUPPORTED_AGENT_TOOLS / Get-UnsupportedSkillDirs.

Co-authored-by: Isaac
@dustinvannoy-db
Remove the stable/experimental release channel
ee5d47c 
Drop the channel concept entirely: no release-channel prompt, no --experimental
flag / DEVKIT_CHANNEL env var, no re-download-and-re-exec from the experimental
branch, and no experimental banners in the summaries. The installer always uses
the same path (latest release, or DEVKIT_BRANCH/AIDEVKIT_BRANCH). Installing a
subset of databricks-agent-skills is done by picking a profile (e.g.
--skills-profile data-engineer) instead of all.

Unchanged: the separate `aitools install --experimental` flag (auto-added when a
selected agent skill is experimental) and SKILLS_CHANNEL (raw-fetch dev knob).

Co-authored-by: Isaac
@dustinvannoy-db
Add --experimental true|false to control experimental agent skills
65993e1 
Default true (current behavior: profiles and "all" include experimental
databricks-agent-skills). Pass --experimental false (or DEVKIT_EXPERIMENTAL=
false) to install only stable skills — experimental ones are filtered out of
profile/"all" selections, and the aitools --experimental flag is then omitted.
Explicit --skills requests are always honored as named, even experimental ones.

Co-authored-by: Isaac
@dustinvannoy-db
Suppress aitools "does not support project-scoped skills" notices
5ecd402 
aitools prints "Skipped <agent>: does not support project-scoped skills" for
agents it can't install at project scope (Copilot, Codex, OpenCode,
Antigravity). The installer delivers to those tools itself via the canonical
store, so the notice is just noise. Filter that specific line out of aitools'
output on the non-silent path while keeping everything else (and real errors).

Co-authored-by: Isaac
@dustinvannoy-db
Only show MCP-enable next-steps when the MCP server was installed
30302ef 
When MCP isn't selected (the default now), the summary no longer prints the
MCP setup instructions that don't apply: "Enable MCP in Cursor", Copilot's
"Configure Tools ... enable databricks", and "Restart Windsurf to pick up the
databricks MCP server". Skills-only next-steps (Agent mode, launch/open the
tool, try a prompt) still print, with correct step numbering.

Co-authored-by: Isaac
@dustinvannoy-db
Generalize the final next-step prompt suggestion
ff710f7 
Replace the "Try: List my SQL warehouses" line in the summary with a general
statement to start prompting the AI assistant to interact with Databricks.

Co-authored-by: Isaac
@dustinvannoy-db
Custom skill picker: always require databricks-core
10f764f 
Deselecting everything in the custom picker left USER_SKILLS empty, so
resolve_skills fell through to installing ALL skills. Force databricks-core
into the selection (guaranteeing a non-empty explicit list) and warn when it's
the only skill chosen. Mirrored in install.ps1.

Co-authored-by: Isaac
@dustinvannoy-db
Empty profile selection drops into the custom skill picker
f637167 
Deselecting every option on the profile screen previously defaulted to
installing all skills. Instead, treat an empty interactive selection as
"custom" and show the individual skill picker (which preselects core and
requires databricks-core). The silent/non-interactive default stays "all".

Co-authored-by: Isaac
@dustinvannoy-db
Show databricks-core as locked-on in the custom skill picker
c179538 
Add an optional "lock" field to the checkbox selectors: a locked item is always
checked and can't be toggled off. Mark databricks-core locked (with a
"(required)" hint) in the custom picker so users can see it's always installed
and can't deselect it. Mirrored in install.ps1 (Locked item property).

Co-authored-by: Isaac
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@dustinvannoy-db