From 06eaac6f303e636636379e56c45b85faa56fc896 Mon Sep 17 00:00:00 2001 From: vkodithala Date: Tue, 30 Jun 2026 19:45:38 +0000 Subject: [PATCH 1/6] Add optional best-effort warp-skills install step Add script/install_warp_skills to install the internal warpdotdev/warp-skills skills pinned in warp-skills-lock.json. It is wired optionally and best-effort into script/bootstrap and script/run after the common-skills step, skips on --skip-warp-skills or WARP_SKIP_WARP_SKILLS_INSTALL=1, no-ops without a lock file, and never fails its caller (e.g. external contributors without access). The common-skills install flow is left untouched. Document the optional step and opt-out in AGENTS.md and CONTRIBUTING.md, noting it is not required for external contributors. Co-Authored-By: Oz --- AGENTS.md | 3 ++ CONTRIBUTING.md | 2 ++ script/bootstrap | 25 +++++++++++++++ script/install_warp_skills | 63 ++++++++++++++++++++++++++++++++++++++ script/run | 12 ++++++++ warp-skills-lock.json | 26 ++++++++++++++++ 6 files changed, 131 insertions(+) create mode 100755 script/install_warp_skills create mode 100644 warp-skills-lock.json diff --git a/AGENTS.md b/AGENTS.md index 4c78ec4e762..a6479aa6adc 100644 --- a/AGENTS.md +++ b/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 step; not required for external contributors). - `./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=`. Cloud setup should use `common-skills/scripts/install_common_skills --repo-root --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/install_warp_skills`, which installs the pinned skills into the same target as the common skills via `npx --yes skills@1.5.6 add warpdotdev/warp-skills# --agent warp --skill '*' --yes --copy`; 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 not required for external contributors. To update the pinned skills, re-run the install command against `warpdotdev/warp-skills` and commit the regenerated `warp-skills-lock.json`. + ## Architecture Overview This is a Rust-based terminal emulator with a custom UI framework called **WarpUI**. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 25da1648af0..da64f24f565 100644 --- a/CONTRIBUTING.md +++ b/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/install_warp_skills` to restore them into the same target as the common skills. This step is **optional and not required for external contributors**: it is best-effort and a no-op if you lack access to that repository, and you can always skip it with `./script/bootstrap --skip-warp-skills` or `WARP_SKIP_WARP_SKILLS_INSTALL=1`. + To open a spec PR: 1. Add `specs/GH/product.md` and `specs/GH/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. diff --git a/script/bootstrap b/script/bootstrap index 1966f93900f..45df5fc0744 100755 --- a/script/bootstrap +++ b/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 the internal warp-skills (optional; not required for external contributors). 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 the internal 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,15 @@ maybe_install_common_skills() { fi } +# Optionally install the internal warp-skills after the common-skills step. +# install_warp_skills is best-effort and never fails, but guard with || true +# so an unexpected error can't abort bootstrap. +maybe_install_warp_skills() { + if [[ "${INSTALL_WARP_SKILLS}" -eq 1 ]]; then + ./script/install_warp_skills || true + fi +} + # This repository requires Git LFS; ensure it is installed and initialized # for this checkout. ensure_git_lfs() { @@ -156,10 +179,12 @@ 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 if [[ "${INSTALL_COMMON_SKILLS}" -eq 1 ]]; then if [[ -n "${COMMON_SKILLS_TARGET}" ]]; then diff --git a/script/install_warp_skills b/script/install_warp_skills new file mode 100755 index 00000000000..5702fb71e20 --- /dev/null +++ b/script/install_warp_skills @@ -0,0 +1,63 @@ +#!/usr/bin/env bash +# +# Best-effort installer for the internal warpdotdev/warp-skills skills pinned +# in warp-skills-lock.json. Invoked optionally from script/bootstrap and +# script/run after the common-skills step. It NEVER fails its caller: any +# problem (no lock file, no repo access, missing tooling) results in a single +# notice and exit 0. Not required for external contributors. + +set -uo pipefail + +REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")"/.. && pwd)" +LOCK_FILE="${REPO_ROOT}/warp-skills-lock.json" +SKILLS_CLI_VERSION="1.5.6" +SKILLS_REPO="warpdotdev/warp-skills" + +notice() { echo "warp-skills: $*"; } + +# Opt out via WARP_SKIP_WARP_SKILLS_INSTALL=1 or a --skip-warp-skills argument. +skip_requested=0 +if [[ "${WARP_SKIP_WARP_SKILLS_INSTALL:-}" = "1" ]]; then + skip_requested=1 +fi +for arg in "$@"; do + case "${arg}" in + --skip-warp-skills) skip_requested=1 ;; + esac +done +if [[ "${skip_requested}" -eq 1 ]]; then + notice "skipping install (opt-out requested)." + exit 0 +fi + +# Nothing to install without a committed lock file. +if [[ ! -f "${LOCK_FILE}" ]]; then + exit 0 +fi + +# Read the pinned ref recorded in the lock file (all entries share one ref). +pinned_ref="$(grep -o '"ref"[[:space:]]*:[[:space:]]*"[^"]*"' "${LOCK_FILE}" 2>/dev/null \ + | head -1 \ + | sed 's/.*"ref"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/')" + +source_spec="${SKILLS_REPO}" +if [[ -n "${pinned_ref}" ]]; then + source_spec="${SKILLS_REPO}#${pinned_ref}" +fi + +# Match the install target chosen for common skills (project by default). +target_args=() +if [[ "${WARP_COMMON_SKILLS_INSTALL_TARGET:-}" = "global" ]]; then + target_args=(--global) +fi + +# Clone uses the developer's git auth (SSH or the gh credential helper). +cd "${REPO_ROOT}" +if npx --yes "skills@${SKILLS_CLI_VERSION}" add "${source_spec}" \ + --agent warp --skill '*' --yes --copy "${target_args[@]}"; then + notice "installed pinned skills from ${source_spec}." +else + notice "not installed (no access) — skipping." +fi + +exit 0 diff --git a/script/run b/script/run index 059af5f5635..afd72b0708b 100755 --- a/script/run +++ b/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,13 @@ if [[ "$INSTALL_COMMON_SKILLS" -eq 1 ]]; then fi fi +# Optionally install the internal warp-skills after the common-skills step. +# Best-effort: install_warp_skills always exits 0; || true keeps set -e from +# aborting run on an unexpected failure. +if [[ "${INSTALL_WARP_SKILLS}" -eq 1 ]]; then + ./script/install_warp_skills || true +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. diff --git a/warp-skills-lock.json b/warp-skills-lock.json new file mode 100644 index 00000000000..3bad1a267ef --- /dev/null +++ b/warp-skills-lock.json @@ -0,0 +1,26 @@ +{ + "version": 1, + "skills": { + "agent-attribution": { + "source": "warpdotdev/warp-skills", + "ref": "oz/skills-migration", + "sourceType": "github", + "skillPath": ".agents/skills/agent-attribution/SKILL.md", + "computedHash": "814d656e0df26da1644cb629c09358de99d88eb1905a01107ed21724196b2ec6" + }, + "brandalf": { + "source": "warpdotdev/warp-skills", + "ref": "oz/skills-migration", + "sourceType": "github", + "skillPath": ".agents/skills/brandalf/SKILL.md", + "computedHash": "44eccce975aeb4df325f0112602d4e3181c80cf7febe659367c524a18dd61da9" + }, + "pr-walkthrough-local": { + "source": "warpdotdev/warp-skills", + "ref": "oz/skills-migration", + "sourceType": "github", + "skillPath": ".agents/skills/pr-walkthrough-local/SKILL.md", + "computedHash": "fc14030fe49a236815d2a54835bdd2c7d96b7aaf7f277fcb69b0aa9d44b31e60" + } + } +} From 91b848826d6584cec5ed6b9aefee0b72a556f132 Mon Sep 17 00:00:00 2001 From: vkodithala Date: Tue, 30 Jun 2026 19:57:03 +0000 Subject: [PATCH 2/6] install_warp_skills: avoid mutating repo skills-lock.json Run the skills CLI inside a throwaway temp dir and copy only the resulting skill directories into the target (.agents/skills or ~/.agents/skills), instead of running --copy from the repo root. Running from the repo root made the CLI write/merge its own skills-lock.json into the committed common-skills lock at runtime. The repo's skills-lock.json now stays clean. Co-Authored-By: Oz --- script/install_warp_skills | 36 ++++++++++++++++++++++++++++-------- 1 file changed, 28 insertions(+), 8 deletions(-) diff --git a/script/install_warp_skills b/script/install_warp_skills index 5702fb71e20..ef367bcb556 100755 --- a/script/install_warp_skills +++ b/script/install_warp_skills @@ -45,17 +45,37 @@ if [[ -n "${pinned_ref}" ]]; then source_spec="${SKILLS_REPO}#${pinned_ref}" fi -# Match the install target chosen for common skills (project by default). -target_args=() +# Install into the same target as the common skills (project by default). if [[ "${WARP_COMMON_SKILLS_INSTALL_TARGET:-}" = "global" ]]; then - target_args=(--global) + target_dir="${HOME}/.agents/skills" +else + target_dir="${REPO_ROOT}/.agents/skills" fi -# Clone uses the developer's git auth (SSH or the gh credential helper). -cd "${REPO_ROOT}" -if npx --yes "skills@${SKILLS_CLI_VERSION}" add "${source_spec}" \ - --agent warp --skill '*' --yes --copy "${target_args[@]}"; then - notice "installed pinned skills from ${source_spec}." +# Run the install inside a throwaway temp dir so the skills CLI's own +# skills-lock.json is never written into this repo (which would mutate the +# committed common-skills skills-lock.json), then copy only the resulting +# skill directories into the target. The clone uses the developer's git auth +# (SSH or the gh credential helper). +tmp_dir="$(mktemp -d "${TMPDIR:-/tmp}/warp-skills.XXXXXX")" +trap 'rm -rf "${tmp_dir}"' EXIT + +if ( cd "${tmp_dir}" && npx --yes "skills@${SKILLS_CLI_VERSION}" add "${source_spec}" \ + --agent warp --skill '*' --yes --copy ) && [[ -d "${tmp_dir}/.agents/skills" ]]; then + mkdir -p "${target_dir}" + installed=0 + for skill_dir in "${tmp_dir}"/.agents/skills/*/; do + [[ -d "${skill_dir}" ]] || continue + skill_name="$(basename "${skill_dir}")" + rm -rf "${target_dir:?}/${skill_name}" + cp -R "${skill_dir%/}" "${target_dir}/${skill_name}" + installed=1 + done + if [[ "${installed}" -eq 1 ]]; then + notice "installed pinned skills from ${source_spec} into ${target_dir}." + else + notice "not installed (no skills found) — skipping." + fi else notice "not installed (no access) — skipping." fi From 08f0a6d7d7ed68d444c0c9df9eda1166a2ee7aa8 Mon Sep 17 00:00:00 2001 From: vkodithala Date: Tue, 30 Jun 2026 22:47:49 +0000 Subject: [PATCH 3/6] Pin warp-skills-lock.json to warpdotdev/warp-skills#main Pin the consumer lock to main (canonical) to match warp-server. main is empty until warp-skills #1 merges, so the optional install step cleanly no-ops until then; the common-skills downstream lock-automation refreshes it afterward. Co-Authored-By: Oz --- warp-skills-lock.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/warp-skills-lock.json b/warp-skills-lock.json index 3bad1a267ef..47ceefc33f9 100644 --- a/warp-skills-lock.json +++ b/warp-skills-lock.json @@ -3,21 +3,21 @@ "skills": { "agent-attribution": { "source": "warpdotdev/warp-skills", - "ref": "oz/skills-migration", + "ref": "main", "sourceType": "github", "skillPath": ".agents/skills/agent-attribution/SKILL.md", "computedHash": "814d656e0df26da1644cb629c09358de99d88eb1905a01107ed21724196b2ec6" }, "brandalf": { "source": "warpdotdev/warp-skills", - "ref": "oz/skills-migration", + "ref": "main", "sourceType": "github", "skillPath": ".agents/skills/brandalf/SKILL.md", "computedHash": "44eccce975aeb4df325f0112602d4e3181c80cf7febe659367c524a18dd61da9" }, "pr-walkthrough-local": { "source": "warpdotdev/warp-skills", - "ref": "oz/skills-migration", + "ref": "main", "sourceType": "github", "skillPath": ".agents/skills/pr-walkthrough-local/SKILL.md", "computedHash": "fc14030fe49a236815d2a54835bdd2c7d96b7aaf7f277fcb69b0aa9d44b31e60" From ec92b6e357e62546126e48620eb74b421843d5e4 Mon Sep 17 00:00:00 2001 From: vkodithala Date: Wed, 1 Jul 2026 15:35:42 -0400 Subject: [PATCH 4/6] Use shared install_warp_skills wrapper instead of vendored script Delete the vendored script/install_warp_skills and instead call the shared wrapper via ./script/resolve_common_skills install_warp_skills, resolved from warpdotdev/common-skills. bootstrap and run keep the best-effort || true guard and the --skip-warp-skills / WARP_SKIP_WARP_SKILLS_INSTALL gating. Update AGENTS.md and CONTRIBUTING.md accordingly. Co-Authored-By: Oz --- AGENTS.md | 2 +- CONTRIBUTING.md | 2 +- script/bootstrap | 13 +++--- script/install_warp_skills | 83 -------------------------------------- script/run | 9 +++-- 5 files changed, 14 insertions(+), 95 deletions(-) delete mode 100755 script/install_warp_skills diff --git a/AGENTS.md b/AGENTS.md index a6479aa6adc..fa5c7bf233c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -53,7 +53,7 @@ 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=`. Cloud setup should use `common-skills/scripts/install_common_skills --repo-root --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/install_warp_skills`, which installs the pinned skills into the same target as the common skills via `npx --yes skills@1.5.6 add warpdotdev/warp-skills# --agent warp --skill '*' --yes --copy`; 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 not required for external contributors. To update the pinned skills, re-run the install command against `warpdotdev/warp-skills` and commit the regenerated `warp-skills-lock.json`. +`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 not required for external contributors. 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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index da64f24f565..0694ddca8c2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -102,7 +102,7 @@ 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/install_warp_skills` to restore them into the same target as the common skills. This step is **optional and not required for external contributors**: it is best-effort and a no-op if you lack access to that repository, and you can always skip it with `./script/bootstrap --skip-warp-skills` or `WARP_SKIP_WARP_SKILLS_INSTALL=1`. +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 **optional and not required for external contributors**: it is best-effort and a no-op if you lack access to that repository, and you can always skip it with `./script/bootstrap --skip-warp-skills` or `WARP_SKIP_WARP_SKILLS_INSTALL=1`. To open a spec PR: diff --git a/script/bootstrap b/script/bootstrap index 45df5fc0744..e6624f77dcd 100755 --- a/script/bootstrap +++ b/script/bootstrap @@ -29,13 +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 the internal warp-skills (optional; not required for external contributors). + --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 the internal warp-skills. + 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 @@ -145,12 +145,13 @@ maybe_install_common_skills() { fi } -# Optionally install the internal warp-skills after the common-skills step. -# install_warp_skills is best-effort and never fails, but guard with || true -# so an unexpected error can't abort bootstrap. +# Optionally install the internal warp-skills after the common-skills step, via +# the shared install_warp_skills wrapper resolved from warpdotdev/common-skills. +# It is best-effort and never fails, but guard with || true so an unexpected +# error can't abort bootstrap. maybe_install_warp_skills() { if [[ "${INSTALL_WARP_SKILLS}" -eq 1 ]]; then - ./script/install_warp_skills || true + ./script/resolve_common_skills install_warp_skills -- --repo-root "${REPO_ROOT}" --if-needed || true fi } diff --git a/script/install_warp_skills b/script/install_warp_skills deleted file mode 100755 index ef367bcb556..00000000000 --- a/script/install_warp_skills +++ /dev/null @@ -1,83 +0,0 @@ -#!/usr/bin/env bash -# -# Best-effort installer for the internal warpdotdev/warp-skills skills pinned -# in warp-skills-lock.json. Invoked optionally from script/bootstrap and -# script/run after the common-skills step. It NEVER fails its caller: any -# problem (no lock file, no repo access, missing tooling) results in a single -# notice and exit 0. Not required for external contributors. - -set -uo pipefail - -REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")"/.. && pwd)" -LOCK_FILE="${REPO_ROOT}/warp-skills-lock.json" -SKILLS_CLI_VERSION="1.5.6" -SKILLS_REPO="warpdotdev/warp-skills" - -notice() { echo "warp-skills: $*"; } - -# Opt out via WARP_SKIP_WARP_SKILLS_INSTALL=1 or a --skip-warp-skills argument. -skip_requested=0 -if [[ "${WARP_SKIP_WARP_SKILLS_INSTALL:-}" = "1" ]]; then - skip_requested=1 -fi -for arg in "$@"; do - case "${arg}" in - --skip-warp-skills) skip_requested=1 ;; - esac -done -if [[ "${skip_requested}" -eq 1 ]]; then - notice "skipping install (opt-out requested)." - exit 0 -fi - -# Nothing to install without a committed lock file. -if [[ ! -f "${LOCK_FILE}" ]]; then - exit 0 -fi - -# Read the pinned ref recorded in the lock file (all entries share one ref). -pinned_ref="$(grep -o '"ref"[[:space:]]*:[[:space:]]*"[^"]*"' "${LOCK_FILE}" 2>/dev/null \ - | head -1 \ - | sed 's/.*"ref"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/')" - -source_spec="${SKILLS_REPO}" -if [[ -n "${pinned_ref}" ]]; then - source_spec="${SKILLS_REPO}#${pinned_ref}" -fi - -# Install into the same target as the common skills (project by default). -if [[ "${WARP_COMMON_SKILLS_INSTALL_TARGET:-}" = "global" ]]; then - target_dir="${HOME}/.agents/skills" -else - target_dir="${REPO_ROOT}/.agents/skills" -fi - -# Run the install inside a throwaway temp dir so the skills CLI's own -# skills-lock.json is never written into this repo (which would mutate the -# committed common-skills skills-lock.json), then copy only the resulting -# skill directories into the target. The clone uses the developer's git auth -# (SSH or the gh credential helper). -tmp_dir="$(mktemp -d "${TMPDIR:-/tmp}/warp-skills.XXXXXX")" -trap 'rm -rf "${tmp_dir}"' EXIT - -if ( cd "${tmp_dir}" && npx --yes "skills@${SKILLS_CLI_VERSION}" add "${source_spec}" \ - --agent warp --skill '*' --yes --copy ) && [[ -d "${tmp_dir}/.agents/skills" ]]; then - mkdir -p "${target_dir}" - installed=0 - for skill_dir in "${tmp_dir}"/.agents/skills/*/; do - [[ -d "${skill_dir}" ]] || continue - skill_name="$(basename "${skill_dir}")" - rm -rf "${target_dir:?}/${skill_name}" - cp -R "${skill_dir%/}" "${target_dir}/${skill_name}" - installed=1 - done - if [[ "${installed}" -eq 1 ]]; then - notice "installed pinned skills from ${source_spec} into ${target_dir}." - else - notice "not installed (no skills found) — skipping." - fi -else - notice "not installed (no access) — skipping." -fi - -exit 0 diff --git a/script/run b/script/run index afd72b0708b..0137d38771b 100755 --- a/script/run +++ b/script/run @@ -127,11 +127,12 @@ if [[ "$INSTALL_COMMON_SKILLS" -eq 1 ]]; then fi fi -# Optionally install the internal warp-skills after the common-skills step. -# Best-effort: install_warp_skills always exits 0; || true keeps set -e from -# aborting run on an unexpected failure. +# 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: it always exits 0; || true keeps set -e from aborting run on an +# unexpected failure. if [[ "${INSTALL_WARP_SKILLS}" -eq 1 ]]; then - ./script/install_warp_skills || true + ./script/resolve_common_skills install_warp_skills -- --repo-root "${REPO_ROOT}" --if-needed || true fi # These cargo features were removed and replaced by environment variables read From f365aa2426d412f8a088863c67947f522ff0c005 Mon Sep 17 00:00:00 2001 From: vkodithala Date: Thu, 2 Jul 2026 16:18:42 -0400 Subject: [PATCH 5/6] Address review feedback on warp-skills install step MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Clarify docs (CONTRIBUTING.md, AGENTS.md): warp-skills is internal-only — external contributors lack access to warpdotdev/warp-skills, so it no-ops for them. - bootstrap/run: surface a warning if the warp-skills install unexpectedly fails, instead of silently swallowing it with || true (still non-blocking). - Note that the Windows (bootstrap.ps1) path does not wire up warp-skills yet. Co-Authored-By: Oz --- AGENTS.md | 4 ++-- CONTRIBUTING.md | 2 +- script/bootstrap | 10 +++++++--- script/run | 8 +++++--- 4 files changed, 15 insertions(+), 9 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index fa5c7bf233c..eedb79df74e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -39,7 +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 step; not required for external contributors). +- `./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`. @@ -53,7 +53,7 @@ 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=`. Cloud setup should use `common-skills/scripts/install_common_skills --repo-root --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 not required for external contributors. 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. +`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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0694ddca8c2..b6c47bf4d90 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -102,7 +102,7 @@ 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 **optional and not required for external contributors**: it is best-effort and a no-op if you lack access to that repository, and you can always skip it with `./script/bootstrap --skip-warp-skills` or `WARP_SKIP_WARP_SKILLS_INSTALL=1`. +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: diff --git a/script/bootstrap b/script/bootstrap index e6624f77dcd..2b8c3925004 100755 --- a/script/bootstrap +++ b/script/bootstrap @@ -147,11 +147,13 @@ maybe_install_common_skills() { # Optionally install the internal warp-skills after the common-skills step, via # the shared install_warp_skills wrapper resolved from warpdotdev/common-skills. -# It is best-effort and never fails, but guard with || true so an unexpected -# error can't abort bootstrap. +# 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 - ./script/resolve_common_skills install_warp_skills -- --repo-root "${REPO_ROOT}" --if-needed || true + 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 } @@ -187,6 +189,8 @@ elif [[ "$OS_TYPE" = "Linux" ]]; then 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}" diff --git a/script/run b/script/run index 0137d38771b..7fb5e5e42d2 100755 --- a/script/run +++ b/script/run @@ -129,10 +129,12 @@ 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: it always exits 0; || true keeps set -e from aborting run on an -# unexpected failure. +# 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 ]]; then - ./script/resolve_common_skills install_warp_skills -- --repo-root "${REPO_ROOT}" --if-needed || true + 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 From cb01994a0251178bc5930f797d5bc9b9add628f8 Mon Sep 17 00:00:00 2001 From: vkodithala Date: Thu, 2 Jul 2026 17:30:57 -0400 Subject: [PATCH 6/6] warp-skills: honor WARP_SKIP_WARP_SKILLS_INSTALL in the install guard The warp-skills install guard in bootstrap/run only checked INSTALL_WARP_SKILLS (the --skip-warp-skills flag). Add a WARP_SKIP_WARP_SKILLS_INSTALL=1 check so the documented env opt-out short-circuits before invoking the resolver, matching the common-skills guard. Co-Authored-By: Oz --- script/bootstrap | 3 +++ script/run | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/script/bootstrap b/script/bootstrap index 2b8c3925004..d805c4c954a 100755 --- a/script/bootstrap +++ b/script/bootstrap @@ -151,6 +151,9 @@ maybe_install_common_skills() { # 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 diff --git a/script/run b/script/run index 7fb5e5e42d2..e8aedbb1c5f 100755 --- a/script/run +++ b/script/run @@ -131,7 +131,7 @@ fi # 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 ]]; then +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