diff --git a/.nextchanges/cli/aitools-install-path-help.md b/.nextchanges/cli/aitools-install-path-help.md
new file mode 100644
index 00000000000..57409607186
--- /dev/null
+++ b/.nextchanges/cli/aitools-install-path-help.md
@@ -0,0 +1 @@
+* Clarify how to install selected skills to a custom directory. ([#7572](https://github.com/databricks/cli/pull/7572))
diff --git a/cmd/aitools/install.go b/cmd/aitools/install.go
index b050ec7bac0..63d6efbde33 100644
--- a/cmd/aitools/install.go
+++ b/cmd/aitools/install.go
@@ -93,7 +93,7 @@ By default this installs the databricks plugin through each agent's own CLI
(` + strings.Join(agents.SkillsOnlyNames(), ", ") + `) get raw skill files.
Escape hatches:
- --skills-only Force raw skill files for every agent (no plugin).
+ --skills-only Force raw skill files for every agent (no plugin; not with --path).
--skills name1,name2 Install only the named skills (with --skills-only/--path).
--path
Write resolved skill files to a directory (no agents, no state).
@@ -107,6 +107,11 @@ Output:
and --agents so the command runs without interactive prompts.
Supported agents: ` + strings.Join(agents.SupportedNames(), ", "),
+ Example: ` # Install a selected skill for coding agents.
+ databricks aitools install --skills-only --skills databricks-ai-runtime
+
+ # Write a selected skill to a custom directory (omit --skills-only).
+ databricks aitools install --skills databricks-ai-runtime --path ./skills`,
Args: cobra.NoArgs,
RunE: func(cmd *cobra.Command, args []string) (err error) {
ctx := cmd.Context()
@@ -309,8 +314,8 @@ Supported agents: ` + strings.Join(agents.SupportedNames(), ", "),
cmd.Flags().StringVar(&skillsFlag, "skills", "", "Specific skills to install (comma-separated)")
cmd.Flags().StringVar(&agentsFlag, "agents", "", "Agents to install for (comma-separated, e.g. claude-code,cursor)")
cmd.Flags().BoolVar(&includeExperimental, "experimental", false, "Include experimental skills")
- cmd.Flags().BoolVar(&skillsOnly, "skills-only", false, "Force raw skill files for every agent instead of the plugin")
- cmd.Flags().StringVar(&pathFlag, "path", "", "Write resolved skill files to this directory (no agents, no state)")
+ cmd.Flags().BoolVar(&skillsOnly, "skills-only", false, "Force raw skill files for every agent instead of the plugin (not with --path)")
+ cmd.Flags().StringVar(&pathFlag, "path", "", "Write resolved skill files to this directory instead of using --skills-only (no agents, no state)")
cmd.Flags().StringVar(&scopeFlag, "scope", "", "Install scope: project or global (default: global, or prompt when interactive)")
cmd.Flags().BoolVar(&projectFlag, "project", false, "Install to project directory (cwd)")
cmd.Flags().BoolVar(&globalFlag, "global", false, "Install globally (default)")
diff --git a/cmd/aitools/legacy_skills.go b/cmd/aitools/legacy_skills.go
index 67ed8854dea..e0838e7dbae 100644
--- a/cmd/aitools/legacy_skills.go
+++ b/cmd/aitools/legacy_skills.go
@@ -39,7 +39,7 @@ func newLegacySkillsInstallCmd() *cobra.Command {
cmd := &cobra.Command{
Use: "install [skill-name]",
Short: "Install Databricks skills for detected coding agents",
- Deprecated: `use "databricks aitools install --skills " instead.`,
+ Deprecated: `use "databricks aitools install --skills-only --skills " instead.`,
Args: cobra.MaximumNArgs(1),
RunE: func(cmd *cobra.Command, args []string) error {
installCmd := NewInstallCmd()