# Common Skills Installation — Tech Spec

## Context
This PR replaces the custom `.agents/common-skills.lock` flow with the standard project lock managed by `npx skills`. The checked-in `skills-lock.json` records each common skill from `warpdotdev/common-skills`, including its source, skill path, and content hash (`skills-lock.json:1`). Installed skill copies are local developer state: they may live in the checkout's project-local skills directory or in the user's global agent skills directory, but they are not source-controlled. For project-local installs, the installer ignores only the locked common-skill paths so unrelated project skills in `.agents/skills` remain visible to Git.

The main install entrypoint is `warpdotdev/common-skills/scripts/install_common_skills`. It targets a Warp checkout through `--repo-root <warp-checkout>` or `WARP_COMMON_SKILLS_TARGET_REPO_ROOT`, points at that checkout's `skills-lock.json`, and installs into an explicit target selected by `--project`, `--global`, `WARP_COMMON_SKILLS_INSTALL_TARGET`, or an interactive prompt. If the lock is missing during a normal install, the script creates it by installing the standard common skill set from `warpdotdev/common-skills` with the pinned `skills` CLI. When `WARP_COMMON_SKILLS_REF=<git-ref>` is set, missing-lock creation uses `warpdotdev/common-skills#<git-ref>`. If the lock exists during an interactive normal install, the script checks whether adding the selected common-skills source in a temporary directory would produce a different lock and, when it would, prompts the developer before changing `skills-lock.json`. If the lock is missing during `--verify-only`, the script fails immediately without prompting or creating files.

The script hashes `skills-lock.json` and records target-local install metadata after a successful restore. Project-local installs use checkout-local metadata under `.git` so normal restore runs do not create tracked files. Global installs use global target metadata so different client repositories can verify whether the shared global install is pinned to the same lock. If a global install already matches the requested lock, setup verifies and succeeds. If it is pinned to a different lock, setup fails with an actionable version-mismatch error instead of silently overwriting the shared global copy. Successful install and skip paths verify that exactly one target contains common skills and that installed contents match `skills-lock.json`.

`script/run` checks common skills before launching a local build. It enables the check by default and executes the installer through `script/resolve_common_skills`, which uses the raw script from `warpdotdev/common-skills` unless the developer explicitly sets `WARP_COMMON_SKILLS_SCRIPTS_DIR` to a local common-skills checkout or worktree. `WARP_COMMON_SKILLS_REF=<branch>` selects a non-main common-skills ref for the remote script path and is inherited by the installer as the common-skills source ref for missing-lock creation and interactive update checks. `script/run` then calls `warpdotdev/common-skills/scripts/install_common_skills --repo-root <warp-checkout> --if-needed --prompt-for-target --quiet` when no explicit target was provided, or passes `--project`/`--global` when `WARP_COMMON_SKILLS_INSTALL_TARGET` selected a target. `--install-common-skills` forces a restore using the same target-resolution behavior. `script/bootstrap` also installs common skills by default and delegates target resolution to the same installer, allowing the installer to prompt first for an upstream lock update and then for the install target when those choices are needed. `WARP.md` documents the standard update command and the files reviewers should expect to change.

## Diagrams
### Local agent installation and update flow
```mermaid
flowchart TD
  A["warpdotdev/warp checkout"] --> B["skills-lock.json"]
  A --> C["Selected install target"]
  C --> C1["Project-local .agents/skills/*"]
  C --> C2["Global ~/.agents/skills/*"]

  B --> D["script/run"]
  D --> E["common-skills/scripts/install_common_skills --repo-root <warp-checkout> --if-needed --quiet"]
  E --> F["Hash skills-lock.json"]
  F --> G{"Does target metadata match?"}

  G -->|Yes| H["Skip restore"]
  H --> I["Continue local build/run"]

  G -->|No| J["npx --yes skills@1.5.6 experimental_install"]
  J --> K["Read skills-lock.json"]
  K --> L["Fetch locked skills from warpdotdev/common-skills"]
  L --> M["Restore selected install target"]
  M --> N["Write target-local lock metadata"]
  N --> I

  O["Developer updates common skills"] --> P["npx --yes skills@1.5.6 update -p -y"]
  P --> Q["Update skills-lock.json hashes"]
  Q --> S["Commit lock change"]
  S --> A
```

### Global target compatibility flow
```mermaid
flowchart TD
  A["Client repo selects global install"] --> B["Read repo skills-lock.json"]
  B --> C{"Does global target contain common skills?"}
  C -->|No| D["Install locked common skills globally"]
  C -->|Yes| E{"Does global metadata match repo lock?"}
  E -->|Yes| F["Verify installed contents"]
  F --> G["Succeed without reinstalling"]
  E -->|No| H["Fail with version-mismatch error"]
  H --> I["Developer explicitly reconciles, updates, or removes/reinstalls global skills"]
```

## Proposed changes
The implementation should keep `skills-lock.json` as the single source of truth for common skills installed from `warpdotdev/common-skills`. The repo should not maintain a second custom lock format or a separate GitHub workflow for scheduled common-skill updates.

`warpdotdev/common-skills/scripts/install_common_skills` owns lock creation and restoration from the lock for a target checkout. It should remain small and deterministic: if `skills-lock.json` is missing during a normal install, create it from the pinned common-skill source; otherwise compute a hash for `skills-lock.json`, compare it with target-local metadata, run `npx --yes skills@1.5.6 experimental_install` only when needed and allowed, and update the metadata after a successful restore. Project-local metadata belongs under the target checkout's `.git` so normal restore runs do not create or modify tracked files unless the lock itself has been updated intentionally. Global metadata belongs with the global install target so multiple client repos can detect whether they are pinned to the same common-skills lock.

`warpdotdev/common-skills/scripts/install_common_skills` should own install target resolution, but target selection must be explicit. The installer accepts `--project`, `--global`, or `WARP_COMMON_SKILLS_INSTALL_TARGET`; if none is provided in an interactive invocation, it prompts with global as the recommended default. If none is provided in a non-interactive invocation, it fails with an actionable error. It must not infer the target from an existing project-local or global install. It should also fail when both targets contain common skills, suggesting `remove_common_skills --repo-root <warp-checkout>` for the project-local copy or `remove_common_skills --repo-root <warp-checkout> --global` for the global copy.

For interactive normal install flows with an existing lock, `install_common_skills` should compute a candidate updated lock in a temporary directory before resolving the install target. The candidate is generated by adding `warpdotdev/common-skills`, or `warpdotdev/common-skills#<git-ref>` when `WARP_COMMON_SKILLS_REF` is set, with the pinned `skills` CLI. If the candidate lock differs from the checkout's `skills-lock.json`, the script should print that common skills have been updated in the selected source and ask whether to update the checkout lock and reinstall. Accepting copies the candidate lock into the checkout, marks the flow as an explicit lock update, and continues to target resolution and install. Declining discards the candidate and continues from the existing lock. Non-interactive and verify-only flows skip this upstream check entirely.

`script/run` should call the installer before building so local developer runs validate lock changes automatically. This makes `script/run` the dependency-update check point requested during review: when a branch changes `skills-lock.json`, the next run restores the matching project-local target or compatible global target without requiring a separate workflow. If no target was provided, run should use the same interactive target prompt as bootstrap; if no prompt is available, the installer should fail with the same actionable target-selection error. If the global target is pinned to a different lock, run should fail before launching Warp. `--install-common-skills` is retained as a force-install escape hatch, subject to the same target-resolution behavior and global version-mismatch guard.

`script/bootstrap` should delegate to the same installer by default, while retaining `--skip-common-skills` as an opt-out. If bootstrap needs to install or update common skills and no target was explicitly provided, it should ask the user whether to install project-local or globally. This keeps platform setup and normal run setup consistent while avoiding surprising writes.

`script/resolve_common_skills` should default to executing the remote raw script from `warpdotdev/common-skills`. Local common-skills checkouts or worktrees are used only when `WARP_COMMON_SKILLS_SCRIPTS_DIR` is set. `WARP_COMMON_SKILLS_REF` selects the remote branch, tag, or commit to fetch and is also consumed by `install_common_skills` when selecting the common-skills source for missing-lock creation and interactive update checks. Because the remote script is executed through a pipe, installer child commands that might read stdin should redirect from `/dev/null` so they cannot consume the remaining script body before the restore and verification steps run. No separate `WARP_COMMON_SKILLS_FORCE_REMOTE` option is needed because remote execution is already the default.

Updates to common skills should be explicit developer actions: accept the interactive bootstrap/install prompt or run `npx --yes skills@1.5.6 update -p -y`, review the generated `skills-lock.json` changes, and commit them. This preserves dependency-review semantics without adding repository-specific scheduled automation.

## Testing and validation
Validate the shell changes with `bash -n <common-skills>/scripts/install_common_skills <common-skills>/scripts/remove_common_skills script/resolve_common_skills script/run script/bootstrap`.

Validate the Windows bootstrap script parses with PowerShell: `pwsh -NoProfile -Command '$null = [scriptblock]::Create((Get-Content -Raw "script/windows/bootstrap.ps1"))'`.

Validate the missing-lock path by removing common skills and the lock, then running `<common-skills>/scripts/install_common_skills --repo-root <warp-checkout> --project --if-needed --non-interactive`. It should run the pinned `skills@1.5.6 add warpdotdev/common-skills` command, create `skills-lock.json`, restore the selected project-local target, and write project-local metadata.

Validate the restore path by running `<common-skills>/scripts/install_common_skills --repo-root <warp-checkout> --project --if-needed --quiet` from a checkout without matching project-local metadata but with an existing lock. It should run the pinned `skills@1.5.6` restore command, restore the selected project-local target, and write project-local metadata.

Validate the skip path by running `<common-skills>/scripts/install_common_skills --repo-root <warp-checkout> --project --if-needed --quiet` again. It should exit successfully without output and without changing the worktree.

Validate global sharing by installing common skills globally from two test checkouts with identical `skills-lock.json` contents. The second install should verify and succeed without unnecessarily reinstalling. Then change one checkout's lock and run global setup again; it should fail with the version-mismatch error rather than overwriting the shared global target.

Validate explicit target selection by running the installer in non-interactive mode without `--project`, `--global`, or `WARP_COMMON_SKILLS_INSTALL_TARGET`. It should fail with an actionable target-selection error and must not infer the target from existing installs.

Validate interactive update behavior by using a test checkout whose `skills-lock.json` differs from the current `warpdotdev/common-skills` output and running `<common-skills>/scripts/install_common_skills --repo-root <test-checkout> --if-needed --prompt-for-target`. Before the project/global prompt, the script should report that common skills have been updated and ask whether to update the lock. Accepting should change only `skills-lock.json` before target installation; declining should leave the lock unchanged and continue from the existing lock. Also validate `WARP_COMMON_SKILLS_REF=<branch>` with a branch whose skill content differs from the lock; the update prompt should compare against the branch source and the accepted lock should record that ref.

Validate manual update behavior by running `npx --yes skills@1.5.6 update -p -y` in a test checkout or intentional update branch. If upstream common skills changed, the diff should be limited to `skills-lock.json`.