feat(cli): squad install --machine-wide — ship /squad as a personal-scope skill so /squad init works in any folder #1310

Summary

Today, /squad (the skill registered by bradygaster/squad#1303) and the squad init / squad upgrade commands only work in a folder where Squad has already been installed — both because the slash command requires the skill to be present in the project's .github/skills/ directory and because the CLI bootstrap requires npx -y @bradygaster/squad-cli@insider (or a global install).

Goal: enable users to do /squad init (or /squad cast) from any folder, even before any Squad bootstrapping, by installing the squad skill machine-wide rather than per-repo.

Mechanic

Copilot CLI scans two skill scopes (per sdk/index.js v1.0.62, function getLoadedSkills):

1. Project scope — .github/skills/, .claude/skills/, .agents/skills/ in the current working directory. This is what squad init populates today.
2. Personal scope — ~/.copilot/skills/, ~/.agents/skills/ in the user's home directory. Loaded for every session regardless of cwd.

If the squad skill lives in personal scope, /squad works from any folder. The slash command is name-derived (with user-invocable: true per #1303), so it's the same /squad shape.

Proposed implementation

Path A — opt-in via squad install --machine-wide

New subcommand: squad install --machine-wide

What it does:

1. Resolve ~/.copilot/skills/ (create if missing).
2. Copy the squad skill from the installed @bradygaster/squad-cli package's templates/skills/squad/ into ~/.copilot/skills/squad/.
3. Also install squad-help for the disambiguation skill the coordinator reads on skill(Squad) mis-fires.
4. Print a one-line confirmation: ✅ squad skill installed machine-wide. /squad now works in any folder.

Idempotent. Refuses to overwrite an existing personal skill of the same name unless --force.

Path B — auto-install on npm i -g @bradygaster/squad-cli

Use the npm postinstall script in packages/squad-cli/package.json to call the same logic as Path A. Pros: zero user friction. Cons: surprising side-effect; some users dislike postinstall writes outside node_modules.

Recommendation: ship Path A first (explicit + safe). If user feedback says it's a chore, add Path B behind an opt-in env var (SQUAD_INSTALL_MACHINE_SKILL=1).

Path C — pure documentation (no code change)

Document the manual recipe:

$src = "$(npm root -g)\@bradygaster\squad-cli\templates\skills\squad"
$dst = "$env:USERPROFILE\.copilot\skills\squad"
New-Item -ItemType Directory -Path $dst -Force | Out-Null
Copy-Item "$src\*" $dst -Recurse -Force

Cheap but ugly. Use as fallback only.

Trade-offs to think about

• squad init from /squad: the skill's Menu Presentation Rules already include "init a new squad" as one of the commands it surfaces. Once machine-wide, /squad → user picks "init" → coordinator runs squad init in the current folder. That's the load-bearing UX.
• Skill version sync: a machine-wide skill goes stale as @bradygaster/squad-cli updates. Solution: squad install --machine-wide should be idempotent (re-running overwrites with current version). Document running it after every squad upgrade.
• Multi-user machines (devbox, shared dev VM): personal scope is per-user, so it Just Works for each developer.
• Cleanup: squad uninstall --machine-wide to remove. Symmetric.

Tests

• Smoke: install machine-wide, change to an empty git init'd folder, run copilot --agent squad -p "/squad init", verify init succeeds.
• Regression: ensure project-scope skills still take precedence over personal-scope ones (per Copilot CLI's documented dedup rule).

Filed by

Squad weekend stabilisation effort. Identified as a deferred follow-up because the v0.10 release ships the squad skill in project scope only.