PR #74466: feat(cli): support installing skills to shared global directory via --global

• Repository: openclaw/openclaw
• Author: Marvae
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/74466

Description (problem / solution / changelog)

Summary

• Problem: openclaw skills install only targets workspace directories, requiring manual file movement for shared skills
• Why it matters: Multi-agent setups need skills shared globally across agents
• What changed: Added --global flag to install and update commands, targeting ~/.openclaw/skills
• What did NOT change: Default behavior unchanged; workspace resolution logic untouched; ClawHub installer unchanged

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #74124
• Related #56161
• This PR fixes a bug or regression

Root Cause (if applicable)

N/A (feature request)

Regression Test Plan (if applicable)

• Coverage level:
  • Unit test
• Target test file: src/cli/skills-cli.commands.test.ts
• Scenarios locked in:
  • --global installs to CONFIG_DIR
  • --global and --agent mutually exclusive
  • --global works for both install and update
• 6 new unit tests added

User-visible / Behavior Changes

• New --global flag for openclaw skills install and openclaw skills update
• --global installs/updates skills in ~/.openclaw/skills instead of workspace

Diagram (if applicable)

N/A

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: macOS 24.6.0
• Runtime/container: Node.js v25.6.1
• Model/provider: N/A
• Integration/channel: CLI

Steps

1. node openclaw.mjs skills install test-test --global
2. Check ~/.openclaw/skills/test-test exists
3. node openclaw.mjs skills update test-test --global
4. Verify update checks the global directory

Expected

• Skill installed/updated in shared directory ~/.openclaw/skills/

Actual

• Works as expected

Evidence

• Failing test/log before + passing after

Unit tests:

pnpm test src/cli/skills-cli.commands.test.ts
# 27 tests passed (6 new)

Manual E2E (install --global):

$ node openclaw.mjs skills install test-test --global
Downloading [email protected] from ClawHub…
Installing to /Users/hongweima/.openclaw/skills/test-test…
Installed [email protected] -> /Users/hongweima/.openclaw/skills/test-test

Manual E2E (update --global):

$ node openclaw.mjs skills update test-test --global
Downloading [email protected] from ClawHub…
Installing to /Users/hongweima/.openclaw/skills/test-test…
test-test already at 1.0.16

Human Verification (required)

• Verified scenarios: Unit tests pass (27/27), manual E2E with real ClawHub install and update
• Edge cases checked: --global + --agent conflict, parent --agent with child --global
• What you did NOT verify: N/A (all scenarios verified)

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: Global installs may override workspace-specific versions
  • Mitigation: Workspace skills have higher precedence in skill loader (documented behavior)

Changed files

• docs/cli/skills.md (modified, +13/-7)
• docs/help/faq.md (modified, +7/-4)
• docs/tools/clawhub.md (modified, +6/-2)
• docs/tools/skills.md (modified, +14/-10)
• src/cli/skills-cli.commands.test.ts (modified, +115/-0)
• src/cli/skills-cli.ts (modified, +31/-10)