Add opt-in common skills installer by zachlloyd · Pull Request #10121 · warpdotdev/warp

zachlloyd · 2026-05-05T03:15:40Z

Description

Replaces the custom common-skills lock file with the standard project lock generated by npx skills, and wires local setup to restore checked-in common skills from that lock.

This PR:

Removes .agents/common-skills.lock and the custom common-skills lock/update workflow.
Adds skills-lock.json, the standard npx skills project lock for skills sourced from warpdotdev/common-skills.
Keeps the copied .agents/skills/* files checked in so local and cloud agents can discover repo-local skills directly from the checkout.
Reworks script/install_common_skills to restore from skills-lock.json via npx --yes skills@1.5.6 experimental_install.
Stores the local install stamp under .git/warp/common-skills-lock.hash so normal restores do not dirty the worktree.
Updates script/run to check the lock before building and restore skills only when the lock hash changed.
Keeps ./script/bootstrap --install-common-skills and .\script\windows\bootstrap.ps1 -InstallCommonSkills as explicit bootstrap paths that delegate to the same installer.
Adds specs/common-skills-installation/TECH.md with separate Mermaid diagrams for the local install/update flow and the Oz Claude cloud-agent environment setup flow.

Pretty cool loom of what's coming on orchestration for anyone interested :)

https://www.loom.com/share/87212dc5a6824573861794e32cf9902d

Flow

Local agent install/update flow

warpdotdev/warp checks in both skills-lock.json and .agents/skills/*.
script/run calls script/install_common_skills --if-needed --non-interactive --quiet before launching the local build.
The installer hashes skills-lock.json and compares it with .git/warp/common-skills-lock.hash.
If the hash matches, it skips restore and continues the build.
If the hash is missing or stale, it runs npx --yes skills@1.5.6 experimental_install, restores .agents/skills/* with the pinned skills@1.5.6 CLI, writes the new local stamp, and then continues.
To intentionally update common skills, run npx --yes skills@1.5.6 update -p -y and commit the resulting skills-lock.json and .agents/skills/* changes together.

Oz Claude cloud-agent environment setup flow

Oz provisions or reuses a cloud environment and clones/syncs warpdotdev/warp.
Environment setup should invoke ./script/install_common_skills --if-needed after checkout sync and before starting the Claude agent.
Fresh environments restore from skills-lock.json; reused environments skip when the cloud-local stamp matches.
The Claude agent starts with repo-local checked-in skills discoverable, and runs may still pass explicit skill specs such as warpdotdev/warp:create-pr.

The Oz environment hook itself lives outside this repo; this PR makes the repository checkout self-sufficient and idempotent when that hook invokes the installer.

Linked Issue

The linked issue is labeled ready-to-spec or ready-to-implement.
Where appropriate, screenshots or a short video of the implementation are included below (especially for user-visible or UI changes).

Screenshots / Videos

Not applicable; script/docs/skills change.

Testing

bash -n script/install_common_skills script/run script/bootstrap
PowerShell parse check for script/windows/bootstrap.ps1
./script/install_common_skills --if-needed --quiet using pinned skills@1.5.6
second ./script/install_common_skills --if-needed --quiet skip-path check
git diff --check
Earlier branch validation: cargo check --manifest-path Cargo.toml
Earlier branch validation: cargo fmt --all --manifest-path Cargo.toml
Earlier branch validation: cargo clippy --manifest-path Cargo.toml --workspace --all-targets --all-features --tests -- -D warnings

Agent Mode

Warp Agent Mode - This PR was created via Warp's AI Agent Mode

Co-Authored-By: Oz oz-agent@warp.dev

oz-for-oss · 2026-05-05T03:15:52Z

@zachlloyd

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

oz-for-oss

Overview

This PR moves shared agent skills out of the Warp repo and adds bootstrap/run integration that installs or refreshes them from the pinned common-skills lock.

Concerns

The local common-skills source path bypasses the documented ref override, so a caller can request one ref and silently install/stamp another.

Verdict

Found: 0 critical, 1 important, 0 suggestions

Request changes

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

Co-Authored-By: Oz <oz-agent@warp.dev>

# Conflicts: # script/macos/bootstrap

Co-Authored-By: Oz <oz-agent@warp.dev>

captainsafia

We may want to update https://github.com/warpdotdev/warp/blob/master/WARP.md#platform-setup to let agents know to bootstrap with support for installing the custom skills.

captainsafia · 2026-05-08T16:01:09Z

@@ -0,0 +1,2 @@
+repo=https://github.com/warpdotdev/common-skills/


Is this a custom lock file format or one that the npx skills command uses?

In either case, we'll probably want to figure out a way to hook this up to our dependency update flows.

Replace the custom common-skills lock with the project skills-lock.json managed by npx skills. Restore checked-in skills through script/run and bootstrap using the standard lock, and document the local and Oz cloud environment flows in a tech spec. Co-Authored-By: Oz <oz-agent@warp.dev>

oz-for-oss · 2026-05-09T18:37:31Z

@zachlloyd

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

oz-for-oss

Overview

This PR replaces the custom common-skills lock/update flow with a standard skills-lock.json restore path and wires it into bootstrap and script/run.

Concerns

Windows bootstrap invocations that include -y/--yes now fail because the Bash wrapper still forwards those args while the PowerShell script only declares Help and InstallCommonSkills switches.

Security

The automatic restore path executes skills@latest from npm on fresh or stale checkouts, so the installer code is not pinned by the checked-in lock.

Verdict

Found: 0 critical, 2 important, 0 suggestions

Request changes

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

oz-for-oss · 2026-05-09T18:47:55Z

+      ;;
+    -y|--yes)
+      export WARP_SKIP_SUDO_PROMPT=1
+      PLATFORM_ARGS+=("${arg}")


⚠️ [IMPORTANT] -y/--yes is still forwarded through PLATFORM_ARGS, but script/windows/bootstrap.ps1 now has a strict param block that only accepts -Help and -InstallCommonSkills; ./script/bootstrap -y on Windows will fail before bootstrap starts. Keep this env-only for Windows or add matching PowerShell passthrough.

oz-for-oss · 2026-05-09T18:47:55Z

+install_from_lock() {
+  (
+    cd "${REPO_ROOT}"
+    npx --yes skills@latest experimental_install


⚠️ [IMPORTANT] [SECURITY] skills@latest runs unpinned npm code whenever a fresh or stale checkout invokes the automatic restore path; skills-lock.json pins skill contents, not the installer. Pin the CLI version or execute a checked-in package-lock-backed tool before making this path automatic.

Avoid forwarding -y/--yes to the Windows bootstrap wrapper, and pin the npx skills CLI used by automatic common-skills restores. Update the tech spec and WARP.md to document the pinned installer/update flow. Co-Authored-By: Oz <oz-agent@warp.dev>

## Description Replaces the custom common-skills lock file with the standard project lock generated by `npx skills`, and wires local setup to restore checked-in common skills from that lock. This PR: - Removes `.agents/common-skills.lock` and the custom common-skills lock/update workflow. - Adds `skills-lock.json`, the standard `npx skills` project lock for skills sourced from `warpdotdev/common-skills`. - Keeps the copied `.agents/skills/*` files checked in so local and cloud agents can discover repo-local skills directly from the checkout. - Reworks `script/install_common_skills` to restore from `skills-lock.json` via `npx --yes skills@1.5.6 experimental_install`. - Stores the local install stamp under `.git/warp/common-skills-lock.hash` so normal restores do not dirty the worktree. - Updates `script/run` to check the lock before building and restore skills only when the lock hash changed. - Keeps `./script/bootstrap --install-common-skills` and `.\script\windows\bootstrap.ps1 -InstallCommonSkills` as explicit bootstrap paths that delegate to the same installer. - Adds `specs/common-skills-installation/TECH.md` with separate Mermaid diagrams for the local install/update flow and the Oz Claude cloud-agent environment setup flow. Pretty cool loom of what's coming on orchestration for anyone interested :) https://www.loom.com/share/87212dc5a6824573861794e32cf9902d ## Flow ### Local agent install/update flow 1. `warpdotdev/warp` checks in both `skills-lock.json` and `.agents/skills/*`. 2. `script/run` calls `script/install_common_skills --if-needed --non-interactive --quiet` before launching the local build. 3. The installer hashes `skills-lock.json` and compares it with `.git/warp/common-skills-lock.hash`. 4. If the hash matches, it skips restore and continues the build. 5. If the hash is missing or stale, it runs `npx --yes skills@1.5.6 experimental_install`, restores `.agents/skills/*` with the pinned `skills@1.5.6` CLI, writes the new local stamp, and then continues. 6. To intentionally update common skills, run `npx --yes skills@1.5.6 update -p -y` and commit the resulting `skills-lock.json` and `.agents/skills/*` changes together. ### Oz Claude cloud-agent environment setup flow 1. Oz provisions or reuses a cloud environment and clones/syncs `warpdotdev/warp`. 2. Environment setup should invoke `./script/install_common_skills --if-needed` after checkout sync and before starting the Claude agent. 3. Fresh environments restore from `skills-lock.json`; reused environments skip when the cloud-local stamp matches. 4. The Claude agent starts with repo-local checked-in skills discoverable, and runs may still pass explicit skill specs such as `warpdotdev/warp:create-pr`. The Oz environment hook itself lives outside this repo; this PR makes the repository checkout self-sufficient and idempotent when that hook invokes the installer. ## Linked Issue - [ ] The linked issue is labeled `ready-to-spec` or `ready-to-implement`. - [ ] Where appropriate, screenshots or a short video of the implementation are included below (especially for user-visible or UI changes). ## Screenshots / Videos Not applicable; script/docs/skills change. ## Testing - `bash -n script/install_common_skills script/run script/bootstrap` - PowerShell parse check for `script/windows/bootstrap.ps1` - `./script/install_common_skills --if-needed --quiet` using pinned `skills@1.5.6` - second `./script/install_common_skills --if-needed --quiet` skip-path check - `git diff --check` - Earlier branch validation: `cargo check --manifest-path Cargo.toml` - Earlier branch validation: `cargo fmt --all --manifest-path Cargo.toml` - Earlier branch validation: `cargo clippy --manifest-path Cargo.toml --workspace --all-targets --all-features --tests -- -D warnings` ## Agent Mode - [x] Warp Agent Mode - This PR was created via Warp's AI Agent Mode Co-Authored-By: Oz <oz-agent@warp.dev> --------- Co-authored-by: Oz <oz-agent@warp.dev>

cla-bot Bot added the cla-signed label May 5, 2026

oz-for-oss Bot reviewed May 5, 2026

View reviewed changes

Comment thread script/install_common_skills Outdated

Add opt-in common skills installer

3df1e8c

Co-Authored-By: Oz <oz-agent@warp.dev>

zachlloyd force-pushed the zach/bootstrap-common-skills-updater branch from 901ca39 to 3df1e8c Compare May 5, 2026 15:07

zachlloyd changed the title ~~Install common agent skills during bootstrap and run~~ Add opt-in common skills installer May 5, 2026

zachlloyd and others added 4 commits May 5, 2026 16:53

Honor explicit common skills refs for local sources

6501e30

Co-Authored-By: Oz <oz-agent@warp.dev>

Merge branch 'master' into zach/bootstrap-common-skills-updater

b9e5eda

# Conflicts: # script/macos/bootstrap

Use npx skills CLI for common skills install

6c7a5ae

Co-Authored-By: Oz <oz-agent@warp.dev>

Fix PowerShell lint for common skills bootstrap

3fa4491

Co-Authored-By: Oz <oz-agent@warp.dev>

zachlloyd requested a review from captainsafia May 8, 2026 00:41

captainsafia reviewed May 8, 2026

View reviewed changes

captainsafia approved these changes May 9, 2026

View reviewed changes

zachlloyd closed this May 9, 2026

zachlloyd reopened this May 9, 2026

zachlloyd enabled auto-merge (squash) May 9, 2026 18:37

oz-for-oss Bot reviewed May 9, 2026

View reviewed changes

zachlloyd disabled auto-merge May 9, 2026 18:51

zachlloyd enabled auto-merge (squash) May 9, 2026 19:04

zachlloyd merged commit b84e3e9 into master May 9, 2026
29 of 30 checks passed

zachlloyd deleted the zach/bootstrap-common-skills-updater branch May 9, 2026 19:20

jasonkeung mentioned this pull request May 10, 2026

[SAL-55] Add orchestration launch modal with placeholders #10382

Merged

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add opt-in common skills installer#10121

Add opt-in common skills installer#10121
zachlloyd merged 7 commits into
masterfrom
zach/bootstrap-common-skills-updater

zachlloyd commented May 5, 2026 •

edited

Loading

Uh oh!

oz-for-oss Bot commented May 5, 2026 •

edited

Loading

Uh oh!

oz-for-oss Bot left a comment

Uh oh!

Uh oh!

captainsafia left a comment

Uh oh!

captainsafia May 8, 2026

Uh oh!

oz-for-oss Bot commented May 9, 2026 •

edited

Loading

Uh oh!

oz-for-oss Bot left a comment

Uh oh!

oz-for-oss Bot May 9, 2026

Uh oh!

oz-for-oss Bot May 9, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -0,0 +1,2 @@
		repo=https://github.com/warpdotdev/common-skills/

Conversation

zachlloyd commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Flow

Local agent install/update flow

Oz Claude cloud-agent environment setup flow

Linked Issue

Screenshots / Videos

Testing

Agent Mode

Uh oh!

oz-for-oss Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot left a comment

Choose a reason for hiding this comment

Overview

Concerns

Verdict

Uh oh!

Uh oh!

captainsafia left a comment

Choose a reason for hiding this comment

Uh oh!

captainsafia May 8, 2026

Choose a reason for hiding this comment

Uh oh!

oz-for-oss Bot commented May 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot left a comment

Choose a reason for hiding this comment

Overview

Concerns

Security

Verdict

Uh oh!

oz-for-oss Bot May 9, 2026

Choose a reason for hiding this comment

Uh oh!

oz-for-oss Bot May 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

zachlloyd commented May 5, 2026 •

edited

Loading

oz-for-oss Bot commented May 5, 2026 •

edited

Loading

oz-for-oss Bot commented May 9, 2026 •

edited

Loading