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

[simonfaltum]

PR Stack

1. [1/5] State + release discovery + directory rename ([1/5] Aitools: state tracking, manifest source, directory rename #4810)
2. [2/5] Install writes state + interactive agent selection ([2/5] Aitools: install writes state, interactive agent selection, idempotent install #4811)
3. [3/5] Update + uninstall + version commands ([3/5] Aitools: update, uninstall, and version commands #4812)
4. [4/5] List improvements + command restructuring + flags ([4/5] Aitools: list command, flat structure, --skills/--agents/--include-experimental 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 : does not support project-scoped skills."
• Version shows both scopes when both exist.
• State includes scope: "project" field for project installs.

Test plan

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

[github-actions]

Suggested reviewers

Based on git history of the changed files, these people are best suited to review:

• @arsenyinfo -- recent work in experimental/aitools/cmd/, experimental/aitools/lib/installer/, experimental/aitools/lib/agents/

Confidence: high

Eligible reviewers

Based on CODEOWNERS, these people or teams could also review:

@databricks/eng-apps-devex, @lennartkats-db

_{Suggestions based on git history of 17 changed files (6 scored). See CODEOWNERS for path-specific ownership rules.}

[arsenyinfo]

More nitpicker comments that look legit to me:

Critical & Medium Priority Fixes

- Idempotency Failure (Scope-Unaware Check): The allAgentsHaveSkill function in installer.go hardcodes the global skills directory. During a --project install, the check looks in the wrong place, finds nothing, and triggers unnecessary re-downloads every time.
- *Action:* Update to use `agentSkillsDirForScope` and pass the relevant scope/CWD.
- Incorrect UI Labeling in list: Running list --project when no skills are installed incorrectly displays (global) in the summary.
- *Action:* Update `list.go` to respect the requested scope in the default switch case.
- Silent Update Failures: In UpdateSkills, if a user attempts to update project-scoped skills for agents that don't support them, the process proceeds silently without symlinking or warning.
- *Action:* Add a `len(targetAgents) == 0` check (similar to the install flow) to return an error/warning.
- Incompatible Agent Prompting (UX): The interactive install prompt displays all detected agents even if a user has already selected --project scope. While not a "crash" (as it is handled gracefully later), it leads to a poor user experience.
- *Action:* Pre-filter the agent list passed to the prompt based on the resolved scope.

[simonfaltum]

Good catches, all four are legit. Fixed in 0dab0e7:

1. Idempotency check: allAgentsHaveSkill now takes scope and cwd params and uses agentSkillsDirForScope instead of the hardcoded global dir.
2. List label: added a scope == ScopeProject case before the default so list --project with no state shows "(project)" not "(global)".
3. Update zero-agent guard: UpdateSkills now returns an error when all agents are incompatible with project scope, matching the install flow.
4. Agent prompt pre-filter: the install command pre-filters detected agents by SupportsProjectScope before showing the interactive prompt, so users don't see agents that'll get skipped anyway.

[eng-dev-ecosystem-bot]

Commit: a9c8a28

Run: 23585568387