Skip to content

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

Merged
simonfaltum merged 20 commits into
mainfrom
jbroadhead/aitools-public
May 18, 2026
Merged

Promote aitools skills-management commands to top-level#4917
simonfaltum merged 20 commits into
mainfrom
jbroadhead/aitools-public

Conversation

@jamesbroadhead
Copy link
Copy Markdown
Contributor

@jamesbroadhead jamesbroadhead commented Apr 8, 2026

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 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:

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

  • databricks aitools --help shows install/update/uninstall/list/version (no tools)
  • databricks --help lists aitools in the output
  • databricks experimental aitools install prints a deprecation notice and still forwards
  • 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; the legacy-wrapper tests moved with the wrapper to cmd/aitools/legacy_skills_test.go

This pull request was AI-assisted by Isaac.

@simonfaltum
Copy link
Copy Markdown
Member

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

jamesbroadhead added a commit that referenced this pull request Apr 28, 2026
Per Simon's review on #4917, the source files should live outside
experimental/ now that aitools is a top-level command. Renames the
directory from experimental/aitools/ to aitools/ and updates all
import paths, examples, and tooling references (Makefile, OWNERS,
testmask, pr-checklist).

The experimental/aitools alias still routes to the same package via
its new import path, so 'databricks experimental aitools' continues
to work as a deprecated entry point.

Co-authored-by: Isaac
@simonfaltum simonfaltum force-pushed the jbroadhead/aitools-public branch from c1b87a6 to 8b230d7 Compare April 30, 2026 08:12
@simonfaltum simonfaltum changed the title Promote aitools from experimental to top-level command Promote aitools skills-management commands to top-level Apr 30, 2026
# Conflicts:
#	.github/OWNERS
#	NEXT_CHANGELOG.md
#	aitools/lib/installer/SKILLS_VERSION
#	aitools/lib/installer/version.go
Copy link
Copy Markdown
Member

@simonfaltum simonfaltum left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, will do a follow up to mark this as beta

* Restructure to match `cmd/apps` + `libs/apps`: move `aitools/cmd/`
  to `cmd/aitools/` and `aitools/lib/{agents,installer}/` to
  `libs/aitools/{agents,installer}/`. Removes the asymmetric top-level
  `aitools/` directory. Updates OWNERS, Taskfile, and the agent
  pr-checklist accordingly. Drops the redundant `aitools/README.md`
  (apps/pipelines don't have one).

* Print a deprecation notice on every legacy invocation under
  `databricks experimental aitools` (Lennart's review ask). The hidden
  aliases now set cobra's `Deprecated` field so users see
  `Command "install" is deprecated, use "databricks aitools install"
  instead.` instead of silent forwarding.

* Stop exporting `InstallSkillsForAgentsFn`, `ListSkillsFn`, and
  `PromptAgentSelection`. The legacy skills wrapper now lives in
  `cmd/aitools/legacy_skills.go` next to the install/list code it
  wraps, so its tests are in the same package and can use the
  unexported vars directly. Deletes
  `experimental/aitools/cmd/skills.go` and its `_test.go`.

* Improve the top-level `databricks aitools` Long description.

Co-authored-by: Isaac
The entry now introduces the new `databricks aitools` command group on
its own terms, explains what it does (install Databricks skills from
github.com/databricks/databricks-agent-skills into your coding agent),
and lists the four user-facing verbs. Drops the experimental-history
and backward-compat-alias detail — that lives in the PR description for
reviewers, not in user-facing release notes.

Co-authored-by: Isaac
…e right tempdir

Moving aitools to top-level cmd/ and libs/ means TEST_PACKAGES on Windows
now runs these tests via ./cmd/... and ./libs/... globs; previously they
lived under experimental/aitools/, which Windows skipped. The tests set
HOME, but env.HomeEnvVar() returns "USERPROFILE" on Windows.

Set both env vars at every call site, following the libs/git pattern.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants