Add --project/--global scope flags and project-scoped skill installation

Implements scope selection for aitools install, update, uninstall, and version
commands. Skills can now be installed to a project directory (cwd) instead of
only globally. Agents that support project scope (Claude Code, Cursor) get
symlinks from their project config dirs to the canonical project skills dir.

Co-authored-by: Isaac

Author: simonfaltum

experimental/aitools/cmd/install.go

@@ -16,24 +16,31 @@ import (
 func newInstallCmd() *cobra.Command {
 	var skillsFlag, agentsFlag string
 	var includeExperimental bool
+	var projectFlag, globalFlag bool
 
 	cmd := &cobra.Command{
 		Use:   "install",
 		Short: "Install AI skills for coding agents",
 		Long: `Install Databricks AI skills for detected coding agents.
 
-Skills are installed globally to each agent's skills directory.
+By default, skills are installed globally to each agent's skills directory.
+Use --project to install to the current project directory instead.
 When multiple agents are detected, skills are stored in a canonical location
 and symlinked to each agent to avoid duplication.
 
 Supported agents: Claude Code, Cursor, Codex CLI, OpenCode, GitHub Copilot, Antigravity`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()
 
+			// Resolve scope.
+			scope, err := resolveScopeWithPrompt(ctx, projectFlag, globalFlag)
+			if err != nil {
+				return err
+			}
+
 			// Resolve target agents.
 			var targetAgents []*agents.Agent
 			if agentsFlag != "" {
-				var err error
 				targetAgents, err = resolveAgentNames(ctx, agentsFlag)
 				if err != nil {
 					return err
@@ -49,7 +56,6 @@ Supported agents: Claude Code, Cursor, Codex CLI, OpenCode, GitHub Copilot, Anti
 				case len(detected) == 1:
 					targetAgents = detected
 				case cmdio.IsPromptSupported(ctx):
-					var err error
 					targetAgents, err = promptAgentSelection(ctx, detected)
 					if err != nil {
 						return err
@@ -62,6 +68,7 @@ Supported agents: Claude Code, Cursor, Codex CLI, OpenCode, GitHub Copilot, Anti
 			// Build install options.
 			opts := installer.InstallOptions{
 				IncludeExperimental: includeExperimental,
+				Scope:               scope,
 			}
 			if skillsFlag != "" {
 				opts.SpecificSkills = strings.Split(skillsFlag, ",")
@@ -77,6 +84,8 @@ Supported agents: Claude Code, Cursor, Codex CLI, OpenCode, GitHub Copilot, Anti
 	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, "include-experimental", false, "Include experimental skills")
+	cmd.Flags().BoolVar(&projectFlag, "project", false, "Install to project directory (cwd)")
+	cmd.Flags().BoolVar(&globalFlag, "global", false, "Install globally (default)")
 	return cmd
 }
 

experimental/aitools/cmd/install_test.go

@@ -31,6 +31,19 @@ func setupInstallMock(t *testing.T) *[]installCall {
 	return &calls
 }
 
+func setupScopeMock(t *testing.T, scope string) *bool {
+	t.Helper()
+	orig := promptScopeSelection
+	t.Cleanup(func() { promptScopeSelection = orig })
+
+	called := false
+	promptScopeSelection = func(_ context.Context) (string, error) {
+		called = true
+		return scope, nil
+	}
+	return &called
+}
+
 type installCall struct {
 	agents []string
 	opts   installer.InstallOptions
@@ -146,6 +159,7 @@ func TestInstallIncludeExperimental(t *testing.T) {
 func TestInstallInteractivePrompt(t *testing.T) {
 	setupTestAgents(t)
 	calls := setupInstallMock(t)
+	setupScopeMock(t, installer.ScopeGlobal)
 
 	origPrompt := promptAgentSelection
 	t.Cleanup(func() { promptAgentSelection = origPrompt })
@@ -347,3 +361,134 @@ func TestResolveAgentNamesEmpty(t *testing.T) {
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "no agents specified")
 }
+
+// --- Scope flag tests ---
+
+func TestInstallProjectFlag(t *testing.T) {
+	setupTestAgents(t)
+	calls := setupInstallMock(t)
+
+	ctx := cmdio.MockDiscard(t.Context())
+	cmd := newInstallCmd()
+	cmd.SetContext(ctx)
+	cmd.SetArgs([]string{"--project"})
+
+	err := cmd.Execute()
+	require.NoError(t, err)
+
+	require.Len(t, *calls, 1)
+	assert.Equal(t, installer.ScopeProject, (*calls)[0].opts.Scope)
+}
+
+func TestInstallGlobalFlag(t *testing.T) {
+	setupTestAgents(t)
+	calls := setupInstallMock(t)
+
+	ctx := cmdio.MockDiscard(t.Context())
+	cmd := newInstallCmd()
+	cmd.SetContext(ctx)
+	cmd.SetArgs([]string{"--global"})
+
+	err := cmd.Execute()
+	require.NoError(t, err)
+
+	require.Len(t, *calls, 1)
+	assert.Equal(t, installer.ScopeGlobal, (*calls)[0].opts.Scope)
+}
+
+func TestInstallGlobalAndProjectErrors(t *testing.T) {
+	setupTestAgents(t)
+	setupInstallMock(t)
+
+	ctx := cmdio.MockDiscard(t.Context())
+	cmd := newInstallCmd()
+	cmd.SetContext(ctx)
+	cmd.SetArgs([]string{"--global", "--project"})
+	cmd.SilenceErrors = true
+	cmd.SilenceUsage = true
+
+	err := cmd.Execute()
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "cannot use --global and --project together")
+}
+
+func TestInstallNoFlagNonInteractiveUsesGlobal(t *testing.T) {
+	setupTestAgents(t)
+	calls := setupInstallMock(t)
+
+	ctx := cmdio.MockDiscard(t.Context())
+	cmd := newInstallCmd()
+	cmd.SetContext(ctx)
+
+	err := cmd.RunE(cmd, nil)
+	require.NoError(t, err)
+
+	require.Len(t, *calls, 1)
+	assert.Equal(t, installer.ScopeGlobal, (*calls)[0].opts.Scope)
+}
+
+func TestInstallNoFlagInteractiveShowsScopePrompt(t *testing.T) {
+	setupTestAgents(t)
+	calls := setupInstallMock(t)
+	scopePromptCalled := setupScopeMock(t, installer.ScopeProject)
+
+	// Also mock agent prompt since interactive mode triggers it.
+	origPrompt := promptAgentSelection
+	t.Cleanup(func() { promptAgentSelection = origPrompt })
+	promptAgentSelection = func(_ context.Context, detected []*agents.Agent) ([]*agents.Agent, error) {
+		return detected, nil
+	}
+
+	ctx, test := cmdio.SetupTest(t.Context(), cmdio.TestOptions{PromptSupported: true})
+	defer test.Done()
+
+	drain := func(r *bufio.Reader) {
+		buf := make([]byte, 4096)
+		for {
+			_, err := r.Read(buf)
+			if err != nil {
+				return
+			}
+		}
+	}
+	go drain(test.Stdout)
+	go drain(test.Stderr)
+
+	cmd := newInstallCmd()
+	cmd.SetContext(ctx)
+
+	err := cmd.RunE(cmd, nil)
+	require.NoError(t, err)
+
+	assert.True(t, *scopePromptCalled, "scope prompt should be called in interactive mode")
+	require.Len(t, *calls, 1)
+	assert.Equal(t, installer.ScopeProject, (*calls)[0].opts.Scope)
+}
+
+func TestResolveScopeValidation(t *testing.T) {
+	tests := []struct {
+		name    string
+		project bool
+		global  bool
+		want    string
+		wantErr string
+	}{
+		{name: "neither", want: installer.ScopeGlobal},
+		{name: "global only", global: true, want: installer.ScopeGlobal},
+		{name: "project only", project: true, want: installer.ScopeProject},
+		{name: "both", project: true, global: true, wantErr: "cannot use --global and --project together"},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got, err := resolveScope(tc.project, tc.global)
+			if tc.wantErr != "" {
+				require.Error(t, err)
+				assert.Contains(t, err.Error(), tc.wantErr)
+			} else {
+				require.NoError(t, err)
+				assert.Equal(t, tc.want, got)
+			}
+		})
+	}
+}

experimental/aitools/cmd/scope.go

@@ -0,0 +1,74 @@
+package aitools
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+
+	"github.com/charmbracelet/huh"
+	"github.com/databricks/cli/experimental/aitools/lib/installer"
+	"github.com/databricks/cli/libs/cmdio"
+	"github.com/databricks/cli/libs/env"
+)
+
+// promptScopeSelection is a package-level var so tests can replace it with a mock.
+var promptScopeSelection = defaultPromptScopeSelection
+
+// resolveScope validates --project and --global flags and returns the scope.
+func resolveScope(project, global bool) (string, error) {
+	if project && global {
+		return "", errors.New("cannot use --global and --project together")
+	}
+	if project {
+		return installer.ScopeProject, nil
+	}
+	return installer.ScopeGlobal, nil
+}
+
+// resolveScopeWithPrompt resolves scope with optional interactive prompt.
+// When neither flag is set: interactive mode shows a prompt (default: global),
+// non-interactive mode uses global.
+func resolveScopeWithPrompt(ctx context.Context, project, global bool) (string, error) {
+	if project || global {
+		return resolveScope(project, global)
+	}
+
+	// No flag: prompt if interactive, default to global otherwise.
+	if cmdio.IsPromptSupported(ctx) {
+		return promptScopeSelection(ctx)
+	}
+	return installer.ScopeGlobal, nil
+}
+
+func defaultPromptScopeSelection(ctx context.Context) (string, error) {
+	homeDir, err := env.UserHomeDir(ctx)
+	if err != nil {
+		return "", err
+	}
+	globalPath := filepath.Join(homeDir, ".databricks", "aitools", "skills")
+
+	cwd, err := os.Getwd()
+	if err != nil {
+		return "", err
+	}
+	projectPath := filepath.Join(cwd, ".databricks", "aitools", "skills")
+
+	globalLabel := "User global (" + globalPath + "/)\n    Available to you across all projects."
+	projectLabel := "Project (" + projectPath + "/)\n    Checked into the repo, shared with everyone on the project."
+
+	var scope string
+	err = huh.NewSelect[string]().
+		Title("Where should skills be installed?").
+		Options(
+			huh.NewOption(globalLabel, installer.ScopeGlobal),
+			huh.NewOption(projectLabel, installer.ScopeProject),
+		).
+		Value(&scope).
+		Run()
+	if err != nil {
+		return "", err
+	}
+
+	return scope, nil
+}

experimental/aitools/cmd/uninstall.go

@@ -9,6 +9,7 @@ import (
 
 func newUninstallCmd() *cobra.Command {
 	var skillsFlag string
+	var projectFlag, globalFlag bool
 
 	cmd := &cobra.Command{
 		Use:   "uninstall",
@@ -17,7 +18,14 @@ func newUninstallCmd() *cobra.Command {
 
 By default, removes all skills. Use --skills to remove specific skills only.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			opts := installer.UninstallOptions{}
+			scope, err := resolveScope(projectFlag, globalFlag)
+			if err != nil {
+				return err
+			}
+
+			opts := installer.UninstallOptions{
+				Scope: scope,
+			}
 			if skillsFlag != "" {
 				opts.Skills = strings.Split(skillsFlag, ",")
 			}
@@ -26,5 +34,7 @@ By default, removes all skills. Use --skills to remove specific skills only.`,
 	}
 
 	cmd.Flags().StringVar(&skillsFlag, "skills", "", "Specific skills to uninstall (comma-separated)")
+	cmd.Flags().BoolVar(&projectFlag, "project", false, "Uninstall project-scoped skills")
+	cmd.Flags().BoolVar(&globalFlag, "global", false, "Uninstall globally-scoped skills (default)")
 	return cmd
 }

experimental/aitools/cmd/update.go

@@ -12,6 +12,7 @@ import (
 func newUpdateCmd() *cobra.Command {
 	var check, force, noNew bool
 	var skillsFlag string
+	var projectFlag, globalFlag bool
 
 	cmd := &cobra.Command{
 		Use:   "update",
@@ -23,13 +24,20 @@ from the manifest. Use --no-new to skip new skills, or --check to
 preview what would change without downloading.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()
+
+			scope, err := resolveScope(projectFlag, globalFlag)
+			if err != nil {
+				return err
+			}
+
 			installed := agents.DetectInstalled(ctx)
 			src := &installer.GitHubManifestSource{}
 
 			opts := installer.UpdateOptions{
 				Check: check,
 				Force: force,
 				NoNew: noNew,
+				Scope: scope,
 			}
 			if skillsFlag != "" {
 				opts.Skills = strings.Split(skillsFlag, ",")
@@ -50,5 +58,7 @@ preview what would change without downloading.`,
 	cmd.Flags().BoolVar(&force, "force", false, "Re-download even if versions match")
 	cmd.Flags().BoolVar(&noNew, "no-new", false, "Don't auto-install new skills from manifest")
 	cmd.Flags().StringVar(&skillsFlag, "skills", "", "Specific skills to update (comma-separated)")
+	cmd.Flags().BoolVar(&projectFlag, "project", false, "Update project-scoped skills")
+	cmd.Flags().BoolVar(&globalFlag, "global", false, "Update globally-scoped skills (default)")
 	return cmd
 }