Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .nextchanges/cli/air-skill-hint.md
Original file line number Diff line number Diff line change
@@ -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))
4 changes: 4 additions & 0 deletions acceptance/air/help/output.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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 <dir> --skills databricks-ai-runtime
Writes the skill files to <dir> without installing anything.

=== list help

Expand Down
4 changes: 2 additions & 2 deletions acceptance/air/image-push/output.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
<claude-code-hint v="1" type="plugin" value="databricks@claude-plugins-official" />
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 <dir>.
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
Expand All @@ -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
<claude-code-hint v="1" type="plugin" value="databricks@claude-plugins-official" />
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 <dir>.
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
4 changes: 4 additions & 0 deletions cmd/air/air.go
Original file line number Diff line number Diff line change
Expand Up @@ -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 <dir> --skills databricks-ai-runtime
Writes the skill files to <dir> without installing anything.
`

// Spec declares the air command.
Expand Down
5 changes: 5 additions & 0 deletions cmd/air/air_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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 <dir> --skills databricks-ai-runtime")

list := findSubcommand(t, cmd, "list")
var listOut bytes.Buffer
Expand Down
90 changes: 90 additions & 0 deletions cmd/air/hint_test.go
Original file line number Diff line number Diff line change
@@ -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 <dir> --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)
}
6 changes: 4 additions & 2 deletions libs/aitools/agents/calling.go
Original file line number Diff line number Diff line change
Expand Up @@ -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 := ""
Expand Down
118 changes: 112 additions & 6 deletions libs/aitools/agents/hint.go
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@ package agents

import (
"context"
"os"
"path/filepath"
"strings"
"time"

Expand All @@ -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 <dir>."

// 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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
}
Expand Down Expand Up @@ -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
Expand All @@ -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 {
Expand Down
17 changes: 17 additions & 0 deletions libs/aitools/agents/hint_agents_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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())
})
}
}
Loading
Loading