Promote aitools skills-management commands to top-level (#4917)

## Summary

Promotes the **aitools skills-management surface** out of
`experimental/` so the stable half lives at `databricks aitools …` and
slots in next to the other top-level command groups. The matching
**interface changes** (`--scope` enum, `--project`/`--global`
deprecation, `--agents` auto-detect doc) live in a stacked follow-up:
**#5234**.

This is mostly a move, but it is not move-only — see [Non-move
changes](#non-move-changes) below.

- Source files for `install`, `update`, `uninstall`, `list`, `version`
(and the agents/installer libs they depend on) physically move from
`experimental/aitools/` to `cmd/aitools/` + `libs/aitools/`, matching
the existing `cmd/apps/` + `libs/apps/` layout. OWNERS, Taskfile, and
the pr-checklist skill are updated to match.
- The top-level command is registered at `databricks aitools …`.
- **Keeps the `tools` subtree under `experimental/aitools/`** — `query`,
`discover-schema`, `get-default-warehouse`, `statement …` — because
`tools.go` still says "There are no stability guarantees for these
tools".
- The old paths under `databricks experimental aitools
install/update/uninstall/list/version` and `databricks experimental
aitools skills install/list` keep working as **deprecated
backward-compat aliases** that print a notice pointing at the new path
(via cobra's `Deprecated` field).

The aitools skills-management surface is feature-complete after the 5-PR
series (#4810–#4814) that added state tracking, lifecycle commands, and
project scope support. The `tools` subtree is functionally useful but
its shape is still in flux, so promoting only the stable half.

## Non-move changes

In addition to the file moves, this PR:

- Removes the redundant `aitools/README.md` (apps/pipelines don't carry
one); the same info lives in the command's Long description.
- Rewrites the Long description on the new top-level `databricks
aitools` command.
- Adds a deprecation notice to every legacy alias under `databricks
experimental aitools` (Lennart's review ask — they used to forward
silently).
- Refactors how the legacy `experimental aitools skills install [name]`
wrapper is wired: the wrapper now lives in
`cmd/aitools/legacy_skills.go` alongside the install code it wraps, and
the previously-exported test-injection vars (`InstallSkillsForAgentsFn`,
`ListSkillsFn`, `PromptAgentSelection`) are back to unexported. The two
now-empty experimental files (`experimental/aitools/cmd/skills.go` and
`skills_test.go`) are deleted.

## What's not in this PR

These are deliberately separated and reviewed independently:

- **#5234** — `--scope=project|global|both` flag, deprecation of
`--project`/`--global` via `cobra.Deprecated`, `--agents` auto-detect
help text.
- **#5233** (draft) — `--output json` on `databricks aitools list`.

## Command shape after this PR

```
# Stable, top-level
databricks aitools install      # use --skills <name>[,<name>...] for specific skills
databricks aitools update
databricks aitools uninstall
databricks aitools list
databricks aitools version

# Backward-compat aliases (print deprecation notice; point at the new paths)
databricks experimental aitools install/update/uninstall/list/version
databricks experimental aitools skills {list,install}

# Experimental, unchanged path
databricks experimental aitools tools query
databricks experimental aitools tools discover-schema
databricks experimental aitools tools get-default-warehouse
databricks experimental aitools tools statement {submit,get,status,cancel}
```

## Test plan

- [x] `databricks aitools --help` shows
install/update/uninstall/list/version (no `tools`)
- [x] `databricks --help` lists `aitools` in the output
- [x] `databricks experimental aitools install` prints a deprecation
notice and still forwards
- [x] `databricks experimental aitools tools query …` runs as before
- [x] `databricks experimental aitools tools --help` lists
query/discover-schema/get-default-warehouse/statement
- [x] Existing aitools tests pass; the legacy-wrapper tests moved with
the wrapper to `cmd/aitools/legacy_skills_test.go`

This pull request was AI-assisted by Isaac.

---------

Co-authored-by: simon <simon.faltum@databricks.com>
Co-authored-by: simon <4305831+simonfaltum@users.noreply.github.com>

Author: jamesbroadhead

.agent/skills/pr-checklist/SKILL.md

@@ -22,8 +22,8 @@ Before submitting a PR, run these commands to match what CI checks. CI uses the
 # 5. If you changed files in python/:
 ./task pydabs-codegen pydabs-test pydabs-lint pydabs-docs
 
-# 6. If you changed experimental/aitools or experimental/ssh:
-./task test-exp-aitools   # only if aitools code changed
+# 6. If you changed cmd/aitools/, libs/aitools/, experimental/aitools/, or experimental/ssh/:
+./task test-exp-aitools   # only if aitools code changed (top-level or experimental)
 ./task test-exp-ssh       # only if ssh code changed
 ```
 

.github/OWNERS

@@ -59,6 +59,10 @@
 # Internal
 /internal/                  team:platform
 
+# AI tools
+/cmd/aitools/               team:eng-apps-devex team:platform @lennartkats-db
+/libs/aitools/              team:eng-apps-devex team:platform @lennartkats-db
+
 # CLI compatibility manifest
 /internal/build/cli-compat.json  team:eng-apps-devex team:platform
 /libs/clicompat/                 team:eng-apps-devex team:platform

NEXT_CHANGELOG.md

@@ -6,6 +6,8 @@
 
 ### CLI
 
+* Added `databricks aitools` command group for installing Databricks skills into your coding agents (Claude Code, Cursor, Codex CLI, OpenCode, GitHub Copilot, Antigravity). Skills are fetched from [github.com/databricks/databricks-agent-skills](https://github.com/databricks/databricks-agent-skills) and either symlinked into each agent's skills directory or copied into the current project. Use `databricks aitools install` to set up, `update` to pull newer versions, `list` to see what's available, and `uninstall` to remove them.
+
 ### Bundles
 * Make sure warnings asking for approval are understood by agents ([#5239](https://github.com/databricks/cli/pull/5239))
 

Taskfile.yml

@@ -609,8 +609,10 @@ tasks:
   # generic `test` target (the catch-all) instead.
 
   test-exp-aitools:
-    desc: Run experimental aitools unit and acceptance tests
+    desc: Run aitools (top-level + experimental) unit and acceptance tests
     sources:
+      - cmd/aitools/**
+      - libs/aitools/**
       - experimental/aitools/**
       - acceptance/apps/**
       - "{{.EMBED_SOURCES}}"
@@ -619,7 +621,7 @@ tasks:
         {{.GO_TOOL}} gotestsum \
           --format ${GOTESTSUM_FORMAT:-pkgname-and-test-fails} \
           --no-summary=skipped \
-          --packages ./experimental/aitools/... \
+          --packages "./cmd/aitools/... ./libs/aitools/... ./experimental/aitools/..." \
           -- -timeout=${LOCAL_TIMEOUT:-30m}
       - |
         {{.GO_TOOL}} gotestsum \

acceptance/help/output.txt

@@ -168,6 +168,7 @@ Developer Tools
 
 Additional Commands:
   account                                Databricks Account Commands
+  aitools                                Databricks AI Tools for coding agents
   api                                    Perform Databricks API call
   auth                                   Authentication related commands
   cache                                  Local cache related commands

cmd/aitools/aitools.go

@@ -0,0 +1,25 @@
+package aitools
+
+import (
+	"github.com/spf13/cobra"
+)
+
+func NewAitoolsCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "aitools",
+		Short: "Databricks AI Tools for coding agents",
+		Long: `Install Databricks skills into your coding agent so it can work
+effectively with Databricks resources (bundles, jobs, SQL, and more).
+
+Supported agents: Claude Code, Cursor, Codex CLI, OpenCode, GitHub
+Copilot, Antigravity.`,
+	}
+
+	cmd.AddCommand(NewInstallCmd())
+	cmd.AddCommand(NewUpdateCmd())
+	cmd.AddCommand(NewUninstallCmd())
+	cmd.AddCommand(NewListCmd())
+	cmd.AddCommand(NewVersionCmd())
+
+	return cmd
+}

experimental/aitools/cmd/flags.go cmd/aitools/flags.goexperimental/aitools/cmd/flags.go renamed to cmd/aitools/flags.go

@@ -6,13 +6,51 @@ import (
 	"fmt"
 	"strings"
 
-	"github.com/databricks/cli/experimental/aitools/lib/agents"
-	"github.com/databricks/cli/experimental/aitools/lib/installer"
+	"github.com/charmbracelet/huh"
+	"github.com/databricks/cli/libs/aitools/agents"
+	"github.com/databricks/cli/libs/aitools/installer"
 	"github.com/databricks/cli/libs/cmdio"
 	"github.com/spf13/cobra"
 )
 
-func newInstallCmd() *cobra.Command {
+// Package-level for testability. Tests in this package override them via
+// helpers in install_test.go.
+var (
+	promptAgentSelection     = defaultPromptAgentSelection
+	installSkillsForAgentsFn = installer.InstallSkillsForAgents
+)
+
+func defaultPromptAgentSelection(ctx context.Context, detected []*agents.Agent) ([]*agents.Agent, error) {
+	options := make([]huh.Option[string], 0, len(detected))
+	agentsByName := make(map[string]*agents.Agent, len(detected))
+	for _, a := range detected {
+		options = append(options, huh.NewOption(a.DisplayName, a.Name).Selected(true))
+		agentsByName[a.Name] = a
+	}
+
+	var selected []string
+	err := huh.NewMultiSelect[string]().
+		Title("Select coding agents to install skills for").
+		Description("space to toggle, enter to confirm").
+		Options(options...).
+		Value(&selected).
+		Run()
+	if err != nil {
+		return nil, err
+	}
+
+	if len(selected) == 0 {
+		return nil, errors.New("at least one agent must be selected")
+	}
+
+	result := make([]*agents.Agent, 0, len(selected))
+	for _, name := range selected {
+		result = append(result, agentsByName[name])
+	}
+	return result, nil
+}
+
+func NewInstallCmd() *cobra.Command {
 	var skillsFlag, agentsFlag string
 	var includeExperimental bool
 	var projectFlag, globalFlag bool
@@ -27,6 +65,8 @@ Use --project to install to the current project directory instead.
 When multiple agents are detected, skills are stored in a canonical location
 and symlinked to each agent to avoid duplication.
 
+Use --skills name1,name2 to install specific skills.
+
 Supported agents: Claude Code, Cursor, Codex CLI, OpenCode, GitHub Copilot, Antigravity`,
 		Args: cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {