[5/5] Aitools: project scope (--project/--global) (#4814)

## PR Stack

1. [1/5] State + release discovery + directory rename (#4810)
2. [2/5] Install writes state + interactive agent selection (#4811)
3. [3/5] Update + uninstall + version commands (#4812)
4. [4/5] List improvements + command restructuring + flags (#4813)
5. **[5/5] Project scope (--project/--global)** (this PR)

Manifest v2 PR: databricks/databricks-agent-skills#35

**Base**: `simonfaltum/aitools-pr4-restructure` (PR 4)

## Why

Skills are currently global-only. Teams working on the same project
can't share a curated set of skills via their repo. Project-scoped
installation puts skills alongside the code, so they can be committed to
git and shared.

## Changes

Before: All skills install to `~/.databricks/aitools/skills/` (global
only).

Now:
- `--project` flag on install, update, uninstall: operates on
`<cwd>/.databricks/aitools/skills/`
- `--global` flag: explicit global scope (default behavior)
- `--global` + `--project` -> error
- Interactive scope prompt on install (default: global). Uses
`huh.NewSelect` in cmd layer.
- Non-interactive defaults to global.
- `SupportsProjectScope` field on `Agent` struct. Only Claude Code and
Cursor support project scope.
- Incompatible agents get a warning, not an error: "Skipped <agent>:
does not support project-scoped skills."
- Version shows both scopes when both exist.
- State includes `scope: "project"` field for project installs.

## Test plan

- [x] `--project` installs to cwd-relative directory
- [x] `--global` + `--project` -> error
- [x] No flag, interactive -> scope prompt shown, default is global
- [x] No flag, non-interactive -> global (no prompt)
- [x] Incompatible agents warned, not errored
- [x] Symlinks only created for capable agents in project scope
- [x] Version shows both scopes when both exist
- [x] `SupportsProjectScope` set correctly for all 6 agents
- [x] All lint checks pass

Author: simonfaltum

experimental/aitools/cmd/install.go

@@ -16,13 +16,15 @@ 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.
 
@@ -31,10 +33,15 @@ Supported agents: Claude Code, Cursor, Codex CLI, OpenCode, GitHub Copilot, Anti
 		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
@@ -46,11 +53,18 @@ Supported agents: Claude Code, Cursor, Codex CLI, OpenCode, GitHub Copilot, Anti
 					return nil
 				}
 
+				// For project scope, pre-filter to compatible agents before prompting.
+				if scope == installer.ScopeProject {
+					detected = filterProjectScopeAgents(detected)
+					if len(detected) == 0 {
+						return errors.New("no detected agents support project-scoped skills")
+					}
+				}
+
 				switch {
 				case len(detected) == 1:
 					targetAgents = detected
 				case cmdio.IsPromptSupported(ctx):
-					var err error
 					targetAgents, err = promptAgentSelection(ctx, detected)
 					if err != nil {
 						return err
@@ -63,6 +77,7 @@ Supported agents: Claude Code, Cursor, Codex CLI, OpenCode, GitHub Copilot, Anti
 			// Build install options.
 			opts := installer.InstallOptions{
 				IncludeExperimental: includeExperimental,
+				Scope:               scope,
 			}
 			opts.SpecificSkills = splitAndTrim(skillsFlag)
 
@@ -76,6 +91,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, "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
 }
 
@@ -111,6 +128,17 @@ func resolveAgentNames(ctx context.Context, names string) ([]*agents.Agent, erro
 	return result, nil
 }
 
+// filterProjectScopeAgents returns only agents that support project-scoped skills.
+func filterProjectScopeAgents(detected []*agents.Agent) []*agents.Agent {
+	var compatible []*agents.Agent
+	for _, a := range detected {
+		if a.SupportsProjectScope {
+			compatible = append(compatible, a)
+		}
+	}
+	return compatible
+}
+
 // printNoAgentsMessage prints the "no agents detected" message.
 func printNoAgentsMessage(ctx context.Context) {
 	cmdio.LogString(ctx, color.YellowString("No supported coding agents detected."))

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 })
@@ -436,3 +450,134 @@ func TestResolveAgentNamesDuplicatesDeduplicates(t *testing.T) {
 	assert.Len(t, result, 1, "duplicate agent names should be deduplicated")
 	assert.Equal(t, "claude-code", result[0].Name)
 }
+
+// --- 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)
+			}
+		})
+	}
+}