[common-skills migration] Add optional best-effort warp-skills install step

AGENTS.md

@@ -39,6 +39,7 @@ Environment variables:
 ### Platform Setup
 - `./script/bootstrap` - Platform-specific setup plus common agent skill installation from `skills-lock.json`; prompts for project/global when an install or update is needed unless a target flag or environment override is provided.
 - `./script/bootstrap --skip-common-skills` - Platform setup without installing or updating common agent skills.
+- `./script/bootstrap --skip-warp-skills` - Platform setup without installing the internal warp-skills (optional; internal-only, and a no-op without `warpdotdev/warp-skills` access).
 - `./script/bootstrap --install-common-skills` - Explicitly install common agent skills from `skills-lock.json`; this is the default behavior.
 - `./script/bootstrap --install-common-skills-in-repo` - Platform setup plus common agent skill installation in this checkout's `.agents/skills`.
 - `./script/bootstrap --install-common-skills-globally` - Platform setup plus common agent skill installation in `~/.agents/skills`.
@@ -52,6 +53,8 @@ Environment variables:
 
 `skills-lock.json` is the standard project lock file managed by `npx skills`. `warpdotdev/common-skills/scripts/install_common_skills` requires an explicit install target before restoring: pass `--project`, pass `--global`, set `WARP_COMMON_SKILLS_INSTALL_TARGET`, or answer the interactive prompt from bootstrap. Non-interactive flows fail if no target is explicit. The installer creates `skills-lock.json` from `warpdotdev/common-skills` if it is missing, uses global as the recommended interactive default, errors if common skills are present in both project and global locations, prevents a global install pinned to one lock from being silently overwritten by another checkout pinned to a different lock, and verifies installed skills against the lock after successful install or skip paths. `script/run` and `script/bootstrap` execute this installer with `script/resolve_common_skills`, which uses `WARP_COMMON_SKILLS_SCRIPTS_DIR` only when explicitly set and otherwise runs the raw script from `warpdotdev/common-skills`. To test a remote common-skills branch, set `WARP_COMMON_SKILLS_REF=<branch>`. Cloud setup should use `common-skills/scripts/install_common_skills --repo-root <warp-checkout> --project --if-needed --non-interactive` or set `WARP_COMMON_SKILLS_INSTALL_TARGET=project` to avoid the prompt. To update the locked common skills, run `npx --yes skills@1.5.6 update -p -y` and commit the resulting `skills-lock.json` changes.
 
+`warp-skills-lock.json` pins the internal `warpdotdev/warp-skills` skills (for example, the canonical `agent-attribution` skill referenced by the `*-local` companion skills). After the common-skills step, `script/bootstrap` and `script/run` optionally run `./script/resolve_common_skills install_warp_skills -- --repo-root "$PWD" --if-needed`, which restores the pinned skills from `warp-skills-lock.json` into the same target as the common skills (project unless `WARP_COMMON_SKILLS_INSTALL_TARGET=global`); the clone uses your local git auth (SSH or the `gh` credential helper). This step is optional and best-effort: it is a no-op when `warp-skills-lock.json` is absent, and on any failure (for example, an external contributor without repo access) it prints a short notice and exits 0 without failing bootstrap or run. Skip it with `--skip-warp-skills` or `WARP_SKIP_WARP_SKILLS_INSTALL=1`. It is internal-only: external contributors lack access to `warpdotdev/warp-skills`, so it no-ops for them. To update the pinned skills, regenerate `warp-skills-lock.json` (for example, `update_common_skills_lock --source warpdotdev/warp-skills --lock-file warp-skills-lock.json`) and commit the result.
+
 ## Architecture Overview
 
 This is a Rust-based terminal emulator with a custom UI framework called **WarpUI**.

CONTRIBUTING.md

@@ -102,6 +102,8 @@ The spec-writing skills are sourced from [`warpdotdev/common-skills`](https://gi
 - `WARP_COMMON_SKILLS_INSTALL_TARGET=project ./script/bootstrap` and `WARP_COMMON_SKILLS_INSTALL_TARGET=global ./script/bootstrap` select the same targets non-interactively.
 - `./script/bootstrap --skip-common-skills` leaves common skills untouched if you are managing them separately.
 
+Warp also maintains a small set of internal skills in [`warpdotdev/warp-skills`](https://github.com/warpdotdev/warp-skills), pinned in [`warp-skills-lock.json`](warp-skills-lock.json). After the common-skills step, `./script/bootstrap` and `./script/run` optionally run `./script/resolve_common_skills install_warp_skills` to restore them into the same target as the common skills. This step is **internal-only**: it needs access to `warpdotdev/warp-skills`, which external contributors don't have, so for them it is a best-effort no-op. You can skip it explicitly with `./script/bootstrap --skip-warp-skills` or `WARP_SKIP_WARP_SKILLS_INSTALL=1`.
+
 To open a spec PR:
 
 1. Add `specs/GH<issue-number>/product.md` and `specs/GH<issue-number>/tech.md`. See [`specs/GH408/`](specs/GH408/), [`specs/GH1063/`](specs/GH1063/), and [`specs/GH1066/`](specs/GH1066/) for examples of well-structured specs, and browse the rest of [`specs/`](specs/) for more. After common skills are installed, the `/write-product-spec` and `/write-tech-spec` skills are available to scaffold these for you.

script/bootstrap

@@ -9,6 +9,7 @@ set -eo pipefail
 OS_TYPE="$(uname -s)"
 REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")"/.. && pwd)"
 INSTALL_COMMON_SKILLS=1
+INSTALL_WARP_SKILLS=1
 COMMON_SKILLS_TARGET="${WARP_COMMON_SKILLS_INSTALL_TARGET:-}"
 PLATFORM_ARGS=()
 
@@ -28,10 +29,13 @@ Options:
   --install-common-skills-globally
                             Install or update common agent skills in ~/.agents/skills.
   --skip-common-skills     Skip installing common agent skills.
+  --skip-warp-skills       Skip installing team-specific warp-skills.
 
 Environment:
   WARP_SKIP_COMMON_SKILLS_INSTALL=1
       Skip installing common agent skills, even when --install-common-skills is provided.
+  WARP_SKIP_WARP_SKILLS_INSTALL=1
+      Skip installing team-specific warp-skills.
   WARP_COMMON_SKILLS_INSTALL_TARGET=project|global
       Choose the install target when no explicit prompt answer is provided.
       Target prompting and duplicate checks are delegated to
@@ -75,6 +79,13 @@ print_bootstrap_preview() {
   if [[ "${INSTALL_COMMON_SKILLS}" -eq 1 && "${WARP_SKIP_COMMON_SKILLS_INSTALL:-}" != "1" ]]; then
     echo "  - Verify installed common skills match skills-lock.json."
   fi
+  if [[ "${INSTALL_WARP_SKILLS}" -eq 0 ]]; then
+    echo "  - Skip the internal warp-skills because --skip-warp-skills was provided."
+  elif [[ "${WARP_SKIP_WARP_SKILLS_INSTALL:-}" = "1" ]]; then
+    echo "  - Skip the internal warp-skills because WARP_SKIP_WARP_SKILLS_INSTALL=1."
+  else
+    echo "  - Install the internal warp-skills pinned in warp-skills-lock.json if accessible (best-effort; optional)."
+  fi
   echo "Run ./script/bootstrap --help to see options and environment overrides."
   echo
 }
@@ -106,6 +117,9 @@ for arg in "$@"; do
     --skip-common-skills)
       INSTALL_COMMON_SKILLS=0
       ;;
+    --skip-warp-skills)
+      INSTALL_WARP_SKILLS=0
+      ;;
     *)
       PLATFORM_ARGS+=("${arg}")
       ;;
@@ -131,6 +145,21 @@ maybe_install_common_skills() {
   fi
 }
 
+# Optionally install the internal warp-skills after the common-skills step, via
+# the shared install_warp_skills wrapper resolved from warpdotdev/common-skills.
+# Best-effort: a missing lock or no access is a clean no-op. Surface a warning on
+# any unexpected failure, but never abort bootstrap.
+maybe_install_warp_skills() {
+  if [[ "${INSTALL_WARP_SKILLS}" -eq 1 ]]; then
+    if [[ "${WARP_SKIP_WARP_SKILLS_INSTALL:-}" = "1" ]]; then
+      return
+    fi
+    if ! ./script/resolve_common_skills install_warp_skills -- --repo-root "${REPO_ROOT}" --if-needed; then
+      echo "warning: warp-skills install did not complete; continuing without it." >&2
+    fi
+  fi
+}
+
 # This repository requires Git LFS; ensure it is installed and initialized
 # for this checkout.
 ensure_git_lfs() {
@@ -156,11 +185,15 @@ if [[ "$OS_TYPE" = "Darwin" ]]; then
   print_bootstrap_preview "macOS"
   ./script/macos/bootstrap "${PLATFORM_ARGS[@]}"
   maybe_install_common_skills
+  maybe_install_warp_skills
 elif [[ "$OS_TYPE" = "Linux" ]]; then
   print_bootstrap_preview "Linux"
   ./script/linux/bootstrap "${PLATFORM_ARGS[@]}"
   maybe_install_common_skills
+  maybe_install_warp_skills
 elif [[ "$OS_TYPE" =~ ^(MINGW64_NT|MSYS_NT) ]]; then
+  # The Windows bootstrap runs through bootstrap.ps1, which installs common
+  # skills but does not yet wire up the internal warp-skills step.
   if [[ "${INSTALL_COMMON_SKILLS}" -eq 1 ]]; then
     if [[ -n "${COMMON_SKILLS_TARGET}" ]]; then
       ./script/windows/bootstrap.ps1 "${PLATFORM_ARGS[@]}" -InstallCommonSkills -CommonSkillsTarget "${COMMON_SKILLS_TARGET}"

script/run

@@ -21,6 +21,7 @@ OS_TYPE="$(uname -s)"
 FEATURES="gui"
 INSTALL_COMMON_SKILLS=1
 FORCE_COMMON_SKILLS=0
+INSTALL_WARP_SKILLS=1
 COMMON_SKILLS_TARGET="${WARP_COMMON_SKILLS_INSTALL_TARGET:-}"
 
 ./script/install_channel_config || echo "Skipping internal channel config installation (no repo access)."
@@ -71,6 +72,10 @@ while (( "$#" )); do
       FORCE_COMMON_SKILLS=1
       shift
       ;;
+    --skip-warp-skills)
+      INSTALL_WARP_SKILLS=0
+      shift
+      ;;
     --release)
       CARGO_PARAMS+=("$1")
       MAC_ARGS+=("$1")
@@ -122,6 +127,16 @@ if [[ "$INSTALL_COMMON_SKILLS" -eq 1 ]]; then
   fi
 fi
 
+# Optionally install the internal warp-skills after the common-skills step, via
+# the shared install_warp_skills wrapper resolved from warpdotdev/common-skills.
+# Best-effort: a missing lock or no access is a clean no-op. Surface a warning on
+# any unexpected failure, but never abort run.
+if [[ "${INSTALL_WARP_SKILLS}" -eq 1 && "${WARP_SKIP_WARP_SKILLS_INSTALL:-}" != "1" ]]; then
+  if ! ./script/resolve_common_skills install_warp_skills -- --repo-root "${REPO_ROOT}" --if-needed; then
+    echo "warning: warp-skills install did not complete; continuing without it." >&2
+  fi
+fi
+
 # These cargo features were removed and replaced by environment variables read
 # by warp-channel-config. Intercept them here so that existing --features
 # invocations keep working.

warp-skills-lock.json

@@ -0,0 +1,26 @@
+{
+  "version": 1,
+  "skills": {
+    "agent-attribution": {
+      "source": "warpdotdev/warp-skills",
+      "ref": "main",
+      "sourceType": "github",
+      "skillPath": ".agents/skills/agent-attribution/SKILL.md",
+      "computedHash": "814d656e0df26da1644cb629c09358de99d88eb1905a01107ed21724196b2ec6"
+    },
+    "brandalf": {
+      "source": "warpdotdev/warp-skills",
+      "ref": "main",
+      "sourceType": "github",
+      "skillPath": ".agents/skills/brandalf/SKILL.md",
+      "computedHash": "44eccce975aeb4df325f0112602d4e3181c80cf7febe659367c524a18dd61da9"
+    },
+    "pr-walkthrough-local": {
+      "source": "warpdotdev/warp-skills",
+      "ref": "main",
+      "sourceType": "github",
+      "skillPath": ".agents/skills/pr-walkthrough-local/SKILL.md",
+      "computedHash": "fc14030fe49a236815d2a54835bdd2c7d96b7aaf7f277fcb69b0aa9d44b31e60"
+    }
+  }
+}