fix: skip skills fallback when DATABRICKS_SKILLS_REF is explicitly set

GetSkillsRef now returns whether the ref was explicitly set via env var.
FetchSkillsManifestWithFallback accepts allowFallback to skip the
embedded fallback when the user explicitly chose a ref.

Co-authored-by: Isaac

Author: pkosiec

experimental/aitools/cmd/list.go

@@ -48,13 +48,13 @@ func newListCmd() *cobra.Command {
 func defaultListSkills(cmd *cobra.Command, scope string) error {
 	ctx := cmd.Context()
 
-	ref, err := installer.GetSkillsRef(ctx)
+	ref, explicit, err := installer.GetSkillsRef(ctx)
 	if err != nil {
 		return err
 	}
 
 	src := &installer.GitHubManifestSource{}
-	manifest, ref, err := installer.FetchSkillsManifestWithFallback(ctx, src, ref)
+	manifest, ref, err := installer.FetchSkillsManifestWithFallback(ctx, src, ref, !explicit)
 	if err != nil {
 		return fmt.Errorf("failed to fetch manifest: %w", err)
 	}

experimental/aitools/cmd/version.go

@@ -45,7 +45,7 @@ func newVersionCmd() *cobra.Command {
 				return nil
 			}
 
-			latestRef, err := installer.GetSkillsRef(ctx)
+			latestRef, _, err := installer.GetSkillsRef(ctx)
 			if err != nil {
 				log.Debugf(ctx, "could not resolve skills version: %v", err)
 			}

experimental/aitools/lib/installer/installer.go

@@ -33,17 +33,18 @@ const (
 // It is a package-level var so tests can replace it with a mock.
 var fetchFileFn = fetchSkillFile
 
-// GetSkillsRef returns the skills repo ref to use.
+// GetSkillsRef returns the skills repo ref to use and whether it was explicitly
+// set via DATABRICKS_SKILLS_REF (as opposed to auto-resolved from the manifest).
 // Resolution order: DATABRICKS_SKILLS_REF env var → compatibility manifest → error.
-func GetSkillsRef(ctx context.Context) (string, error) {
+func GetSkillsRef(ctx context.Context) (ref string, explicit bool, err error) {
 	if ref := env.Get(ctx, "DATABRICKS_SKILLS_REF"); ref != "" {
-		return ref, nil
+		return ref, true, nil
 	}
 	v, err := clicompat.ResolveAgentSkillsVersion(ctx)
 	if err != nil {
-		return "", fmt.Errorf("could not resolve skills version: %w", err)
+		return "", false, fmt.Errorf("could not resolve skills version: %w", err)
 	}
-	return "v" + v, nil
+	return "v" + v, false, nil
 }
 
 // Manifest describes the skills manifest fetched from the skills repo.
@@ -97,10 +98,10 @@ func fetchSkillFile(ctx context.Context, ref, skillName, filePath string) ([]byt
 // If the ref points to a non-existent tag (not-found error), it falls back to
 // the embedded manifest's skills version. Returns the manifest, the (possibly
 // updated) ref, and any error.
-func FetchSkillsManifestWithFallback(ctx context.Context, src ManifestSource, ref string) (*Manifest, string, error) {
+func FetchSkillsManifestWithFallback(ctx context.Context, src ManifestSource, ref string, allowFallback bool) (*Manifest, string, error) {
 	tag := strings.TrimPrefix(ref, "v")
 	manifest, err := src.FetchManifest(ctx, ref)
-	if err != nil && clicompat.IsNotFoundError(err) {
+	if err != nil && allowFallback && clicompat.IsNotFoundError(err) {
 		fallbackVersion, fbErr := clicompat.ResolveEmbeddedAgentSkillsVersion()
 		if fbErr == nil && fallbackVersion != "" && fallbackVersion != tag {
 			log.Warnf(ctx, "Skills version %s not found, falling back to embedded version %s", tag, fallbackVersion)
@@ -117,12 +118,12 @@ func FetchSkillsManifestWithFallback(ctx context.Context, src ManifestSource, re
 // This is the core installation function. Callers are responsible for agent detection,
 // prompting, and printing the "Installing..." header.
 func InstallSkillsForAgents(ctx context.Context, src ManifestSource, targetAgents []*agents.Agent, opts InstallOptions) error {
-	ref, err := GetSkillsRef(ctx)
+	ref, explicit, err := GetSkillsRef(ctx)
 	if err != nil {
 		return err
 	}
 	cmdio.LogString(ctx, "Using skills version "+strings.TrimPrefix(ref, "v"))
-	manifest, ref, err := FetchSkillsManifestWithFallback(ctx, src, ref)
+	manifest, ref, err := FetchSkillsManifestWithFallback(ctx, src, ref, !explicit)
 	if err != nil {
 		return err
 	}

experimental/aitools/lib/installer/installer_test.go

@@ -753,8 +753,9 @@ func TestGetSkillsRefResolvesFromManifest(t *testing.T) {
 	manifest := `{"next":{"appkit":"0.24.0","skills":"0.1.5"},"0.300.0":{"appkit":"0.24.0","skills":"0.1.5"}}`
 	require.NoError(t, os.WriteFile(cachePath, []byte(manifest), 0o644))
 
-	ref, err := GetSkillsRef(t.Context())
+	ref, explicit, err := GetSkillsRef(t.Context())
 	require.NoError(t, err, "GetSkillsRef should succeed via cached manifest")
+	assert.False(t, explicit, "ref resolved from manifest should not be explicit")
 	assert.NotEmpty(t, ref)
 	assert.True(t, len(ref) > 1 && ref[0] == 'v', "ref should start with 'v', got %q", ref)
 }

experimental/aitools/lib/installer/update.go

@@ -81,7 +81,7 @@ func UpdateSkills(ctx context.Context, src ManifestSource, targetAgents []*agent
 		return nil, errors.New("no skills installed. Run 'databricks experimental aitools install' to install")
 	}
 
-	latestTag, err := GetSkillsRef(ctx)
+	latestTag, explicit, err := GetSkillsRef(ctx)
 	if err != nil {
 		return nil, err
 	}
@@ -91,7 +91,7 @@ func UpdateSkills(ctx context.Context, src ManifestSource, targetAgents []*agent
 		return &UpdateResult{Unchanged: slices.Sorted(maps.Keys(state.Skills))}, nil
 	}
 
-	manifest, latestTag, err := FetchSkillsManifestWithFallback(ctx, src, latestTag)
+	manifest, latestTag, err := FetchSkillsManifestWithFallback(ctx, src, latestTag, !explicit)
 	if err != nil {
 		if opts.Check {
 			log.Warnf(ctx, "Could not fetch manifest: %v", err)