aitools: parse experimental_skills manifest section

[jamesbroadhead]

Summary

The skills manifest in databricks/databricks-agent-skills is gaining a new top-level experimental_skills map alongside the existing skills map (see paired d-a-s PR #73, which imports the ai-dev-kit skill catalog into experimental/).

This wires the parsing through the aitools installer:

• Manifest.ExperimentalSkills is flattened into Manifest.Skills during FetchManifest, with Experimental=true and RepoDir set so the rest of the installer treats them uniformly.
• fetchSkillFile now takes the repo subdirectory (skills/ vs experimental/) per skill, so experimental skills are downloaded from their actual location upstream.
• The existing --experimental flag (already wired in cmd/skills.go) now has experimental skills to install; without it, resolveSkills filters them out as before.
• Name collisions between stable and experimental are resolved by renaming the experimental copy with a -experimental suffix (stable wins).

UX

# default — only stable skills
databricks experimental aitools skills install

# all experimental skills, plus stable
databricks experimental aitools skills install --experimental

# one experimental skill by name (--experimental still required by resolveSkills)
databricks experimental aitools skills install databricks-iceberg --experimental

TODOs / caveats for iteration

1. DATABRICKS_SKILLS_REF pin. Partially resolved. The default ref is still the latest stable release tag (sourced from experimental/aitools/lib/installer/SKILLS_VERSION); the experimental manifest section won't exist there until d-a-s cuts a release with PR #73 merged. The default ref bump is a follow-up automated by the SKILLS_VERSION file. UX fix shipped in this PR: if --experimental is passed but the manifest at the resolved ref has no experimental skills, a warning is logged pointing users at DATABRICKS_SKILLS_REF=main.

2. Collision handling is naive. Resolved. Every experimental skill now gets a -experimental suffix unconditionally (not just on collision). The manifest key + install dir both carry the suffix; new SourceName field on SkillMeta preserves the upstream repo dir name for fetch URLs. Users see at a glance which installed skills are experimental.

   Also handled in the same commit: experimental↔stable transitions. If a skill flips its experimental status upstream (the same logical skill changes manifest key), install removes the stale variant on disk + state before installing the new one, and uninstall accepts either variant name (and removes both if both are present). Helper: alternateVariantKey(). Covered by new tests TestInstallReplacesAlternateVariant, TestUninstallByEitherVariantRemovesBoth, TestUninstallByAlternateNameWhenOnlyOneVariantInstalled.

3. list UX. Resolved. aitools skills list already shows experimental skills with an [experimental] tag in the NAME column. Combined with the TODO Bump gopkg.in/ini.v1 from 1.66.4 to 1.66.5 #2 resolution (-experimental suffix in the manifest key), every experimental row reads e.g. databricks-iceberg-experimental [experimental] — slightly redundant but a clear visual anchor. Hide-by-default was considered but rejected: users running list are usually looking for what's available, and silently omitting experimental skills makes them un-discoverable.

4. State tracking. Resolved — kept additive semantics. InstallState.IncludeExperimental records what was last requested but is not used to drive retroactive removal. Running install without --experimental leaves previously-installed experimental skills in place. Rationale: (a) users running install are typically adding/updating, not declaring set membership; (b) silently uninstalling things the user previously asked for is surprising; (c) the transition cleanup shipped under TODO Bump gopkg.in/ini.v1 from 1.66.4 to 1.66.5 #2 handles the actual drift case (skill's experimental status flipping upstream). Removal is what uninstall is for.

5. No acceptance test yet. Resolved. Added an acceptance test at acceptance/experimental/aitools/skills/install/ covering the install flow against a mocked manifest server:

   • Stable-only install (no flag) → 1 skill installed
   • --experimental install adds the experimental skill (with -experimental suffix per the install-path model) → 2 skills total
   • Re-running --experimental is idempotent

   To make the test reachable, exposed a new env-var override DATABRICKS_SKILLS_BASE_URL that overrides the hard-coded raw.githubusercontent.com base URL used by GitHubManifestSource.FetchManifest and fetchSkillFile. Defaults to the canonical URL when unset, so no production behavior change. Updated Taskfile.yml's test-exp-aitools task to include acceptance/experimental/aitools/**.

   Variants left as follow-up acceptance tests (the structure is now in place):

   • Variant transition cleanup (stable → experimental, experimental → stable)
   • Uninstall flow (with both variants installed)
   • Specific-skill install (install <name> --experimental)
   • Error cases (skill not found, --experimental with empty manifest)

6. --experimental flag scope. Resolved — kept current scope. Each command has internally consistent behavior:

   • install --experimental → explicit opt-in (required to install experimental skills).
   • update → state-driven (honors InstallState.IncludeExperimental from the last install). If you opted in once, future updates refresh experimentals; otherwise they're skipped (see update.go line 125).
   • list → shows all skills with an [experimental] tag (no filtering — discovery first, opt-in to install).

   Adding --experimental / --no-experimental to update for one-off overrides was considered but rejected: the natural workflow is to re-run install --experimental (or just install), which already sets the desired state. Follow-up if real users hit a use case for the override.

Test plan

• `go build ./...` passes.
• `go test ./experimental/aitools/...` passes (added `source_test.go` covering flatten/collision/empty cases).
• Run `./task lint` and `./task fmt` before merge.
• Manual: against a d-a-s ref containing experimental_skills, verify the four UX cases above behave correctly.

This pull request and its description were written by Claude.

[github-actions]

Approval status: pending

/experimental/aitools/ - needs approval

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

General files (require maintainer)

13 files changed
Based on git history:

• @simonfaltum -- recent work in experimental/aitools/lib/installer/

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