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-manifest-path-validation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
* `databricks aitools install`, `update` and `list` now refuse a skills manifest that names a skill or file outside the skills directory, before writing any skill files. A skill whose name or file paths are not portable is skipped with a warning, and `update` keeps its installed copy. ([#7722](https://github.com/databricks/cli/pull/7722))
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,40 @@

=== a manifest listing a file outside its skill directory fails before any file is written

>>> DATABRICKS_SKILLS_REF=unsafe-ref [CLI] aitools install --skills-only --scope=global --agents=claude-code
Installing Databricks skills for Claude Code...
Using skills version unsafe-ref
Fetching skills manifest...
Error: skills manifest names a path outside the skills directory: skill "test-stable" lists file "../../.bashrc"
No skill files were written. Set DATABRICKS_SKILLS_REF to an earlier release tag from https://github.com/databricks/databricks-agent-skills/releases and re-run 'databricks aitools install --scope=global --agents=claude-code --skills-only', and report the manifest from [DATABRICKS_HOST] at https://github.com/databricks/cli/issues

>>> DATABRICKS_SKILLS_REF=unsafe-ref [CLI] aitools install --skills-only --scope=global --agents=claude-code --output json
{
"scope": "global",
"agents": [],
"error": "skills manifest names a path outside the skills directory: skill \"test-stable\" lists file \"../../.bashrc\"",
"error_category": "MANIFEST_INVALID",
"recovery": "No skill files were written. Set DATABRICKS_SKILLS_REF to an earlier release tag from https://github.com/databricks/databricks-agent-skills/releases and re-run 'databricks aitools install --scope=global --agents=claude-code --skills-only --output json', and report the manifest from [DATABRICKS_HOST] at https://github.com/databricks/cli/issues."
}
no skill files were written

=== a skill with an unportable name is skipped and the others install

>>> DATABRICKS_SKILLS_REF=unportable-ref [CLI] aitools install --skills-only --scope=global --agents=claude-code
Installing Databricks skills for Claude Code...
Using skills version unportable-ref
Fetching skills manifest...
Warn: Skipping skill "Test_Unportable": the name is not at most 64 lowercase letters, digits and single hyphens
Installed 1 skill in [TEST_TMP_DIR]/home/.databricks/aitools/skills.
test-stable

=== naming the unportable skill with --skills fails

>>> DATABRICKS_SKILLS_REF=unportable-ref [CLI] aitools install --skills-only --scope=global --agents=claude-code --skills=Test_Unportable --output json
{
"scope": "global",
"agents": [],
"error": "skill \"Test_Unportable\" cannot be installed: the name is not at most 64 lowercase letters, digits and single hyphens",
"error_category": "MANIFEST_INVALID",
"recovery": "No skill files were written. Set DATABRICKS_SKILLS_REF to an earlier release tag from https://github.com/databricks/databricks-agent-skills/releases and re-run 'databricks aitools install --scope=global --agents=claude-code --skills-only --skills=Test_Unportable --output json', and report the manifest from [DATABRICKS_HOST] at https://github.com/databricks/cli/issues."
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# Isolate HOME so parallel aitools tests don't race on a shared ~/.databricks.
sethome home

title "a manifest listing a file outside its skill directory fails before any file is written"
musterr trace DATABRICKS_SKILLS_REF=unsafe-ref $CLI aitools install --skills-only --scope=global --agents=claude-code
musterr trace DATABRICKS_SKILLS_REF=unsafe-ref $CLI aitools install --skills-only --scope=global --agents=claude-code --output json
if [ -e "$HOME/.databricks/aitools/.bashrc" ] || [ -d "$HOME/.databricks/aitools/skills/test-stable" ]; then
echo "unexpected: a skill file was written"
else
echo "no skill files were written"
fi

title "a skill with an unportable name is skipped and the others install"
trace DATABRICKS_SKILLS_REF=unportable-ref $CLI aitools install --skills-only --scope=global --agents=claude-code
ls "$HOME/.databricks/aitools/skills"

title "naming the unportable skill with --skills fails"
musterr trace DATABRICKS_SKILLS_REF=unportable-ref $CLI aitools install --skills-only --scope=global --agents=claude-code --skills=Test_Unportable --output json
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# Mock server replaces raw.githubusercontent.com for manifest + skill files.
Env.DATABRICKS_SKILLS_BASE_URL = "$DATABRICKS_HOST"

Ignore = [
"home",
]

# A manifest that lists a file outside its skill directory.
[[Server]]
Pattern = "GET /unsafe-ref/manifest.json"
Response.Body = '''
{
"version": "2",
"updated_at": "2026-01-01T00:00:00Z",
"skills": {
"test-stable": {
"version": "1.0.0",
"files": ["SKILL.md", "../../.bashrc"],
"repo_dir": "skills"
}
}
}
'''

# A manifest with one portable skill and one whose name is not in the Agent
# Skills format.
[[Server]]
Pattern = "GET /unportable-ref/manifest.json"
Response.Body = '''
{
"version": "2",
"updated_at": "2026-01-01T00:00:00Z",
"skills": {
"test-stable": {
"version": "1.0.0",
"files": ["SKILL.md"],
"repo_dir": "skills"
},
"Test_Unportable": {
"version": "1.0.0",
"files": ["SKILL.md"],
"repo_dir": "skills"
}
}
}
'''

[[Server]]
Pattern = "GET /unportable-ref/skills/test-stable/SKILL.md"
Response.Body = "test-stable"
8 changes: 8 additions & 0 deletions cmd/aitools/categorize.go
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,11 @@ func classifyInstallError(err error) protos.AitoolsErrorCategory {
if errors.Is(err, installer.ErrUnknownAgent) {
return protos.AitoolsErrorCategoryUnknownAgent
}
// The manifest arrived and parsed, but names a path outside the skills
// directory: content, not transport.
if errors.Is(err, installer.ErrUnsafeManifestPath) {
return protos.AitoolsErrorCategoryManifestInvalid
}
// Skills on disk without the install state that update and uninstall need.
if errors.Is(err, installer.ErrLegacyInstall) {
return protos.AitoolsErrorCategoryStateInvalid
Expand Down Expand Up @@ -137,6 +142,9 @@ func skillErrorCategory(e *installer.SkillError) protos.AitoolsErrorCategory {
return protos.AitoolsErrorCategoryVersionIncompatible
case installer.ReasonExperimentalSkill:
return protos.AitoolsErrorCategoryExperimentalSkill
// The manifest lists the skill in a form it cannot be installed in.
case installer.ReasonUnportableSkill:
return protos.AitoolsErrorCategoryManifestInvalid
default:
return protos.AitoolsErrorCategoryUncategorized
}
Expand Down
20 changes: 20 additions & 0 deletions cmd/aitools/categorize_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -325,3 +325,23 @@ func TestClassifyRealManifestFetchErrors(t *testing.T) {
})
}
}

// TestClassifyUnsafeManifestPath covers a manifest that downloads and parses
// but names a file outside the skills directory: an invalid manifest, not a
// failed download.
func TestClassifyUnsafeManifestPath(t *testing.T) {
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
_, _ = w.Write([]byte(`{"version":"1","skills":{"databricks-core":{"version":"0.1.0","files":["../../.bashrc"]}}}`))
}))
t.Cleanup(server.Close)
t.Setenv("DATABRICKS_SKILLS_BASE_URL", server.URL)

_, _, err := installer.FetchSkillsManifestWithFallback(t.Context(), &installer.GitHubManifestSource{}, "v1", false)
require.ErrorIs(t, err, installer.ErrUnsafeManifestPath)
assert.Equal(t, protos.AitoolsErrorCategoryManifestInvalid, classifyInstallError(err))
}

func TestClassifyUnportableSkill(t *testing.T) {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nit] TestClassifyInstallError (line 29) already has a row for every other SkillError reason, and .agents/rules/testing.md asks for table-driven tests for similar cases. Move this case into that table.

err := &installer.SkillError{Skill: "Databricks_Core", Reason: installer.ReasonUnportableSkill}
assert.Equal(t, protos.AitoolsErrorCategoryManifestInvalid, classifyInstallError(err))
}
5 changes: 5 additions & 0 deletions cmd/aitools/recovery.go
Original file line number Diff line number Diff line change
Expand Up @@ -238,6 +238,11 @@ func installRecovery(ctx context.Context, inv installInvocation, err error) stri
return "The skills release this CLI selected is missing. Set DATABRICKS_SKILLS_REF to a release tag from " + skillsReleasesURL + " and re-run " + rerun + ", and report it at " + cliIssuesURL + "."
case protos.AitoolsErrorCategoryManifestInvalid:
host := skillsHost(ctx)
// The manifest arrived and decoded, but lists a path outside the
// skills directory or a skill in a form it cannot be installed in.
if _, ok := errors.AsType[*installer.SkillError](err); ok || errors.Is(err, installer.ErrUnsafeManifestPath) {
return "No skill files were written. Set DATABRICKS_SKILLS_REF to an earlier release tag from " + skillsReleasesURL + " and re-run " + rerun + ", and report the manifest from " + host + " at " + cliIssuesURL + "."

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nice to have] .agents/rules/testing.md asks for acceptance tests first for user-visible CLI output. The PR changes no acceptance test. The output a user sees is checked only piecewise in unit tests:

  • the new error and its "No skill files were written…" step;
  • error_category: MANIFEST_INVALID under --output json;
  • the --skills <unportable> error.

Add a section with a ../../.bashrc manifest, and one with an unportable --skills name, to acceptance/cmd/aitools/telemetry/install-failure or acceptance/experimental/aitools/skills/install-output-json-error. Both directories already stub manifest.json.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added acceptance/experimental/aitools/skills/install-unsafe-manifest. It covers:

  • the ../../.bashrc manifest in text and --output json (MANIFEST_INVALID plus the recovery step), and checks that no skill file was written;
  • an unportable skill name, which is skipped with the warning while the other skill installs;
  • --skills=<unportable> with --output json.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nit] For --skills <unportable>, the step says to pin an earlier release and re-run the same command. If the skill always had that name (say databricks_sql), every release fails the same way. If the skill didn't exist earlier, the re-run fails with SKILL_NOT_FOUND. For the SkillError case, suggest leaving the skill out of --skills, and report it against the skills repo.

}
return host + " answered with something that is not a skills manifest (a proxy or captive portal page, or a broken mirror). Check what this machine gets from " + host + ", then re-run " + rerun + "."
case protos.AitoolsErrorCategorySkillsFetchFailed:
return downloadRecovery(ctx, inv, ferr)
Expand Down
10 changes: 10 additions & 0 deletions cmd/aitools/recovery_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,16 @@ func TestInstallRecovery(t *testing.T) {
err: &installer.FetchError{Stage: installer.FetchStageManifest, StatusCode: http.StatusOK, Err: fmt.Errorf("failed to parse manifest: %w", &json.SyntaxError{})},
want: "raw.githubusercontent.com answered with something that is not a skills manifest (a proxy or captive portal page, or a broken mirror). Check what this machine gets from raw.githubusercontent.com, then re-run 'databricks aitools install'.",
},
{
name: "manifest names a path outside the skills directory",
err: fmt.Errorf("%w: skill %q lists file %q", installer.ErrUnsafeManifestPath, "databricks-core", "../../.bashrc"),
want: "No skill files were written. Set DATABRICKS_SKILLS_REF to an earlier release tag from " + skillsReleasesURL + " and re-run 'databricks aitools install', and report the manifest from raw.githubusercontent.com at " + cliIssuesURL + ".",
},
{
name: "named skill is not portable",
err: &installer.SkillError{Skill: "Databricks_Core", Reason: installer.ReasonUnportableSkill, Detail: "cannot be installed"},
want: "No skill files were written. Set DATABRICKS_SKILLS_REF to an earlier release tag from " + skillsReleasesURL + " and re-run 'databricks aitools install', and report the manifest from raw.githubusercontent.com at " + cliIssuesURL + ".",
},
{
name: "manifest fetch without a response",
err: &installer.FetchError{Stage: installer.FetchStageManifest, Err: fmt.Errorf("failed to fetch manifest: %w", dnsError)},
Expand Down
8 changes: 8 additions & 0 deletions libs/aitools/installer/errors.go
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,9 @@ const (
ReasonVersionIncompatible = "version-incompatible"
// ReasonExperimentalSkill: the named skill is experimental and --experimental was not set.
ReasonExperimentalSkill = "experimental-skill"
// ReasonUnportableSkill: the manifest lists the skill with a name or file
// path that is not portable, so it is never installed.
ReasonUnportableSkill = "unportable-skill"
)

func (e *SkillError) Error() string {
Expand All @@ -76,6 +79,11 @@ const maxFetchBodySize = 1 << 20
// The command layer classifies it like a manifest that does not parse.
var ErrManifestTooLarge = fmt.Errorf("skills manifest is larger than %d MiB", maxFetchBodySize>>20)

// ErrUnsafeManifestPath reports a skills manifest that names a skill or file
// outside the skills directory. The command layer classifies it like a
// manifest that does not parse.
var ErrUnsafeManifestPath = errors.New("skills manifest names a path outside the skills directory")

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nit] The error reads "names a path outside the skills directory", but it also fires for .state.json (a file inside the directory), . and "". A user sees skills manifest names a path outside the skills directory: skill name ".state.json". A wording such as "names an unsafe path" fits every case. Update the matching comment in cmd/aitools/categorize.go.


// Stages of fetching skills content, recorded on FetchError so a failed
// release lookup can be told apart from a failed download.
const (
Expand Down
21 changes: 18 additions & 3 deletions libs/aitools/installer/installer.go
Original file line number Diff line number Diff line change
Expand Up @@ -259,8 +259,9 @@ func fetchSkillFile(ctx context.Context, ref, repoDir, skillName, filePath strin

// FetchSkillsManifestWithFallback fetches the skills manifest at the given ref.
// 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.
// the embedded manifest's skills version. A manifest that names a skill or file
// outside its directory fails with ErrUnsafeManifestPath, whatever the source.
// Returns the manifest, the (possibly updated) ref, and any 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)
Expand All @@ -274,7 +275,13 @@ func FetchSkillsManifestWithFallback(ctx context.Context, src ManifestSource, re
log.Warnf(ctx, "Could not resolve embedded skills version: %v", fbErr)
}
}
return manifest, ref, err
if err != nil {
return nil, ref, err
}
if err := checkManifestPaths(manifest); err != nil {
return nil, ref, err
}
return manifest, ref, nil
}

// installedSkillsRelease returns the newest recorded raw-skills release and
Expand Down Expand Up @@ -549,6 +556,14 @@ func resolveSkills(ctx context.Context, skills map[string]SkillMeta, opts Instal

result := make(map[string]SkillMeta, len(candidates))
for name, meta := range candidates {
if reason := unportableSkill(name, meta.Files); reason != "" {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nit] The portability check runs before the experimental filter, here and in update.go:149, and warnings print at the default log level. So an experimental skill with an unportable name or file prints Skipping skill "…" on every install, update and apps init, even for users who never pass --experimental. The min_cli_version skip runs after the experimental filter. Move the portability check after the experimental filter in both places.

if isSpecific {
return nil, &SkillError{Skill: name, Reason: ReasonUnportableSkill, Detail: "cannot be installed: " + reason}
}
log.Warnf(ctx, "Skipping skill %q: %s", name, reason)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nit] resolveSkills ranges over the candidates map, so with two unportable skills the Skipping skill warnings print in a different order on each run. .agents/rules/style-guide-go.md asks for sorted order when it reaches logs. The existing min_cli_version warning has the same problem. Iterate slices.Sorted(maps.Keys(candidates)).

continue
}

if meta.IsExperimental() && !opts.IncludeExperimental {
if isSpecific {
return nil, &SkillError{Skill: name, Reason: ReasonExperimentalSkill, Detail: "is experimental; use --experimental to install"}
Expand Down
Loading
Loading