fix(cli): mirror installed OpenClaw skill into agent home dir (Fixes #4819)

[jason-ma-nv]

Summary

Skill install populated only the OpenClaw state dir but never created the home mirror at $HOME/.openclaw/skills/<name>, so on sandboxes whose agent $HOME differs from the state dir a skill showed up in openclaw skills list yet was never loaded by the agent at session start. postInstall now mirrors the uploaded skill into the agent home dir for OpenClaw, symmetric with skill remove (which already deletes that mirror).

Related Issue

Fixes #4819

Changes

• src/lib/skill-install.ts: postInstall now copies the uploaded skill from uploadDir into the OpenClaw home mirror ($HOME/.openclaw/skills/<name>) before refreshing sessions. The copy is a guarded no-op via a [ src -ef dst ] test when both paths resolve to the same directory (the common case where $HOME is the state dir's parent), and emits a warning if the mirror cannot be created.
• src/lib/skill-install.test.ts: added regression tests asserting postInstall issues the mirror command for OpenClaw and warns when the mirror cannot be created.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Verification

• npx prek run --all-files passes
• npm test passes
• Tests added or updated for new or changed behavior
• No secrets, API keys, or credentials committed
• Docs updated for user-facing behavior changes
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: jason jama@nvidia.com

Summary by CodeRabbit

• New Features

  • Skills are mirrored into the local agent home area after upload, improving availability.

• Improvements

  • Installation verification now checks the agent mirror as well as the upload location.
  • Verification failure messages are more informative, including mirror paths when relevant.
  • Mirror creation failures emit warnings but do not block successful installation.

• Tests

  • Added coverage for mirroring behavior, verification logic, and mirror-failure warnings.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: ea033a44-5a9f-4ea8-8a9b-dbffc275fec1

📥 Commits

Reviewing files that changed from the base of the PR and between da307c0 and 8c778e2.

📒 Files selected for processing (3)

• src/lib/actions/sandbox/skill-install.ts
• src/lib/skill-install.test.ts
• src/lib/skill-install.ts

---

📝 Walkthrough

Walkthrough

The PR adds a mirror installation step to the OpenClaw skill deployment flow. After uploading a skill, postInstall now conditionally copies it to the agent's $HOME/.openclaw/skills/ directory via SSH, with tests verifying both successful mirror execution and graceful failure handling.

Changes

OpenClaw skill mirror installation

Layer / File(s)	Summary
Mirror operation and verification updates src/lib/skill-install.ts, src/lib/actions/sandbox/skill-install.ts	Reordered type-only imports and re-exports; postInstall conditionally runs an SSH command to mirror paths.uploadDir into paths.mirrorDir (mkdir/rm/cp), appends a warning on non-zero SSH exit, and verifyInstall now checks SKILL.md at both upload and mirror paths and accepts an sshExecImpl override.
Test coverage for mirror and verification src/lib/skill-install.test.ts	Reformatted imports and added tests verifying the mirror-copy SSH command is constructed and issued, that postInstall still returns success: true with mirror failures while emitting warnings mentioning "mirror", and that verifyInstall checks the home-mirror SKILL.md path and returns false when only the upload-side file exists.

Sequence Diagram

sequenceDiagram
  participant postInstall
  participant uploadStep as Upload Step
  participant mirrorStep as Mirror Step
  participant sshExec
  participant sessionRefresh

  postInstall->>uploadStep: Upload skill to uploadDir
  uploadStep-->>postInstall: upload complete
  postInstall->>mirrorStep: Check paths.mirrorDir
  alt mirrorDir set
    mirrorStep->>sshExec: Execute mkdir -p, rm -rf, cp -a
    alt SSH succeeds
      sshExec-->>mirrorStep: command success
    else SSH fails
      sshExec-->>mirrorStep: command failure
      mirrorStep->>postInstall: append warning message
    end
  end
  postInstall->>sessionRefresh: Refresh sessions (unless skipRefresh)
  sessionRefresh-->>postInstall: refresh complete
  postInstall-->>postInstall: return success: true

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Suggested labels

integration: openclaw, bug-fix

Suggested reviewers

• prekshivyas

Poem

🐰 A skill installed, now mirrored home,
Via SSH's quick steps across the foam,
In $HOME/.openclaw it finds its place,
Tests check the mirror and its quiet grace,
Warnings hum if copying trips, but install wins the race.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and specifically describes the main change: mirroring installed OpenClaw skills into the agent home directory, and correctly references the fixed issue #4819.
Linked Issues check	✅ Passed	The PR fully addresses the linked issue #4819 by implementing the required skill mirroring behavior so agents can load installed skills from the home directory.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to fixing the skill mirroring issue: postInstall mirrors skills, verifyInstall validates the mirror, and error messages are updated accordingly.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/4819-openclaw-skill-mirror

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

E2E Advisor Recommendation

Required E2E: skill-agent-e2e
Optional E2E: openclaw-skill-cli-e2e

Dispatch hint: skill-agent-e2e,openclaw-skill-cli-e2e

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• skill-agent-e2e (medium; installs/onboards a sandbox and uses NVIDIA endpoint inference): Best existing merge-blocking E2E for the main user-flow risk: a skill must be present in the sandbox paths the OpenClaw agent reads and a real agent turn must observe the installed skill content. This PR changes the mirror/verify behavior intended to prevent installed skills from being invisible to the agent.

Optional E2E

• openclaw-skill-cli-e2e (medium; installs/onboards a sandbox but avoids an LLM agent verification turn): Useful adjacent confidence for OpenClaw skill install/list path consistency inside a NemoClaw sandbox. It does not exercise the changed host-side nemoclaw <sandbox> skill install code path, so it is optional rather than merge-blocking.

New E2E recommendations

• host-side NemoClaw sandbox skill install (high): No existing E2E appears to run nemoclaw <sandbox> skill install <local-skill-dir> from the host and then assert both /sandbox/.openclaw/skills/<name>/SKILL.md and $HOME/.openclaw/skills/<name>/SKILL.md exist, followed by nemoclaw <sandbox> skill remove cleanup. That is the exact code path changed here.
  • Suggested test: Add a nightly/selective E2E job such as nemoclaw-sandbox-skill-install-e2e that creates a local SKILL.md fixture, runs host-side nemoclaw <sandbox> skill install, verifies upload + home mirror + verification failure behavior, and optionally checks the agent can load the skill.

Dispatch hint

• Workflow: E2E / Nightly
• jobs input: skill-agent-e2e,openclaw-skill-cli-e2e

[github-actions]

E2E Scenario Advisor Recommendation

Required scenario E2E: None
Optional scenario E2E: None

Workflow run

Full scenario advisor summary

E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required scenario E2E

• None. No scenario E2E jobs are recommended: the changed files are outside test/e2e-scenario/ and the scenario validation suites do not exercise the skill install/remove surface. The PR is covered more directly by unit tests for src/lib/skill-install.ts rather than scenario E2E.

Optional scenario E2E

• None.

Relevant changed files

• None.

[github-actions]

PR Review Advisor

Findings: 0 needs attention, 3 worth checking, 0 nice ideas
Since last review: 1 prior item resolved, 1 still applies, 1 new item found

Review findings

🛠️ Needs attention

• None.

🔎 Worth checking

• Source-of-truth review needed: OpenClaw skill install mirror from uploadDir to `$HOME/.openclaw/skills/<name>`: The advisor marked localized patch analysis as needs_followup.
  • Recommendation: Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
  • Evidence: `postInstall()` adds `mkdir -p`, `rm -rf`, and `cp -a` from `paths.uploadDir` to `paths.mirrorDir`; comments explain the divergent directories but not the long-term source-of-truth plan.
• OpenClaw skill install mirror remains a dual-write workaround without a removal/source-of-truth plan (src/lib/skill-install.ts:242): The code now clearly handles the invalid state where the upload/state directory has the skill but the agent home mirror is missing, and it adds regression coverage for mirror verification. However, this remains a localized dual-write between `/sandbox/.openclaw/skills/<name>` and `$HOME/.openclaw/skills/<name>` without documenting why the authoritative OpenClaw list/load source cannot be fixed here or when the mirror workaround should be removed.
  • Recommendation: Add a short comment or tracking note explaining the source boundary, why this PR cannot make OpenClaw list/load use one canonical skill directory, and the removal condition, for example when OpenClaw exposes/configures a single skill source or a typed install API.
  • Evidence: `postInstall()` copies from `paths.uploadDir` to `paths.mirrorDir` and comments that list reads the state dir while the agent loads from `$HOME/.openclaw/skills`; the regression tests verify the mirror command and mirror-aware `verifyInstall()`, but no removal condition or upstream/source fix constraint is recorded.
• Linked issue's runtime agent-invocation acceptance remains only partially validated: The diff adds strong unit-level evidence that install mirrors `report-writer` into the OpenClaw home skill directory and refuses to verify success when that mirror is missing. The linked issue's expected result, though, is runtime behavior: after install, `openclaw agent --message ...` should reply with the report/topic. That actual agent invocation on the reported macOS/OpenShell environment is not represented in the changed tests or code evidence.
  • Recommendation: Add or identify a targeted runtime/integration validation that installs `report-writer`, confirms both upload and `$HOME` mirror `SKILL.md` exist, invokes OpenClaw with the report prompt, and asserts the reply references `Report on AI testing` or the requested topic.
  • Evidence: Issue [macOS][Agent&Skills] agent does not invoke installed custom skill #4819 expected result says the agent reply should reference the skill/topic. New tests in `src/lib/skill-install.test.ts` assert mirror command construction and `verifyInstall()` behavior, but do not exercise `openclaw skills list` or `openclaw agent --message` in a sandbox.

🌱 Nice ideas

• None.

Consider writing more tests for

• **Runtime validation** — installSandboxSkill exits with the mirror-aware verification error when OpenClaw verifyInstall returns false. The changed production logic is mostly deterministic and now has focused unit tests for mirror command construction and verification failure, but the linked bug is about runtime OpenClaw agent loading/invocation in a sandbox.
• **Runtime validation** — verifyInstall for a non-OpenClaw agent checks only uploadDir/SKILL.md and does not reference mirrorDir. The changed production logic is mostly deterministic and now has focused unit tests for mirror command construction and verification failure, but the linked bug is about runtime OpenClaw agent loading/invocation in a sandbox.
• **Runtime validation** — postInstall for a non-OpenClaw agent emits only the restart hint and does not issue mirror commands. The changed production logic is mostly deterministic and now has focused unit tests for mirror command construction and verification failure, but the linked bug is about runtime OpenClaw agent loading/invocation in a sandbox.
• **Runtime validation** — Runtime validation: install report-writer in an OpenClaw sandbox, verify both uploadDir and $HOME mirror contain SKILL.md, then invoke openclaw agent and assert the reply references "Report on AI testing". The changed production logic is mostly deterministic and now has focused unit tests for mirror command construction and verification failure, but the linked bug is about runtime OpenClaw agent loading/invocation in a sandbox.
• **Acceptance clause:** after a custom "report-writer" skill is installed and recognized in the sandbox, invoking the agent to use the skill does not produce a reply that references the skill or topic. — add test evidence or identify existing coverage. `postInstall()` now mirrors OpenClaw installs into `$HOME/.openclaw/skills/report-writer`, and `verifyInstall()` now requires the mirror `SKILL.md`; tests cover mirror command generation and mirror-missing verification failure. No runtime agent invocation evidence is present.
• **Acceptance clause:** Device: macOS CI runner (Apple Silicon) — add test evidence or identify existing coverage. The patch is deterministic TypeScript/SSH command logic and unit tests; no macOS Apple Silicon runtime validation is included in the diff.
• **Acceptance clause:** OS: macOS — add test evidence or identify existing coverage. No macOS-specific runtime validation or platform-conditional behavior is included in the changed files.
• **Acceptance clause:** Architecture: arm64 — add test evidence or identify existing coverage. No arm64-specific validation is included in the changed files.

Since last review details

Current findings:

• Source-of-truth review needed: OpenClaw skill install mirror from uploadDir to `$HOME/.openclaw/skills/<name>`: The advisor marked localized patch analysis as needs_followup.
  • Recommendation: Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
  • Evidence: `postInstall()` adds `mkdir -p`, `rm -rf`, and `cp -a` from `paths.uploadDir` to `paths.mirrorDir`; comments explain the divergent directories but not the long-term source-of-truth plan.
• OpenClaw skill install mirror remains a dual-write workaround without a removal/source-of-truth plan (src/lib/skill-install.ts:242): The code now clearly handles the invalid state where the upload/state directory has the skill but the agent home mirror is missing, and it adds regression coverage for mirror verification. However, this remains a localized dual-write between `/sandbox/.openclaw/skills/<name>` and `$HOME/.openclaw/skills/<name>` without documenting why the authoritative OpenClaw list/load source cannot be fixed here or when the mirror workaround should be removed.
  • Recommendation: Add a short comment or tracking note explaining the source boundary, why this PR cannot make OpenClaw list/load use one canonical skill directory, and the removal condition, for example when OpenClaw exposes/configures a single skill source or a typed install API.
  • Evidence: `postInstall()` copies from `paths.uploadDir` to `paths.mirrorDir` and comments that list reads the state dir while the agent loads from `$HOME/.openclaw/skills`; the regression tests verify the mirror command and mirror-aware `verifyInstall()`, but no removal condition or upstream/source fix constraint is recorded.
• Linked issue's runtime agent-invocation acceptance remains only partially validated: The diff adds strong unit-level evidence that install mirrors `report-writer` into the OpenClaw home skill directory and refuses to verify success when that mirror is missing. The linked issue's expected result, though, is runtime behavior: after install, `openclaw agent --message ...` should reply with the report/topic. That actual agent invocation on the reported macOS/OpenShell environment is not represented in the changed tests or code evidence.
  • Recommendation: Add or identify a targeted runtime/integration validation that installs `report-writer`, confirms both upload and `$HOME` mirror `SKILL.md` exist, invokes OpenClaw with the report prompt, and asserts the reply references `Report on AI testing` or the requested topic.
  • Evidence: Issue [macOS][Agent&Skills] agent does not invoke installed custom skill #4819 expected result says the agent reply should reference the skill/topic. New tests in `src/lib/skill-install.test.ts` assert mirror command construction and `verifyInstall()` behavior, but do not exercise `openclaw skills list` or `openclaw agent --message` in a sandbox.

Workflow run details

This is an automated advisory review. A human maintainer must make the final merge decision.

[jason-ma-nv]

Addressed the PR Review Advisor findings in 8c778e2.

"Install can report success even when the home mirror was not created" (worth checking): Correct and important — it would have left the linked bug unfixed while reporting success. verifyInstall now also requires SKILL.md at the OpenClaw home mirror ($HOME/.openclaw/skills/<name>), symmetric with verifyRemove, which already checks both paths. A failed mirror copy now fails install verification, and the CLI reports it with a mirror-aware message instead of printing "✓ installed". Added two verifyInstall unit tests (mirror is checked; verification fails when the mirror is missing).

"Source-of-truth review" (worth checking): The mirror is intentionally a second authoritative location rather than a relocation of the source of truth. openclaw skills list reads the OpenClaw state dir (uploadDir), and removeSkill/verifyRemove/checkExisting already treat both uploadDir and the home mirror as authoritative. Uploading only to $HOME would desync the listing; uploading only to the state dir leaves the agent's load path empty when $HOME ≠ state dir. Maintaining both — and now verifying both on install — keeps install symmetric with remove and makes the mirror part of the success contract (the regression condition the advisor asked for).

E2E Advisor: Agreed that skill-agent-e2e is the right live-sandbox regression for the user-visible outcome; it needs a live sandbox + NVIDIA_API_KEY, so it's for the nightly run rather than this PR's checks. A dedicated nemoclaw-skill-install-to-agent-load E2E (host-side install → verify both paths → agent uses the skill token) is a reasonable follow-up.