diff --git a/.nextchanges/cli/air-skill-hint.md b/.nextchanges/cli/air-skill-hint.md
new file mode 100644
index 00000000000..9636ef450a6
--- /dev/null
+++ b/.nextchanges/cli/air-skill-hint.md
@@ -0,0 +1 @@
+* On `databricks air` subcommands, Claude Code now gets an install hint that names the `databricks-ai-runtime` skill, what it covers, and how to preview it with `databricks aitools install --path`, instead of the generic install hint; other commands and other agents' hints are unchanged, and `databricks air --help` lists the skill and the preview too. ([#7622](https://github.com/databricks/cli/pull/7622))
diff --git a/acceptance/air/help/output.txt b/acceptance/air/help/output.txt
index 6f75b4afcc6..b28ae42bd82 100644
--- a/acceptance/air/help/output.txt
+++ b/acceptance/air/help/output.txt
@@ -43,6 +43,10 @@ Learn more:
Quickstart (AWS) https://docs.databricks.com/aws/en/machine-learning/ai-runtime/quickstart
Quickstart (Azure) https://learn.microsoft.com/azure/databricks/machine-learning/ai-runtime/quickstart
Coding agent skill databricks aitools install --skills-only --skills databricks-ai-runtime
+ Teaches coding agents the workload YAML, GPU types, secrets,
+ and how to follow and debug runs.
+ Preview the skill databricks aitools install --path
--skills databricks-ai-runtime
+ Writes the skill files to without installing anything.
=== list help
diff --git a/acceptance/air/image-push/output.txt b/acceptance/air/image-push/output.txt
index 07d4a23b770..0868e4fd0d9 100644
--- a/acceptance/air/image-push/output.txt
+++ b/acceptance/air/image-push/output.txt
@@ -218,7 +218,7 @@ pull --platform linux/amd64 example/image:v1
>>> databricks air images push -p docker-test -s example/image:v1 --catalog main --schema training
-Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install
+Tip: install the databricks-ai-runtime skill for workload configuration and run debugging: databricks aitools install --skills-only --skills databricks-ai-runtime. To preview it first, replace --skills-only with --path .
Warning: This feature is in Preview. APIs may change, and the workspace must enable the Preview features.
Pushing example/image:v1 as main.training.image:v1 using profile docker-test
Configured Docker credential helper for [WORKSPACE_ID].container.us-west-2.localhost
@@ -233,7 +233,7 @@ Now you can set `environment.unity_catalog_image = main.training.image:v1` in yo
>>> musterr databricks air images push -p pat-test -s example/image:v1 --catalog main --schema training
-Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install
+Tip: install the databricks-ai-runtime skill for workload configuration and run debugging: databricks aitools install --skills-only --skills databricks-ai-runtime. To preview it first, replace --skills-only with --path .
Warning: This feature is in Preview. APIs may change, and the workspace must enable the Preview features.
Pushing example/image:v1 as main.training.image:v1 using profile pat-test
Error: configure Docker authentication: run auth docker configure: exit status 1: Error: profile "pat-test" uses auth_type "pat". Docker credential helper requires a profile created by databricks auth login
diff --git a/cmd/air/air.go b/cmd/air/air.go
index 07f4c9281a5..b774160b544 100644
--- a/cmd/air/air.go
+++ b/cmd/air/air.go
@@ -23,6 +23,10 @@ Learn more:
Quickstart (AWS) https://docs.databricks.com/aws/en/machine-learning/ai-runtime/quickstart
Quickstart (Azure) https://learn.microsoft.com/azure/databricks/machine-learning/ai-runtime/quickstart
Coding agent skill databricks aitools install --skills-only --skills databricks-ai-runtime
+ Teaches coding agents the workload YAML, GPU types, secrets,
+ and how to follow and debug runs.
+ Preview the skill databricks aitools install --path --skills databricks-ai-runtime
+ Writes the skill files to without installing anything.
`
// Spec declares the air command.
diff --git a/cmd/air/air_test.go b/cmd/air/air_test.go
index 15877be56fe..f74305c26cc 100644
--- a/cmd/air/air_test.go
+++ b/cmd/air/air_test.go
@@ -55,6 +55,11 @@ func TestHelpFooterOnlyOnAirCommand(t *testing.T) {
cmd.HelpFunc()(cmd, nil)
assert.Contains(t, airOut.String(), "Learn more:")
assert.Contains(t, airOut.String(), "databricks air run -h config")
+ // The footer is where `air` and `air --help` recommend the agent skill
+ // (help never reaches the pre-run hook that prints the install hint).
+ assert.Contains(t, airOut.String(), "databricks aitools install --skills-only --skills databricks-ai-runtime")
+ assert.Contains(t, airOut.String(), "Teaches coding agents the workload YAML")
+ assert.Contains(t, airOut.String(), "databricks aitools install --path --skills databricks-ai-runtime")
list := findSubcommand(t, cmd, "list")
var listOut bytes.Buffer
diff --git a/cmd/air/hint_test.go b/cmd/air/hint_test.go
new file mode 100644
index 00000000000..65390a4bd8b
--- /dev/null
+++ b/cmd/air/hint_test.go
@@ -0,0 +1,90 @@
+package aircmd
+
+import (
+ "bytes"
+ "context"
+ "testing"
+
+ "github.com/databricks/cli/cmd/root"
+ "github.com/databricks/cli/internal/testutil"
+ "github.com/databricks/cli/libs/aitools/agents"
+ "github.com/databricks/cli/libs/cmdio"
+ "github.com/databricks/cli/libs/env"
+ "github.com/spf13/cobra"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+// airUnderRoot mounts the real air tree under a root whose pre-run hook only
+// records that it ran, mirroring where cmd/root calls agents.MaybeHint.
+func airUnderRoot(ctx context.Context, preRunCalled *bool) (*cobra.Command, *cobra.Command) {
+ dummy := &cobra.Command{Use: "databricks"}
+ dummy.AddGroup(&cobra.Group{ID: "development", Title: "Developer Tools"})
+ dummy.PersistentPreRunE = func(cmd *cobra.Command, args []string) error {
+ *preRunCalled = true
+ return nil
+ }
+ air := root.NewCommand(ctx, Spec)
+ dummy.AddCommand(air)
+ return dummy, air
+}
+
+// TestBareAirAndHelpShowFooterWithoutPreRun pins why the footer, not the
+// dynamic hint, is the recommendation surface for `air` and `air --help`.
+func TestBareAirAndHelpShowFooterWithoutPreRun(t *testing.T) {
+ for _, args := range [][]string{{"air"}, {"air", "--help"}} {
+ t.Run(args[len(args)-1], func(t *testing.T) {
+ preRunCalled := false
+ root, _ := airUnderRoot(t.Context(), &preRunCalled)
+ var out bytes.Buffer
+ root.SetOut(&out)
+ root.SetErr(&out)
+ root.SetArgs(args)
+ require.NoError(t, root.Execute())
+ assert.False(t, preRunCalled, "help must not run the pre-run hook")
+ assert.Contains(t, out.String(), "Coding agent skill databricks aitools install --skills-only --skills databricks-ai-runtime")
+ assert.Contains(t, out.String(), "Preview the skill databricks aitools install --path --skills databricks-ai-runtime")
+ })
+ }
+}
+
+// TestRunnableAirCommandsGetSkillHint walks the real air tree, so a new
+// subcommand is covered without listing it here.
+func TestRunnableAirCommandsGetSkillHint(t *testing.T) {
+ testutil.SetAgentEnv(t, "CLAUDECODE", "1")
+ _, air := airUnderRoot(t.Context(), new(bool))
+ assert.False(t, air.Runnable(), "bare air renders help; the footer covers it")
+
+ var runnable []string
+ var walk func(c *cobra.Command)
+ walk = func(c *cobra.Command) {
+ for _, sub := range c.Commands() {
+ if sub.Runnable() {
+ runnable = append(runnable, sub.CommandPath())
+ }
+ walk(sub)
+ }
+ }
+ walk(air)
+ for _, name := range []string{"run", "get", "list", "logs", "cancel", "convert-to-dabs"} {
+ assert.Contains(t, runnable, "databricks air "+name)
+ }
+
+ var visit func(c *cobra.Command)
+ visit = func(c *cobra.Command) {
+ for _, sub := range c.Commands() {
+ if sub.Runnable() {
+ t.Run(sub.CommandPath(), func(t *testing.T) {
+ t.Chdir(t.TempDir())
+ ctx, stderr := cmdio.NewTestContextWithStderr(t.Context())
+ ctx = env.WithUserHomeDir(ctx, t.TempDir())
+ ctx = env.Set(ctx, "DATABRICKS_CACHE_DIR", t.TempDir())
+ agents.MaybeHint(ctx, sub, func(context.Context, string) bool { return false })
+ assert.Contains(t, stderr.String(), "install the databricks-ai-runtime skill")
+ })
+ }
+ visit(sub)
+ }
+ }
+ visit(air)
+}
diff --git a/libs/aitools/agents/calling.go b/libs/aitools/agents/calling.go
index 629554bce29..a0bfe24d7af 100644
--- a/libs/aitools/agents/calling.go
+++ b/libs/aitools/agents/calling.go
@@ -62,8 +62,10 @@ func (t Tooling) String() string {
// record. For Codex and Copilot, pluginRecorded (the CLI install state) is the
// only plugin source, so it misses plugins installed with the agent's own CLI
// and includes plugins later removed with it. The shared skills store is not consulted: it cannot attribute skills.
-// The install hint uses it too, so Claude Code is hinted exactly when it loads
-// no Databricks tooling.
+// The install hint's airSkillAvailable (used on `databricks air` subcommands)
+// differs on purpose: it looks for the AI Runtime skill only (the plugin
+// counts either way), so another Databricks skill never silences a hint about
+// that one.
func (a *Agent) DatabricksTooling(ctx context.Context, pluginRecorded func() bool) Tooling {
// An unknown working directory skips the project lookups below.
cwd := ""
diff --git a/libs/aitools/agents/hint.go b/libs/aitools/agents/hint.go
index f3c49839721..89008c8162d 100644
--- a/libs/aitools/agents/hint.go
+++ b/libs/aitools/agents/hint.go
@@ -2,6 +2,8 @@ package agents
import (
"context"
+ "os"
+ "path/filepath"
"strings"
"time"
@@ -21,6 +23,16 @@ const (
// after thorough testing.
hintText = "Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install"
+ // airSkillName is the agent skill for `databricks air`.
+ airSkillName = "databricks-ai-runtime"
+
+ // airHintText recommends the AI Runtime skill on the commands it helps with.
+ // It names the skill and what it buys the agent, so a coding agent can tell
+ // the hint is about the task at hand rather than generic setup, and offers a
+ // --path preview so the agent can read the skill without installing anything.
+ airHintText = "Tip: install the " + airSkillName + " skill for workload configuration and run debugging: databricks aitools install --skills-only --skills " + airSkillName +
+ ". To preview it first, replace --skills-only with --path ."
+
// claudeAgentProvider is the useragent.AgentProvider() value for Claude Code.
// The SDK maps the CLAUDECODE env var to this product name.
// https://github.com/databricks/databricks-sdk-go/blob/main/useragent/agent.go
@@ -49,6 +61,12 @@ const (
// unattended runs.
ciEnv = "CI"
+ // airCommandName is the top-level command whose runnable subcommands swap
+ // the generic install hint for the AI Runtime skill recommendation. Bare
+ // `databricks air` and `--help` render help without running the pre-run
+ // hook; the air help footer carries the same recommendation there.
+ airCommandName = "air"
+
// authCommandName and tokenCommandName name `databricks auth token`, the
// credential helper the SDKs and Terraform run. They embed its stderr
// mid-line in their own errors, where Claude Code can't strip the native
@@ -174,6 +192,28 @@ func hintForAgent(provider string, pluginRecorded PluginRecordedFunc) *agentHint
}
}
+// hintForCommand returns the hint due for cmd. On a runnable `databricks air`
+// subcommand Claude Code gets the AI Runtime skill recommendation instead of
+// the generic install hint: the skill is what helps with air work, and naming
+// it lets the agent tell the hint is about the task at hand rather than
+// generic setup. The plugin suggestion (native) is shared with the generic
+// hint. Other agents keep their generic install hint everywhere: the aitools
+// installer has no per-agent AI Runtime variant to offer them.
+func hintForCommand(cmd *cobra.Command, provider string, pluginRecorded PluginRecordedFunc) *agentHint {
+ hint := hintForAgent(provider, pluginRecorded)
+ if hint != nil && provider == claudeAgentProvider && isAIRSubcommand(cmd) {
+ return &agentHint{
+ installed: airSkillAvailable,
+ text: airHintText,
+ textKind: protos.AitoolsHintKindInstallText,
+ sessionEnv: claudeSessionEnv,
+ native: claudeNativeHintLine,
+ nativeKind: protos.AitoolsHintKindClaudeCodeNative,
+ }
+ }
+ return hint
+}
+
// isHintedAgent reports whether MaybeHint hints the agent with this
// useragent.AgentProvider() value. It defers to hintForAgent so both follow
// the same dispatch; pluginRecorded is only read when the hint's installed
@@ -191,11 +231,16 @@ func (h *agentHint) nativeLine(ctx context.Context) string {
}
// MaybeHint recommends installing the Databricks AI tooling when a supported
-// agent drives the CLI without it installed. It is a no-op for human callers,
-// unsupported agents, hint-exempt commands (isHintExemptCommand), the `auth
-// token` and `auth docker token` credential helpers, a CLI process the CLI
-// started itself, when there is no output stream, and once the tooling is
-// present.
+// agent drives the CLI without it installed. On a runnable `databricks air`
+// subcommand Claude Code instead gets the AI Runtime skill recommendation,
+// which names the skill, what it covers, and how to preview it: an agent
+// running air has an AI Runtime task for that skill to help with. It is a
+// no-op for human callers, unsupported agents, hint-exempt commands
+// (isHintExemptCommand), the `auth token` and `auth docker token` credential
+// helpers, a CLI process the CLI started itself, when there is no output
+// stream, and once the tooling is present. Bare `databricks air` and
+// `--help` render help without running the pre-run hook; the air help footer
+// carries the same recommendation there.
// The agent-native line (if any) and the model-facing text are throttled
// independently, per session or, for agents without a session id, per agent
// on this machine (fallbackKey). Both hint-shown events follow the text's
@@ -206,7 +251,7 @@ func (h *agentHint) nativeLine(ctx context.Context) string {
// telemetry event for each hint line shown, which makes a command that resolved
// auth upload telemetry at exit.
func MaybeHint(ctx context.Context, cmd *cobra.Command, pluginRecorded PluginRecordedFunc) {
- hint := hintForAgent(useragent.AgentProvider(), pluginRecorded)
+ hint := hintForCommand(cmd, useragent.AgentProvider(), pluginRecorded)
if hint == nil {
return
}
@@ -353,6 +398,19 @@ func isHintExemptCommand(cmd *cobra.Command) bool {
return false
}
+// isAIRSubcommand reports whether cmd sits under the top-level air command
+// (`databricks air list`, `databricks air pools list`, ...), excluding air
+// itself. Matching on the top-level ancestor keeps hidden aliases such as
+// `databricks experimental air` out.
+func isAIRSubcommand(cmd *cobra.Command) bool {
+ for c := cmd; c.HasParent(); c = c.Parent() {
+ if !c.Parent().HasParent() {
+ return c != cmd && c.Name() == airCommandName
+ }
+ }
+ return false
+}
+
// claudeToolingInstalled reports whether Claude Code has Databricks AI tooling
// in its own locations (see Agent.DatabricksTooling): the databricks plugin, or
// databricks skills in Claude's skills dirs. Skills present only in the shared
@@ -379,6 +437,54 @@ func claudeToolingInstalled(ctx context.Context) bool {
return tooling != ToolingNone
}
+// airSkillAvailable reports whether Claude Code has the AI Runtime skill in a
+// location it loads for the current working directory: the databricks plugin
+// (which bundles every Databricks skill) installed for every project or for
+// this one, or a databricks-ai-runtime skill dir in Claude's own skills dir or
+// in the project skills dir of cwd or a parent up to the repository root.
+// Other Databricks skills do not count: they don't cover air, and this hint
+// recommends installing exactly this skill. Skills in the shared
+// ~/.databricks/aitools/skills store don't count either, because Claude Code
+// doesn't load them from there (see DatabricksTooling). Any read/parse failure
+// reports false, so an unreadable state errs toward hinting.
+func airSkillAvailable(ctx context.Context) bool {
+ claude := ByName(NameClaudeCode)
+ if claude == nil {
+ // claude-code is always in the registry; this guard keeps the hint
+ // best-effort rather than panicking in a persistent pre-run hook.
+ return false
+ }
+ cwd := ""
+ if wd, err := os.Getwd(); err == nil {
+ cwd = resolvePath(wd)
+ }
+ if claude.pluginInstalls != nil {
+ if active, _ := claude.DatabricksPluginActiveIn(ctx, cwd); active {
+ log.Debugf(ctx, "Databricks plugin active for Claude Code in %q; skipping AI Runtime skill hint", cwd)
+ return true
+ }
+ }
+ if dir, err := claude.SkillsDir(ctx); err == nil && airSkillDirInstalled(dir) {
+ return true
+ }
+ if claude.SupportsProjectScope && cwd != "" {
+ for _, dir := range projectDirs(cwd) {
+ if airSkillDirInstalled(claude.ProjectSkillsDir(dir)) {
+ return true
+ }
+ }
+ }
+ return false
+}
+
+// airSkillDirInstalled reports whether dir holds the AI Runtime skill as a
+// directory. Stat follows the symlinks the installer may leave in place of
+// copies.
+func airSkillDirInstalled(dir string) bool {
+ info, err := os.Stat(filepath.Join(dir, airSkillName))
+ return err == nil && info.IsDir()
+}
+
// throttleKey returns the cache key throttling the hint: the session id behind
// sessionKeyPrefix, else fallbackKey. "" means no throttle.
func (h *agentHint) throttleKey(ctx context.Context) string {
diff --git a/libs/aitools/agents/hint_agents_test.go b/libs/aitools/agents/hint_agents_test.go
index 73c42aaf6d1..412699386f3 100644
--- a/libs/aitools/agents/hint_agents_test.go
+++ b/libs/aitools/agents/hint_agents_test.go
@@ -326,3 +326,20 @@ func TestMaybeHint_DisabledCacheSkipsHint(t *testing.T) {
assert.Empty(t, telemetry.BufferedEvents(ctx))
}
}
+
+// Non-Claude agents keep their generic install hint on `databricks air`
+// subcommands too: the aitools installer has no per-agent AI Runtime variant
+// to offer them, so the air scoping only changes Claude Code's hint.
+func TestMaybeHint_AgentInstallHintUnchangedOnAIR(t *testing.T) {
+ for _, a := range Registry {
+ if a.Name == NameClaudeCode {
+ continue
+ }
+ t.Run(a.Name, func(t *testing.T) {
+ setAgentEnv(t, agentDetectEnv[a.Name])
+ ctx, stderr := agentCtx(t, t.TempDir(), t.TempDir())
+ MaybeHint(ctx, airCmd(), noPluginRecorded)
+ assert.Equal(t, agentInstallHint(a, noPluginRecorded).text+"\n", stderr.String())
+ })
+ }
+}
diff --git a/libs/aitools/agents/hint_test.go b/libs/aitools/agents/hint_test.go
index c3f092e1eae..e49a77cbc9f 100644
--- a/libs/aitools/agents/hint_test.go
+++ b/libs/aitools/agents/hint_test.go
@@ -446,6 +446,21 @@ func TestMaybeHint_NativeHint(t *testing.T) {
wantStderr: wantNativeHint + "\n" + hintText + "\n",
cmd: func() *cobra.Command { return authDockerCmd("configure [PROFILE]") },
},
+ {
+ // On air subcommands the text is the AI Runtime skill line.
+ name: "air command prints native then air text",
+ env: map[string]string{claudeChildSessionEnv: "1"},
+ wantStderr: wantNativeHint + "\n" + airHintText + "\n",
+ cmd: func() *cobra.Command { return airCmd() },
+ },
+ {
+ name: "air command with the skill installed prints nothing",
+ env: map[string]string{claudeChildSessionEnv: "1"},
+ cmd: func() *cobra.Command { return airCmd() },
+ setup: func(t *testing.T, home string) {
+ writeClaudeSkill(t, home, airSkillName)
+ },
+ },
{
// air images push runs `auth docker configure` and embeds its
// output in an error; the child must add nothing to it.
@@ -770,6 +785,263 @@ func TestMaybeHint_InstalledLogsNothing(t *testing.T) {
assert.Empty(t, telemetry.BufferedEvents(ctx))
}
+// --- AI Runtime skill hint on air subcommands ---
+
+func airCmd() *cobra.Command { return commandAt("air list") }
+
+// writeProjectPluginManifest writes a manifest with one project-scope install
+// covering projectPath. Marshaled, not interpolated, so Windows paths with
+// backslashes stay valid JSON.
+func writeProjectPluginManifest(t *testing.T, home, projectPath string) {
+ manifest, err := json.Marshal(map[string]any{
+ "plugins": map[string]any{
+ "databricks@claude-plugins-official": []any{map[string]string{
+ "scope": "project",
+ "projectPath": projectPath,
+ }},
+ },
+ })
+ require.NoError(t, err)
+ writePluginManifest(t, home, string(manifest))
+}
+
+// assertAIRHinted checks for exactly the AI Runtime skill line and one
+// hint-shown event of kind INSTALL_TEXT.
+func assertAIRHinted(t *testing.T, ctx context.Context, stderr *bytes.Buffer) {
+ t.Helper()
+ assert.Equal(t, airHintText+"\n", stderr.String())
+ assert.Equal(t, []protos.AitoolsHintKind{protos.AitoolsHintKindInstallText}, hintKinds(t, ctx))
+}
+
+// assertNothingHinted checks for no hint line and no telemetry event.
+func assertNothingHinted(t *testing.T, ctx context.Context, stderr *bytes.Buffer) {
+ t.Helper()
+ assert.Empty(t, stderr.String())
+ assert.Empty(t, hintKinds(t, ctx))
+}
+
+func TestAIRHintText(t *testing.T) {
+ // The hint names the skill, says what it is for, and offers both the install
+ // and a no-install preview, on one line.
+ assert.Contains(t, airHintText, "install the databricks-ai-runtime skill")
+ assert.Contains(t, airHintText, "workload configuration and run debugging")
+ assert.Contains(t, airHintText, "databricks aitools install --skills-only --skills databricks-ai-runtime")
+ assert.Contains(t, airHintText, "replace --skills-only with --path ")
+ assert.NotContains(t, airHintText, "\n")
+}
+
+// TestMaybeHint_NonAIRCommandsKeepGenericHint pins the scoping: outside air,
+// Claude Code gets the generic install hint it always got, never the AI
+// Runtime skill line.
+func TestMaybeHint_NonAIRCommandsKeepGenericHint(t *testing.T) {
+ setClaudeAgent(t)
+ for _, path := range []string{
+ "clusters list", "jobs list", "bundle deploy", "workspace list",
+ // The bare air node only renders help (the footer carries the tip), and
+ // the hidden alias points users at `databricks air`; neither is an air
+ // subcommand, so they keep the generic hint.
+ "air",
+ "experimental air",
+ } {
+ t.Run(path, func(t *testing.T) {
+ ctx, stderr := claudeCtx(t, t.TempDir())
+ ctx = telemetry.WithNewLogger(ctx)
+ MaybeHint(ctx, commandAt(path), noPluginRecorded)
+ assert.Equal(t, hintText+"\n", stderr.String())
+ assert.Equal(t, []protos.AitoolsHintKind{protos.AitoolsHintKindInstallText}, hintKinds(t, ctx))
+ assert.NotContains(t, stderr.String(), airHintText)
+ })
+ }
+}
+
+// Hint-exempt non-air commands stay exactly as main keeps them: no hint of
+// either kind. auth profiles is here because it was the original complaint
+// this PR's scoping answers; main's exemption list now covers it.
+func TestMaybeHint_ExemptNonAIRCommandsSilent(t *testing.T) {
+ setClaudeAgent(t)
+ for _, path := range []string{
+ "auth profiles", "current-user me", "version",
+ } {
+ t.Run(path, func(t *testing.T) {
+ ctx, stderr := claudeCtx(t, t.TempDir())
+ ctx = telemetry.WithNewLogger(ctx)
+ MaybeHint(ctx, commandAt(path), noPluginRecorded)
+ assert.Empty(t, stderr.String())
+ assert.Empty(t, hintKinds(t, ctx))
+ })
+ }
+}
+
+// Every runnable air subcommand, at any depth, gets the skill-specific hint.
+func TestMaybeHint_AIRSubcommandsHint(t *testing.T) {
+ setClaudeAgent(t)
+ for _, path := range []string{
+ "air run", "air get", "air list", "air logs", "air cancel",
+ "air convert-to-dabs", "air images", "air images push", "air pools", "air pools list",
+ } {
+ t.Run(path, func(t *testing.T) {
+ ctx, stderr := claudeCtx(t, t.TempDir())
+ ctx = telemetry.WithNewLogger(ctx)
+ MaybeHint(ctx, commandAt(path), noPluginRecorded)
+ assertAIRHinted(t, ctx, stderr)
+ })
+ }
+}
+
+// Only the databricks-ai-runtime skill itself, in a location Claude Code loads
+// for this working directory, silences the skill hint.
+func TestMaybeHint_AIRSkillDetection(t *testing.T) {
+ for _, tc := range []struct {
+ name string
+ setup func(t *testing.T, home, cwd string)
+ wantHint bool
+ }{
+ {"nothing installed", func(t *testing.T, home, cwd string) {}, true},
+ {"skill in Claude's own skills dir", func(t *testing.T, home, cwd string) {
+ writeClaudeSkill(t, home, airSkillName)
+ }, false},
+ {"skill in the project skills dir", func(t *testing.T, home, cwd string) {
+ require.NoError(t, os.MkdirAll(filepath.Join(cwd, ".claude", "skills", airSkillName), 0o755))
+ }, false},
+ {"other databricks skills only", func(t *testing.T, home, cwd string) {
+ writeClaudeSkill(t, home, "databricks")
+ writeClaudeSkill(t, home, "databricks-jobs")
+ }, true},
+ {"a file named like the skill", func(t *testing.T, home, cwd string) {
+ dir := filepath.Join(home, ".claude", "skills")
+ require.NoError(t, os.MkdirAll(dir, 0o755))
+ require.NoError(t, os.WriteFile(filepath.Join(dir, airSkillName), nil, 0o600))
+ }, true},
+ {"shared canonical store", func(t *testing.T, home, cwd string) {
+ writeCanonicalSkill(t, home, airSkillName)
+ }, true},
+ {"shared legacy store", func(t *testing.T, home, cwd string) {
+ require.NoError(t, os.MkdirAll(filepath.Join(home, LegacySkillsDir, airSkillName), 0o755))
+ }, true},
+ {"plugin for this project", func(t *testing.T, home, cwd string) {
+ writeProjectPluginManifest(t, home, cwd)
+ }, false},
+ {"plugin for an unrelated project", func(t *testing.T, home, cwd string) {
+ writeProjectPluginManifest(t, home, t.TempDir())
+ }, true},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ // A fresh project per case: the project-skills fixtures write into
+ // the working directory and must not leak between cases.
+ setClaudeAgent(t)
+ home := t.TempDir()
+ ctx, stderr := claudeCtx(t, home)
+ ctx = telemetry.WithNewLogger(ctx)
+ cwd, err := os.Getwd()
+ require.NoError(t, err)
+ tc.setup(t, home, cwd)
+
+ MaybeHint(ctx, airCmd(), noPluginRecorded)
+ if tc.wantHint {
+ assertAIRHinted(t, ctx, stderr)
+ } else {
+ assertNothingHinted(t, ctx, stderr)
+ }
+ })
+ }
+}
+
+// A project-scoped skill at the repository root still counts when the CLI runs
+// in a subdirectory, as Claude Code loads it there.
+func TestMaybeHint_AIRSkillInRepositoryRoot(t *testing.T) {
+ setClaudeAgent(t)
+ home := t.TempDir()
+ ctx, stderr := claudeCtx(t, home)
+ ctx = telemetry.WithNewLogger(ctx)
+ root, err := os.Getwd()
+ require.NoError(t, err)
+ require.NoError(t, os.MkdirAll(filepath.Join(root, ".claude", "skills", airSkillName), 0o755))
+ sub := filepath.Join(root, "training", "configs")
+ require.NoError(t, os.MkdirAll(sub, 0o755))
+ t.Chdir(sub)
+
+ MaybeHint(ctx, airCmd(), noPluginRecorded)
+ assertNothingHinted(t, ctx, stderr)
+}
+
+func TestAIRSkillAvailable_LogsPluginDetection(t *testing.T) {
+ // Clears the host's CLAUDE_CONFIG_DIR, which would move the manifest.
+ testutil.SetAgentEnv(t)
+ t.Chdir(t.TempDir())
+ home := t.TempDir()
+ writePluginManifest(t, home, `{"plugins":{"databricks@claude-plugins-official":[{"version":"0.2.6"}]}}`)
+
+ // Capture debug output by installing a text logger on the context.
+ var buf bytes.Buffer
+ handler := slog.NewTextHandler(&buf, &slog.HandlerOptions{Level: log.LevelDebug})
+ ctx := log.NewContext(t.Context(), slog.New(handler))
+ ctx = env.WithUserHomeDir(ctx, home)
+
+ assert.True(t, airSkillAvailable(ctx))
+
+ assert.Contains(t, buf.String(), "Databricks plugin active for Claude Code")
+ assert.Contains(t, buf.String(), "skipping AI Runtime skill hint")
+}
+
+// With a session id the first hinted command is the only one; without one
+// (older Claude Code) every air command is hinted. The throttle is shared with
+// the generic hint, so a hint already shown on a non-air command also silences
+// the air one for the rest of the session.
+func TestMaybeHint_AIRSessionThrottle(t *testing.T) {
+ setClaudeAgent(t)
+ home := t.TempDir()
+ cacheDir := t.TempDir()
+ newCtx := func() (context.Context, *bytes.Buffer) {
+ ctx, stderr := claudeCtx(t, home)
+ ctx = env.Set(ctx, "DATABRICKS_CACHE_DIR", cacheDir)
+ ctx = env.Set(ctx, claudeSessionEnv, "session-abc")
+ ctx = telemetry.WithNewLogger(ctx)
+ return ctx, stderr
+ }
+
+ ctx1, stderr1 := newCtx()
+ MaybeHint(ctx1, airCmd(), noPluginRecorded)
+ assertAIRHinted(t, ctx1, stderr1)
+
+ // Same session, second air command: stays quiet.
+ ctx2, stderr2 := newCtx()
+ MaybeHint(ctx2, commandAt("air run"), noPluginRecorded)
+ assertNothingHinted(t, ctx2, stderr2)
+
+ // Another session: the air hint prints again.
+ ctx3, stderr3 := newCtx()
+ ctx3 = env.Set(ctx3, claudeSessionEnv, "session-def")
+ MaybeHint(ctx3, commandAt("air run"), noPluginRecorded)
+ assertAIRHinted(t, ctx3, stderr3)
+
+ // A generic hint shown on a non-air command consumes the same session's
+ // marker, so a later air command stays quiet.
+ ctx4, stderr4 := newCtx()
+ ctx4 = env.Set(ctx4, claudeSessionEnv, "session-ghi")
+ MaybeHint(ctx4, commandAt("clusters list"), noPluginRecorded)
+ assert.Equal(t, hintText+"\n", stderr4.String())
+ ctx5, stderr5 := newCtx()
+ ctx5 = env.Set(ctx5, claudeSessionEnv, "session-ghi")
+ MaybeHint(ctx5, airCmd(), noPluginRecorded)
+ assertNothingHinted(t, ctx5, stderr5)
+}
+
+func TestHintForCommand(t *testing.T) {
+ air := hintForCommand(airCmd(), claudeAgentProvider, noPluginRecorded)
+ require.NotNil(t, air)
+ assert.Equal(t, airHintText, air.text)
+
+ // Outside air Claude Code keeps the generic hint.
+ regular := hintForCommand(regularCmd(), claudeAgentProvider, noPluginRecorded)
+ require.NotNil(t, regular)
+ assert.Equal(t, hintText, regular.text)
+
+ // Other agents are untouched on air subcommands.
+ cursor := hintForCommand(airCmd(), "cursor", noPluginRecorded)
+ require.NotNil(t, cursor)
+ assert.Equal(t, agentInstallHint(ByName(NameCursor), noPluginRecorded).text, cursor.text)
+}
+
// writeProjectSkill creates a project-scoped Claude skill symlink.
func writeProjectSkill(t *testing.T, project, name string) {
canonical := filepath.Join(project, ".databricks", "aitools", "skills", name)