#16654: fix: refresh skills snapshot when managed skills change
agents
stale
size: XS
Cluster:
Skill and Session Management Fixes
## Bug
Installing managed skills to `~/.openclaw/skills/` (or restarting the gateway after adding skills) does not refresh the skills snapshot in active sessions. Sessions continue using stale skill definitions until the gateway process is fully restarted AND a new session is created.
## Root Cause
In `src/auto-reply/reply/session-updates.ts`, the refresh guard is:
```typescript
const shouldRefreshSnapshot =
snapshotVersion > 0 && (nextEntry?.skillsSnapshot?.version ?? 0) < snapshotVersion;
```
`snapshotVersion` comes from `getSkillsSnapshotVersion()`, which returns `Math.max(globalVersion, local)`. The `globalVersion` counter is initialized to `0` in `src/agents/skills/refresh.ts`.
On a fresh gateway process, `globalVersion` is `0` and no workspace-specific version exists yet, so `getSkillsSnapshotVersion()` returns `0`. The `> 0` guard makes `shouldRefreshSnapshot` always `false`, preventing any snapshot rebuild on the first session turn.
The filesystem watcher correctly bumps the version when skill files change, but this only helps for *subsequent* turns after the watcher has fired — not for the cold-start case.
## Fix
**One-line change:** Initialize `globalVersion = 1` instead of `0` in `src/agents/skills/refresh.ts`.
This ensures:
- The `snapshotVersion > 0` guard passes on the very first session turn after gateway start
- Sessions always build a fresh snapshot on their first turn
- The existing watcher-based bump mechanism continues to work for live file changes
- No behavioral change for the remote-node bump path
## How to Test
1. Start the gateway
2. Install a new skill to `~/.openclaw/skills/`
3. Send a message in an active session
4. Verify the new skill appears in available tools
## Tests Added
- `getSkillsSnapshotVersion` returns > 0 on cold start
- `bumpSkillsSnapshotVersion` increases the version
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Changes `globalVersion` initialization from `0` to `1` in `src/agents/skills/refresh.ts` to fix cold-start snapshot refresh bug. Previously, sessions would fail to build skill snapshots on first turn after gateway restart because the `snapshotVersion > 0` guard in `session-updates.ts:158` would always be false. With this one-line fix, the guard now passes and sessions correctly rebuild snapshots on cold start.
<h3>Confidence Score: 5/5</h3>
- Safe to merge - minimal, well-targeted fix with appropriate test coverage
- Single constant change with clear intent, well-explained root cause, and new tests that verify the fix. The change is backwards-compatible and only affects initialization behavior.
- No files require special attention
<sub>Last reviewed commit: 858a08e</sub>
<!-- greptile_other_comments_section -->
<sub>(2/5) Greptile learns from your feedback when you react with thumbs up/down!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#22568: fix(gateway): bump skills snapshot version on startup so sessions r...
by zwffff · 2026-02-21
89.3%
#22525: [Bug]: Session snapshot not reloading skills after gateway restart ...
by zwffff · 2026-02-21
87.4%
#12209: fix(skills): refresh stale skill snapshot after gateway restart
by mcaxtr · 2026-02-09
87.0%
#21883: fix: guard against undefined snapshot.skills in applySkillEnvOverride…
by felipedamacenoteodoro · 2026-02-20
82.3%
#14023: fix: filter skills watcher to relevant file types to prevent FD exh...
by funmerlin · 2026-02-11
81.2%
#13412: fix(sessions): refresh allowAgents permissions after gateway restart
by arun-dev-des · 2026-02-10
80.6%
#11250: fix: expand skills watcher ignore list and improve session repair l...
by zhangzhefang-github · 2026-02-07
80.3%
#20533: fix: strip resolvedSkills from session store to prevent snapshot bloat
by echoVic · 2026-02-19
80.2%
#9221: fix(skills): use skillKey for env config lookup in snapshots
by gavinbmoore · 2026-02-05
79.7%
#21521: fix: re-resolve skill paths at runtime for cross-machine portability
by mmaghsoodnia · 2026-02-20
78.3%