Promote aitools skills-management commands to top-level

[jamesbroadhead]

Summary

Move-only PR. Promotes the aitools skills-management surface out of experimental/ to a new top-level aitools/ package, preserving today's behavior. The matching interface changes (--scope enum, --project/--global deprecation, --agents auto-detect doc) live in a stacked follow-up: #5234.

• Source files for install, update, uninstall, list, version (and the agents/installer libs they depend on) physically move from experimental/aitools/ to top-level aitools/, so the directory layout matches the stability tier.
• 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 hidden skills alias group also stays under experimental/aitools/.
• The old paths under databricks experimental aitools install/update/uninstall/list/version and databricks experimental aitools skills install/list keep working as silent backward-compat aliases — no deprecation warning fires, the commands just forward.

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.

What's not in this PR

These are deliberately separated and reviewed independently:

• aitools: add --scope flag, deprecate --project/--global #5234 — --scope=project|global|both flag, deprecation of --project/--global via cobra.Deprecated, --agents auto-detect help text.
• aitools list: emit JSON via --output json #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

# Silent backward-compat aliases (no warning)
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

• databricks aitools --help shows install/update/uninstall/list/version (no tools)
• databricks --help lists aitools in the output
• databricks experimental aitools install runs without warning and the work happens (silent alias)
• databricks experimental aitools tools query … runs as before
• databricks experimental aitools tools --help lists query/discover-schema/get-default-warehouse/statement
• Existing aitools tests pass plus alias-forwarding coverage in experimental/aitools/cmd/skills_test.go

This pull request was AI-assisted by Isaac.

[github-actions]

Approval status: pending

/cmd/apps/ - needs approval

Files: cmd/apps/init.go
Suggested: @arsenyinfo
Also eligible: @pkosiec, @MarioCadenas, @fjakobs, @keugenek, @calvarjorge, @Shridhad, @atilafassina, @igrekun, @pffigueiredo, @ditadi

/experimental/aitools/ - needs approval

4 files changed
Suggested: @arsenyinfo
Also eligible: @pkosiec, @MarioCadenas, @fjakobs, @keugenek, @lennartkats-db, @calvarjorge, @Shridhad, @atilafassina, @igrekun, @pffigueiredo, @ditadi

General files (require maintainer)

36 files changed
Based on git history:

• @simonfaltum -- recent work in ./, experimental/aitools/cmd/, .github/

_{Any maintainer (@andrewnester, @anton-107, @denik, @pietern, @shreyas-goenka, @simonfaltum, @renaudhartert-db) can approve all areas.
See OWNERS for ownership rules.}

[simonfaltum]

I think we should move the code itself (the files) out of experimental as part of this as well.

[jamesbroadhead]

Hi @pietern — Claude here, on James's behalf.

Just merged origin/main into this PR (one conflict in NEXT_CHANGELOG.md, resolved by keeping both entries). go build ./... and go vet clean.

Could you take a look when you have a chance? You've been the most active reviewer/committer in aitools/ recently and are a top-level maintainer, so picking you over the other auto-assigned reviewers.

---

This comment was generated with GitHub MCP.

[simonfaltum]

Hi @jamesbroadhead
Any chance we could hold off with changing the behavior to databricks aitools install
If we do "databricks aitools install " then we lock ourselves into a corner, and databricks aitools install --skill would do the same thing. The reason behind my caution is that we are still a bit unsure how aitools will evolve in the future, and what might be next thing coming for Agents after skills.

[lennartkats-db]

Only minor comments, PTAL. And I'd like for @simonfaltum to sign off on this as well since we'd promote aitools out of experimental here (even if he's co-author).

[lennartkats-db]

Good to have the backward compatibility, but maybe we can display a warning if they're used? (I think there's a Deprecated property that can be used for this)

[jamesbroadhead]

Hi @simonfaltum @lennartkats-db — Claude here, on James's behalf.

Update (after this comment was originally posted): Per Simon's request, the interface changes (--scope enum, --project/--global deprecation via cobra.Deprecated, --agents auto-detect doc) have been split out into a follow-up PR — #5234. This PR now contains only the move from experimental/aitools/ to top-level aitools/.

#5234 is stacked on this PR (will rebase to main once this lands), so its GitHub diff shows only the interface changes. Simon is the requested reviewer there.

The positional [skill-name] discussion was already addressed by the earlier force-push that dropped the positional form (current top commit on this branch).

The earlier question on whether the databricks experimental aitools … path should surface a Deprecated warning (currently silent) is still open on this PR — happy to add it here if you'd prefer.

PR: #4917

---

This comment was generated with GitHub MCP.