aitools: handle experimental<->stable skill transitions

When a skill flips its experimental status upstream, the manifest key
changes (gains or loses the -experimental suffix). Without explicit
handling, install would leave the stale variant on disk and in state,
and uninstall would fail to find a skill that the user typed under
its other variant name.

- Install: before installing a skill, check if the alternate variant
  is in state and remove it (delete install dir, agent symlinks, and
  state entry). Logs "Replaced previous variant X with Y".
- Uninstall: accept either variant when the user uninstalls by name;
  if both are installed, remove both (the "old version" of the same
  logical skill is stale by definition).

New `alternateVariantKey()` helper centralizes the suffix toggle.
Tests cover: install replacing stale variant, uninstall by either
variant when one is installed, uninstall removing both when both are
installed.

Co-authored-by: Isaac

Author: jamesbroadhead

experimental/aitools/lib/installer/installer.go

@@ -27,8 +27,22 @@ const (
 	skillsRepoName       = "databricks-agent-skills"
 	stableSkillsRepoPath = "skills"
 	experimentalRepoPath = "experimental"
+	experimentalSuffix   = "-experimental"
 )
 
+// alternateVariantKey returns the manifest key of the same logical skill
+// under the opposite experimental status. For "databricks-jobs" it returns
+// "databricks-jobs-experimental"; for "databricks-jobs-experimental" it
+// returns "databricks-jobs". Used to clean up the previously-installed
+// variant when a skill transitions between experimental and stable
+// upstream.
+func alternateVariantKey(key string) string {
+	if strings.HasSuffix(key, experimentalSuffix) {
+		return strings.TrimSuffix(key, experimentalSuffix)
+	}
+	return key + experimentalSuffix
+}
+
 // fetchFileFn is the function used to download individual skill files.
 // It is a package-level var so tests can replace it with a mock.
 var fetchFileFn func(ctx context.Context, ref, repoDir, skillName, filePath string) ([]byte, error) = fetchSkillFile
@@ -179,6 +193,23 @@ func InstallSkillsForAgents(ctx context.Context, src ManifestSource, targetAgent
 
 	for _, name := range skillNames {
 		meta := targetSkills[name]
+
+		// Experimental↔stable transition: if the alternate variant of this
+		// skill was previously installed (upstream flipped its experimental
+		// status), remove the stale variant before installing the new one.
+		if state != nil {
+			alt := alternateVariantKey(name)
+			if _, ok := state.Skills[alt]; ok {
+				altDir := filepath.Join(baseDir, alt)
+				removeSymlinksFromAgents(ctx, alt, altDir, scope, cwd)
+				if err := os.RemoveAll(altDir); err != nil {
+					log.Warnf(ctx, "Failed to remove previous variant %s: %v", altDir, err)
+				}
+				delete(state.Skills, alt)
+				cmdio.LogString(ctx, fmt.Sprintf("Replaced previous variant %s with %s", alt, name))
+			}
+		}
+
 		// Idempotency: skip if same version is already installed, the canonical
 		// dir exists, AND every requested agent already has the skill on disk.
 		if state != nil && state.Skills[name] == meta.Version {

experimental/aitools/lib/installer/installer_test.go

@@ -710,6 +710,51 @@ func TestInstallProjectScopeZeroCompatibleAgentsReturnsError(t *testing.T) {
 	assert.Contains(t, err.Error(), "No Project Agent")
 }
 
+func TestInstallReplacesAlternateVariant(t *testing.T) {
+	// Setup: a skill called "databricks-jobs" is installed as stable.
+	// Then the manifest re-categorizes it as experimental (key becomes
+	// "databricks-jobs-experimental"). A new install with --experimental
+	// should remove the stale stable variant and install the experimental one.
+	tmp := setupTestHome(t)
+	ctx, stderr := cmdio.NewTestContextWithStderr(t.Context())
+	setupFetchMock(t)
+	agent := testAgent(tmp)
+
+	stableManifest := &Manifest{
+		Version: "1",
+		Skills: map[string]SkillMeta{
+			"databricks-jobs": {Version: "0.1.0", Files: []string{"SKILL.md"}},
+		},
+	}
+	require.NoError(t, InstallSkillsForAgents(
+		ctx, &mockManifestSource{manifest: stableManifest},
+		[]*agents.Agent{agent}, InstallOptions{},
+	))
+
+	globalDir := filepath.Join(tmp, ".databricks", "aitools", "skills")
+	require.DirExists(t, filepath.Join(globalDir, "databricks-jobs"))
+
+	// Now flip to experimental upstream. New install run.
+	experimentalManifest := &Manifest{
+		Version: "1",
+		ExperimentalSkills: map[string]SkillMeta{
+			"databricks-jobs": {Version: "0.2.0", Files: []string{"SKILL.md"}},
+		},
+	}
+	require.NoError(t, InstallSkillsForAgents(
+		ctx, &mockManifestSource{manifest: experimentalManifest},
+		[]*agents.Agent{agent}, InstallOptions{IncludeExperimental: true},
+	))
+
+	state, err := LoadState(globalDir)
+	require.NoError(t, err)
+	assert.NotContains(t, state.Skills, "databricks-jobs", "stale stable variant should be removed from state")
+	assert.Equal(t, "0.2.0", state.Skills["databricks-jobs-experimental"])
+	assert.NoDirExists(t, filepath.Join(globalDir, "databricks-jobs"), "stale stable install dir should be gone")
+	assert.DirExists(t, filepath.Join(globalDir, "databricks-jobs-experimental"))
+	assert.Contains(t, stderr.String(), "Replaced previous variant databricks-jobs with databricks-jobs-experimental")
+}
+
 func TestSupportsProjectScopeSetCorrectly(t *testing.T) {
 	expected := map[string]bool{
 		"claude-code": true,

experimental/aitools/lib/installer/source_test.go

@@ -60,6 +60,14 @@ func TestFlattenManifestCollidingNamesCoexist(t *testing.T) {
 	assert.Equal(t, "databricks-jobs", exp.SourceName, "SourceName is the un-suffixed name for the fetch URL")
 }
 
+func TestAlternateVariantKey(t *testing.T) {
+	assert.Equal(t, "databricks-jobs-experimental", alternateVariantKey("databricks-jobs"))
+	assert.Equal(t, "databricks-jobs", alternateVariantKey("databricks-jobs-experimental"))
+	// Idempotent under double application
+	assert.Equal(t, "databricks-jobs",
+		alternateVariantKey(alternateVariantKey("databricks-jobs")))
+}
+
 func TestFlattenManifestEmptyStableSkills(t *testing.T) {
 	m := &Manifest{
 		ExperimentalSkills: map[string]SkillMeta{

experimental/aitools/lib/installer/uninstall.go

@@ -63,15 +63,30 @@ func UninstallSkillsOpts(ctx context.Context, opts UninstallOptions) error {
 	var toRemove []string
 	if len(opts.Skills) > 0 {
 		seen := make(map[string]bool)
-		for _, name := range opts.Skills {
+		for _, raw := range opts.Skills {
+			// Accept either variant: if the literal name isn't installed but
+			// the alternate variant is, use the alternate. This makes uninstall
+			// resilient to the experimental↔stable transition.
+			name := raw
+			if _, ok := state.Skills[name]; !ok {
+				if alt := alternateVariantKey(name); state.Skills[alt] != "" {
+					name = alt
+				} else {
+					return fmt.Errorf("skill %q is not installed", raw)
+				}
+			}
 			if seen[name] {
 				continue
 			}
 			seen[name] = true
-			if _, ok := state.Skills[name]; !ok {
-				return fmt.Errorf("skill %q is not installed", name)
-			}
 			toRemove = append(toRemove, name)
+
+			// If both variants are installed, remove both (the alternate is
+			// the stale "old version" of the same logical skill).
+			if alt := alternateVariantKey(name); state.Skills[alt] != "" && !seen[alt] {
+				seen[alt] = true
+				toRemove = append(toRemove, alt)
+			}
 		}
 	} else {
 		for name := range state.Skills {

experimental/aitools/lib/installer/uninstall_test.go

@@ -320,6 +320,71 @@ func TestUninstallSelectiveDuplicateNamesDeduplicates(t *testing.T) {
 	assert.Contains(t, stderr.String(), "Uninstalled 1 skill.")
 }
 
+func TestUninstallByEitherVariantRemovesBoth(t *testing.T) {
+	// Setup: both stable and experimental variants of databricks-jobs are
+	// installed (the transitional state we want uninstall to clean up).
+	tmp := setupTestHome(t)
+	ctx, stderr := cmdio.NewTestContextWithStderr(t.Context())
+	setupFetchMock(t)
+	agent := testAgent(tmp)
+
+	manifest := &Manifest{
+		Version: "1",
+		Skills: map[string]SkillMeta{
+			"databricks-jobs": {Version: "0.1.0", Files: []string{"SKILL.md"}},
+		},
+		ExperimentalSkills: map[string]SkillMeta{
+			"databricks-jobs": {Version: "0.0.1", Files: []string{"SKILL.md"}},
+		},
+	}
+	require.NoError(t, InstallSkillsForAgents(
+		ctx, &mockManifestSource{manifest: manifest},
+		[]*agents.Agent{agent}, InstallOptions{IncludeExperimental: true},
+	))
+
+	globalDir := filepath.Join(tmp, ".databricks", "aitools", "skills")
+	require.DirExists(t, filepath.Join(globalDir, "databricks-jobs"))
+	require.DirExists(t, filepath.Join(globalDir, "databricks-jobs-experimental"))
+
+	// Uninstall using just the un-suffixed name; both variants should go.
+	require.NoError(t, UninstallSkillsOpts(ctx, UninstallOptions{
+		Skills: []string{"databricks-jobs"},
+	}))
+
+	assert.NoDirExists(t, filepath.Join(globalDir, "databricks-jobs"))
+	assert.NoDirExists(t, filepath.Join(globalDir, "databricks-jobs-experimental"))
+	assert.Contains(t, stderr.String(), "Uninstalled 2 skills.")
+}
+
+func TestUninstallByAlternateNameWhenOnlyOneVariantInstalled(t *testing.T) {
+	// Setup: only the experimental variant is installed.
+	tmp := setupTestHome(t)
+	ctx := cmdio.MockDiscard(t.Context())
+	setupFetchMock(t)
+	agent := testAgent(tmp)
+
+	manifest := &Manifest{
+		Version: "1",
+		ExperimentalSkills: map[string]SkillMeta{
+			"databricks-jobs": {Version: "0.0.1", Files: []string{"SKILL.md"}},
+		},
+	}
+	require.NoError(t, InstallSkillsForAgents(
+		ctx, &mockManifestSource{manifest: manifest},
+		[]*agents.Agent{agent}, InstallOptions{IncludeExperimental: true},
+	))
+
+	globalDir := filepath.Join(tmp, ".databricks", "aitools", "skills")
+	require.DirExists(t, filepath.Join(globalDir, "databricks-jobs-experimental"))
+
+	// User types the un-suffixed name (doesn't know which variant is on
+	// disk); uninstall should still find and remove it.
+	require.NoError(t, UninstallSkillsOpts(ctx, UninstallOptions{
+		Skills: []string{"databricks-jobs"},
+	}))
+	assert.NoDirExists(t, filepath.Join(globalDir, "databricks-jobs-experimental"))
+}
+
 func TestUninstallSelectiveAllRemovesStateFile(t *testing.T) {
 	tmp := setupTestHome(t)
 	globalDir := installTestSkills(t, tmp)