fix(skill): clarify plugin install errors (Fixes #2536)

[deepujain]

Summary

nemoclaw <sandbox> skill install --help was treated like a path, and plugin-shaped directories only got a generic missing SKILL.md error. This PR makes the help path work and gives plugin users a clearer next step.

Changes

• Print skill install usage when --help, -h, or help follows install.
• Detect OpenClaw plugin-shaped directories through openclaw.plugin.json or package.json metadata.
• Add a targeted hint that plugins should be baked into a custom sandbox image with nemoclaw onboard --from.
• Add CLI tests for both flows.

Testing

• npm run build:cli passed.
• npm run typecheck:cli passed.
• npm test -- test/cli.test.ts passed: 61 tests.
• Full npm test -- --reporter=dot was attempted. In this local checkout it still fails outside this change in installer/uninstall/onboard/build-context tests, including temp-source generated-dist lookup and a few timeout/status checks.

Evidence it works

The CLI test now verifies that skill install --help returns usage without a missing-file error and that plugin-shaped directories get the OpenClaw plugin hint.

Fixes #2536

Signed-off-by: Deepak Jain deepujain@gmail.com

Summary by CodeRabbit

• Bug Fixes

  • Improved error detection and messaging for skill install when given plugin-shaped directories, and added a clear suggestion to use the sandbox onboarding workflow instead.
  • Enhanced --help handling to display skill-install usage immediately, including when --help is passed as the positional path.

• Tests

  • Expanded CLI tests for skill install help and plugin-detection scenarios, and restored related start-test coverage.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[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: 46209c5c-8193-46b3-af45-db5902937739

📥 Commits

Reviewing files that changed from the base of the PR and between 025b3c6 and 51e4b72.

📒 Files selected for processing (2)

• src/nemoclaw.ts
• test/cli.test.ts

---

📝 Walkthrough

Walkthrough

Refactors sandboxSkillInstall to centralize and correctly handle --help/-h cases, adds OpenClaw plugin-shape detection (checks openclaw.plugin.json and package.json markers) to produce a specialized error/hint, and expands tests to cover help output and plugin-rejection behavior.

Changes

Cohort / File(s)	Summary
CLI Command Refactoring src/nemoclaw.ts	Extracts skill-install usage into printSkillInstallUsage() and returns early for top-level or positional --help/-h tokens; adds looksLikeOpenClawPlugin() detection (checks openclaw.plugin.json and package.json openclaw markers) and printPluginInstallHint() to emit a plugin-specific error pointing users toward nemoclaw onboard --from <Dockerfile>; minor formatting tweaks.
Test Coverage test/cli.test.ts	Adds writeSandboxRegistry helper to seed tests, replaces prior registry setup with assertions for alpha skill install, and adds tests verifying: skill install --help prints the specific skill-install usage; directories shaped like OpenClaw plugins (via package.json openclaw.extensions or openclaw.plugin.json) are rejected with the plugin hint; restores start test assertions.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐇 I hopped through flags and files today,
Found help that wandered far astray.
I sniffed a plugin, gave a friendly hint,
Pointed to Dockerfile magic in a sprint.
Now installs are clear — a tidy little play!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: fixing skill install error messages and clarifying them for plugin users, with a clear reference to issue #2536.
Linked Issues check	✅ Passed	The pull request fully addresses the objectives from issue #2536: detects plugin-shaped directories via openclaw.plugin.json and package.json markers, emits a redirect hint for plugins, fixes the --help argument handling, and adds comprehensive CLI tests.
Out of Scope Changes check	✅ Passed	All changes are directly related to fixing skill install error handling and plugin detection as specified in issue #2536; no out-of-scope modifications detected.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

🧹 Nitpick comments (2)

test/cli.test.ts (1)

173-189: Add one test for the openclaw.plugin.json marker path.

You already validate package.json metadata detection; adding the file-marker case would lock down both supported plugin-shape signals.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@test/cli.test.ts` around lines 173 - 189, Add a second assertion path that
exercises the openclaw.plugin.json marker: create a file named
"openclaw.plugin.json" inside the test's pluginDir (e.g., using
fs.writeFileSync) with minimal valid JSON to mark the directory as an OpenClaw
plugin, then call runWithEnv the same way and assert the same failure code and
output messages; you can either extend the existing "points plugin-shaped
directories away from skill install" test to write that marker file in addition
to package.json or create a new test using the same helpers (runWithEnv,
writeSandboxRegistry) and the same expected messages.

src/nemoclaw.ts (1)

2204-2217: Tighten plugin-shape detection to reduce false positives.

Boolean(packageJson?.openclaw) may classify non-plugin packages as plugins. Consider checking explicit plugin markers/shape in package.json instead of any openclaw object.

Suggested refinement

 function looksLikeOpenClawPlugin(candidatePath: string): boolean {
@@
   const packageJsonPath = path.join(dir, "package.json");
   if (!fs.existsSync(packageJsonPath)) return false;
   try {
     const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
-    return Boolean(packageJson?.openclaw);
+    const openclawBlock = packageJson?.openclaw;
+    return Boolean(
+      openclawBlock?.plugin ||
+        packageJson?.["openclaw.plugin"] ||
+        (Array.isArray(openclawBlock?.extensions) && openclawBlock.extensions.length > 0),
+    );
   } catch {
     return false;
   }
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/nemoclaw.ts` around lines 2204 - 2217, The current
looksLikeOpenClawPlugin function uses Boolean(packageJson?.openclaw) which is
too permissive; update the package.json check inside looksLikeOpenClawPlugin to
detect an explicit plugin shape (e.g., require packageJson.openclaw to be an
object with specific keys or a boolean flag) rather than any truthy value—for
example ensure typeof packageJson.openclaw === "object" and it contains required
markers like "plugin": true or "entry"/"main" (or require openclaw === true) and
return true only when those explicit markers exist; modify the code that reads
packageJson in looksLikeOpenClawPlugin to perform this stricter validation and
fall back to false otherwise.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@src/nemoclaw.ts`:
- Around line 2204-2217: The current looksLikeOpenClawPlugin function uses
Boolean(packageJson?.openclaw) which is too permissive; update the package.json
check inside looksLikeOpenClawPlugin to detect an explicit plugin shape (e.g.,
require packageJson.openclaw to be an object with specific keys or a boolean
flag) rather than any truthy value—for example ensure typeof
packageJson.openclaw === "object" and it contains required markers like
"plugin": true or "entry"/"main" (or require openclaw === true) and return true
only when those explicit markers exist; modify the code that reads packageJson
in looksLikeOpenClawPlugin to perform this stricter validation and fall back to
false otherwise.

In `@test/cli.test.ts`:
- Around line 173-189: Add a second assertion path that exercises the
openclaw.plugin.json marker: create a file named "openclaw.plugin.json" inside
the test's pluginDir (e.g., using fs.writeFileSync) with minimal valid JSON to
mark the directory as an OpenClaw plugin, then call runWithEnv the same way and
assert the same failure code and output messages; you can either extend the
existing "points plugin-shaped directories away from skill install" test to
write that marker file in addition to package.json or create a new test using
the same helpers (runWithEnv, writeSandboxRegistry) and the same expected
messages.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 8f59ebb9-54aa-4aa6-bbad-fa339107afd7

📥 Commits

Reviewing files that changed from the base of the PR and between 0b49851 and 025b3c6.

📒 Files selected for processing (2)

• src/nemoclaw.ts
• test/cli.test.ts

[deepujain]

Rebased on latest main. Tightened plugin detection to explicit OpenClaw markers and added coverage for openclaw.plugin.json. npm run build:cli and npm test -- test/cli.test.ts pass.

[cv]

looksLikeOpenClawPlugin could use a lot of cleaning up, but that can be a follow-up