Skip to content
Merged
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/aitools-install-skills-fallback.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
* `databricks aitools install` now installs skill files for a detected coding agent whose CLI is not on PATH (for example a Claude Code desktop or IDE install), unless it already has the plugin, says how to switch to the plugin later, and warns when the current project also has the plugin. `databricks aitools update` no longer tries to install the plugin for such an agent, and no longer writes skill files next to a plugin that such an agent already has. ([#7482](https://github.com/databricks/cli/pull/7482))
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{"plugins":{"databricks@claude-plugins-official":[{"scope":"user","version":"0.2.9"}]}}
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Cloud = false
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@

=== no flags, no terminal: no prompts, global scope, every detected agent

>>> [CLI] aitools install
Skipped the plugin for Claude Code: 'claude' is not on PATH. Installing skill files instead; to switch to the plugin, install the Claude Code CLI so 'claude' is on PATH and run 'databricks aitools install --scope=global --agents=claude-code'.
Installing Databricks skills for Claude Code, Cursor...
Using skills version test-ref
Fetching skills manifest...
Installed 1 skill.
Claude Code has skill files

=== a plugin installed with Claude Code itself is kept, without skill files next to it

>>> [CLI] aitools install
Claude Code already has the databricks plugin; it was not refreshed because 'claude' is not on PATH. To refresh it, install the Claude Code CLI so 'claude' is on PATH and run 'databricks aitools install --scope=global --agents=claude-code'.
Installing Databricks skills for Cursor...
Using skills version test-ref
Fetching skills manifest...
Installed 1 skill.
Claude Code has no skill files

>>> [CLI] aitools update --force
updated test-stable v1.0.0 -> v1.0.0
Updated 1 skill.
Claude Code has no skill files

=== a named agent does not fall back: the failure says what to run

>>> musterr [CLI] aitools install --agents=claude-code
Installing databricks plugin for Claude Code...
Skipped Claude Code: 'claude' is not on PATH
Install or update the Claude Code CLI so 'claude' is on PATH, then re-run 'databricks aitools install --scope=global --agents=claude-code'. Or install skill files instead: databricks aitools install --scope=global --agents=claude-code --skills-only
Error: Claude Code: 'claude' is not on PATH

=== the suggested recovery command works

>>> [CLI] aitools install --agents=claude-code --skills-only
Installing Databricks skills for Claude Code...
Using skills version test-ref
Fetching skills manifest...
Installed 1 skill.

=== project scope: a personal plugin does not replace the project's skill files

>>> [CLI] aitools install --scope=project
Skipped the plugin for Claude Code: 'claude' is not on PATH. Installing skill files instead; to switch to the plugin, install the Claude Code CLI so 'claude' is on PATH and run 'databricks aitools install --scope=project --agents=claude-code'.
Installing Databricks skills for Claude Code...
Using skills version test-ref
Fetching skills manifest...
Installed 1 skill.
Skipped Cursor: does not support project-scoped skills
To set up Cursor in the global scope, run: databricks aitools install --scope=global --agents=cursor

>>> [CLI] aitools update --scope=project
Skipped Cursor: does not support project-scoped skills.
Already up to date.
The project has Claude Code skill files

=== nothing can be set up: the run fails instead of exiting 0

>>> musterr [CLI] aitools install --scope=project
Skipped Cursor: does not support project-scoped skills
To set up Cursor in the global scope, run: databricks aitools install --scope=global --agents=cursor
Error: nothing was installed; follow the steps above
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
# Isolate HOME so parallel aitools tests don't race on a shared ~/.databricks.
sethome home

# Agent config dirs can also be moved by environment variables. Point them all
# at the fixture HOME, so the developer's own agents are not detected and
# nothing is written outside it.
unset CLAUDE_CONFIG_DIR PI_CODING_AGENT_DIR GEMINI_CLI_HOME GOOSE_PATH_ROOT
export XDG_CONFIG_HOME="${USERPROFILE:-$HOME}/.config"
export APPDATA="${USERPROFILE:-$HOME}/AppData/Roaming"

# Agents are also detected by their CLI binary on PATH, so drop every PATH entry
# that holds one; otherwise the developer's own agents would join the run. That
# can drop /usr/bin (and /bin on a merged-/usr system), so resolve the commands
# the script runs first. Windows also finds a command under each PATHEXT
# extension (e.g. claude.cmd), so check those names too.
mkdir_bin=$(command -v mkdir)
rm_bin=$(command -v rm)
cp_bin=$(command -v cp)
exts=""
if [ -n "${PATHEXT:-}" ]; then exts=$(printf '%s' "$PATHEXT" | tr ';' ':'); fi
filtered_path=""
IFS=:
for dir in $PATH; do
keep=1
for bin in claude cursor-agent codex opencode copilot pi gemini goose kiro; do
if [ -x "$dir/$bin" ]; then keep=; fi
for ext in $exts; do
if [ -f "$dir/$bin$ext" ]; then keep=; fi
done
done
if [ -n "$keep" ]; then filtered_path="$filtered_path:$dir"; fi
done
unset IFS
export PATH="${filtered_path#:}"

# Claude Code's config dir exists but its CLI is not on PATH (desktop or IDE
# install). Cursor has no plugin and gets raw skill files.
"$mkdir_bin" -p "${USERPROFILE:-$HOME}/.claude" "${USERPROFILE:-$HOME}/.cursor"

check_claude_skills() {
if [ -e "${USERPROFILE:-$HOME}/.claude/skills/test-stable" ]; then echo "Claude Code has skill files"; else echo "Claude Code has no skill files"; fi
}

title "no flags, no terminal: no prompts, global scope, every detected agent"
# Stdin is not a TTY, so the scope select and agent picker are skipped. Cursor
# gets skills; Claude Code's plugin cannot be installed without its CLI, so it
# gets skill files too, with a note on how to switch to the plugin later.
trace $CLI aitools install
check_claude_skills

title "a plugin installed with Claude Code itself is kept, without skill files next to it"
# Claude Code records its plugins in installed_plugins.json. The run keeps the
# plugin and removes the skill files the previous run gave Claude Code, and a
# later update does not write them back.
"$mkdir_bin" -p "${USERPROFILE:-$HOME}/.claude/plugins"
"$cp_bin" installed_plugins.json "${USERPROFILE:-$HOME}/.claude/plugins/"
trace $CLI aitools install
check_claude_skills
trace $CLI aitools update --force
check_claude_skills
"$rm_bin" -rf "${USERPROFILE:-$HOME}/.claude/plugins"

title "a named agent does not fall back: the failure says what to run"
trace musterr $CLI aitools install --agents=claude-code

title "the suggested recovery command works"
trace $CLI aitools install --agents=claude-code --skills-only

title "project scope: a personal plugin does not replace the project's skill files"
# Project skill files are shared through the repository, so a user-scope plugin
# installed with Claude Code itself later must not stop the update from
# refreshing them. Cursor only supports global skills and is skipped.
testdir=$(pwd)
"$mkdir_bin" -p "${USERPROFILE:-$HOME}/project"
cd "${USERPROFILE:-$HOME}/project"
trace $CLI aitools install --scope=project
"$mkdir_bin" -p "${USERPROFILE:-$HOME}/.claude/plugins"
"$cp_bin" "$testdir/installed_plugins.json" "${USERPROFILE:-$HOME}/.claude/plugins/"
trace $CLI aitools update --scope=project
if [ -e .claude/skills/test-stable ]; then echo "The project has Claude Code skill files"; else echo "The project has no Claude Code skill files"; fi
"$rm_bin" -rf "${USERPROFILE:-$HOME}/.claude/plugins"
cd "$testdir"

title "nothing can be set up: the run fails instead of exiting 0"
# Cursor only supports global skills, so a project-scope run has nothing to do.
"$rm_bin" -rf "${USERPROFILE:-$HOME}/.claude"
trace musterr $CLI aitools install --scope=project
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Mock server replaces raw.githubusercontent.com for manifest + skill files.
Env.DATABRICKS_SKILLS_BASE_URL = "$DATABRICKS_HOST"
Env.DATABRICKS_SKILLS_REF = "test-ref"

Ignore = [
"home",
]

[[Server]]
Pattern = "GET /test-ref/manifest.json"
Response.Body = '''
{
"version": "2",
"updated_at": "2026-01-01T00:00:00Z",
"skills": {
"test-stable": {
"version": "1.0.0",
"description": "Stable test skill",
"files": ["SKILL.md"],
"repo_dir": "skills"
}
}
}
'''

[[Server]]
Pattern = "GET /test-ref/skills/test-stable/SKILL.md"
Response.Body = '''---
name: test-stable
---

# Test stable skill
'''
24 changes: 22 additions & 2 deletions cmd/aitools/funnel.go
Original file line number Diff line number Diff line change
Expand Up @@ -178,9 +178,29 @@ func deliverySteps(outcomes []agentOutcome) []protos.AitoolsCommandStep {
return steps
}

// anyInstalled reports whether at least one agent was set up.
// anyInstalled reports whether at least one agent was set up: installed, or
// left with the databricks plugin it already had.
func anyInstalled(outcomes []agentOutcome) bool {
return slices.ContainsFunc(outcomes, func(o agentOutcome) bool { return o.status == outcomeInstalled })
return slices.ContainsFunc(outcomes, func(o agentOutcome) bool {
return o.status == outcomeInstalled || o.status == outcomeKept
})
}

// onlyKeptPlugins reports whether a run installed nothing and failed for no
// agent, because each agent it set up kept the plugin it already had. The
// funnel records such a run as NOTHING_TO_DO rather than SUCCESS.
func onlyKeptPlugins(outcomes []agentOutcome) bool {
kept := false
for _, o := range outcomes {
switch o.status {
case outcomeInstalled, outcomeFailed:
return false
case outcomeKept:
kept = true
case outcomeSkipped:
}
}
return kept
}

// firstFailureCategory returns the category of the first agent that failed or
Expand Down
121 changes: 99 additions & 22 deletions cmd/aitools/funnel_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -570,30 +570,99 @@ func TestListFunnelFailure(t *testing.T) {
}
}

// A plugin failure for an auto-detected agent is only a warning, but when
// nothing got installed the run fails and the funnel must not report SUCCESS.
func TestInstallFunnelDetectedPluginFailureIsNotSuccess(t *testing.T) {
isolateAgents(t)
tmp := t.TempDir()
t.Setenv("HOME", tmp)
t.Setenv("USERPROFILE", tmp)
t.Setenv("XDG_CONFIG_HOME", filepath.Join(tmp, ".config"))
fakeBinsOnPath(t, "codex")
t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6")
setupPluginMock(t)
forbidSkillsInstall(t)
installPluginForAgentFn = func(_ context.Context, a *agents.Agent, _, _ string) (installer.PluginRecord, error) {
return installer.PluginRecord{}, &installer.BlockedError{Agent: a.Name, Reason: installer.ReasonInstallFailed}
// How the funnel finishes when a detected agent's plugin cannot be installed:
// its install failed, or its CLI is missing and it got skill files or kept the
// plugin it already had.
func TestInstallFunnelDetectedPluginAgents(t *testing.T) {
cases := []struct {
name string
claudeConfigDir bool // Claude Code detected by ~/.claude; its CLI is never on PATH
codexOnPath bool // Codex detected by its CLI, whose plugin install fails
pluginInstalled bool
wantErr error
wantShape []string
}{
{
// A plugin failure for an auto-detected agent is only a warning, but
// when nothing got installed the run fails and the funnel takes the
// category from the agent's outcome.
name: "the only install failed",
codexOnPath: true,
wantErr: errNoAgentSetUp,
wantShape: []string{
"STARTED", "FLAGS_VALIDATED", "SCOPE_RESOLVED", "AGENTS_SELECTED", "PLAN_CONFIRMED",
"FINISHED:FAILURE:PLUGIN_INSTALL_FAILED",
},
},
{
name: "CLI missing, skill files instead",
claudeConfigDir: true,
codexOnPath: true,
wantShape: []string{
"STARTED", "FLAGS_VALIDATED", "SCOPE_RESOLVED", "AGENTS_SELECTED", "PLAN_CONFIRMED",
"SKILLS_INSTALLED", "FINISHED:SUCCESS:",
},
},
{
// The run installed nothing, but exits 0.
name: "CLI missing, plugin kept",
claudeConfigDir: true,
pluginInstalled: true,
wantShape: []string{
"STARTED", "FLAGS_VALIDATED", "SCOPE_RESOLVED", "AGENTS_SELECTED", "PLAN_CONFIRMED",
"FINISHED:NOTHING_TO_DO:",
},
},
{
// A kept plugin counts like an installed one: the other agent's
// failed install is only a warning.
name: "CLI missing, plugin kept, another install failed",
claudeConfigDir: true,
codexOnPath: true,
pluginInstalled: true,
wantShape: []string{
"STARTED", "FLAGS_VALIDATED", "SCOPE_RESOLVED", "AGENTS_SELECTED", "PLAN_CONFIRMED",
"FINISHED:SUCCESS:",
},
},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
isolateAgents(t)
tmp := t.TempDir()
t.Setenv("HOME", tmp)
t.Setenv("USERPROFILE", tmp)
t.Setenv("XDG_CONFIG_HOME", filepath.Join(tmp, ".config"))
if tc.claudeConfigDir {
require.NoError(t, os.MkdirAll(filepath.Join(tmp, ".claude"), 0o755))
}
var wantPluginCalls []pluginCall
if tc.codexOnPath {
fakeBinsOnPath(t, "codex")
wantPluginCalls = []pluginCall{{agent: agents.NameCodex}}
} else {
fakeBinsOnPath(t)
}
t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6")
stubPluginAlreadyInstalled(t, tc.pluginInstalled)
stubLegacyCleanup(t)
setupInstallMock(t)
plugins := setupPluginMock(t)
installPluginForAgentFn = func(_ context.Context, a *agents.Agent, _, _ string) (installer.PluginRecord, error) {
*plugins = append(*plugins, pluginCall{agent: a.Name})
return installer.PluginRecord{}, &installer.BlockedError{Agent: a.Name, Reason: installer.ReasonInstallFailed}
}

// The run installed nothing, so it exits non-zero; the FINISHED event takes
// the category from the agent's outcome.
ctx, err := runInstall(t, cmdio.MockDiscard(t.Context()), "--scope", "global")
require.ErrorIs(t, err, errNoAgentSetUp)
assert.Equal(t, []string{
"STARTED", "FLAGS_VALIDATED", "SCOPE_RESOLVED", "AGENTS_SELECTED", "PLAN_CONFIRMED",
"FINISHED:FAILURE:PLUGIN_INSTALL_FAILED",
}, funnelShape(funnelEvents(ctx)))
ctx, err := runInstall(t, cmdio.MockDiscard(t.Context()), "--scope", "global")
if tc.wantErr != nil {
require.ErrorIs(t, err, tc.wantErr)
} else {
require.NoError(t, err)
}
assert.Equal(t, wantPluginCalls, *plugins, "only an agent with its CLI on PATH gets a plugin install")
assert.Equal(t, tc.wantShape, funnelShape(funnelEvents(ctx)))
})
}
}

func TestAnyInstalledAndFirstFailureCategory(t *testing.T) {
Expand All @@ -608,6 +677,13 @@ func TestAnyInstalledAndFirstFailureCategory(t *testing.T) {
assert.False(t, anyInstalled([]agentOutcome{failed, skipped}))
assert.Equal(t, protos.AitoolsErrorCategoryPluginInstallFailed, firstFailureCategory([]agentOutcome{failed, skipped}))

kept := agentOutcome{agent: codex, delivery: deliveryPlugin, status: outcomeKept, errorCategory: protos.AitoolsErrorCategoryCLINotOnPath}
assert.True(t, anyInstalled([]agentOutcome{kept, skipped}), "a kept plugin is set up")
assert.True(t, onlyKeptPlugins([]agentOutcome{kept, skipped}))
assert.False(t, onlyKeptPlugins([]agentOutcome{kept, failed}), "a kept plugin counts like an installed one next to a failed install")
assert.False(t, onlyKeptPlugins([]agentOutcome{kept, installed}))
assert.False(t, onlyKeptPlugins([]agentOutcome{skipped}))

uncategorized := agentOutcome{agent: codex, delivery: deliveryPlugin, status: outcomeFailed}
assert.Equal(t, protos.AitoolsErrorCategoryUnsupportedScope, firstFailureCategory([]agentOutcome{installed, uncategorized, skipped}))
assert.Equal(t, protos.AitoolsErrorCategoryUncategorized, firstFailureCategory([]agentOutcome{installed, uncategorized}))
Expand Down Expand Up @@ -820,6 +896,7 @@ func TestUpdateFunnelWhenPluginsFail(t *testing.T) {
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
isolateCommandEnv(t)
fakeBinsOnPath(t, "copilot")
dir := saveGlobalState(t, tc.skills)
if tc.noPlugins {
require.NoError(t, installer.SaveState(dir, &installer.InstallState{SchemaVersion: 2, Release: "v0.2.6", Skills: tc.skills}))
Expand Down
Loading
Loading