PR #59298: feat(skills): notify agents of available updates via skill preambles

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

Description (problem / solution / changelog)

Summary

• Add openclaw update hint subcommand that reads cached ~/.openclaw/update-check.json and prints an UPGRADE_AVAILABLE one-liner when a newer version exists. Zero network calls — reads the state file maintained by the gateway's periodic update check. Silent on errors, designed for preamble contexts.
• Add bash preamble blocks to all 7 .agents/skills/*/SKILL.md files so every skill invocation surfaces update availability to the agent context.
• --json mode always emits a JSON object ({ "updateAvailable": false } when current, full object when update available), consistent with every other openclaw ... --json command.

Feature proposal: #59304

Why it matters

There is no way to know a newer OpenClaw version is available when working inside a skill. Users have to remember to run openclaw update manually. This brings the same seamless upgrade notification pattern used by gstack to OpenClaw — the agent sees the hint in context and can suggest upgrading.

How it works

1. The gateway's existing periodic update check writes ~/.openclaw/update-check.json with lastAvailableVersion.
2. openclaw update hint reads that file, compares against the running VERSION, and prints:

   UPGRADE_AVAILABLE 2026.3.28 2026.4.1 (latest). Run: openclaw update

3. Each skill's preamble runs: _UPD=$(openclaw update hint 2>/dev/null || true); [ -n "$_UPD" ] && echo "$_UPD" || true
4. The agent sees the output and can suggest upgrading.

What changed

• New file: src/cli/update-cli/hint.ts — 76-line command implementation
• New file: src/cli/update-cli/hint.test.ts — 9 tests (no state file, no version, up-to-date, newer available, JSON output with update, JSON output without update, local-newer, corrupt JSON)
• Modified: src/cli/update-cli.ts — registers the hint subcommand under openclaw update
• Modified: 7 .agents/skills/*/SKILL.md — identical 4-line preamble block each

Test plan

• 9 unit tests covering all paths including --json no-update output
• pnpm check (tsgo + lint + format) passes
• Manual: run openclaw update hint with/without a stale update-check.json
• Manual: invoke a skill in Claude Code and verify the preamble surfaces the hint

Co-Authored-By: Claude Opus 4.6 (1M context) [email protected]

Changed files

• .agents/skills/openclaw-ghsa-maintainer/SKILL.md (modified, +6/-0)
• .agents/skills/openclaw-parallels-smoke/SKILL.md (modified, +6/-0)
• .agents/skills/openclaw-pr-maintainer/SKILL.md (modified, +6/-0)
• .agents/skills/openclaw-release-maintainer/SKILL.md (modified, +6/-0)
• .agents/skills/openclaw-test-heap-leaks/SKILL.md (modified, +6/-0)
• .agents/skills/parallels-discord-roundtrip/SKILL.md (modified, +6/-0)
• .agents/skills/security-triage/SKILL.md (modified, +6/-0)
• src/cli/update-cli.ts (modified, +17/-2)
• src/cli/update-cli/hint.test.ts (added, +134/-0)
• src/cli/update-cli/hint.ts (added, +76/-0)