Summary

OpenClaw should support a first-class workflow where shared/global skills added after chats already exist become available to those chats reliably and predictably, without requiring manual prompting, per-workspace duplication, or recreating sessions.

Today, shared skill loading appears to exist at the runtime level, but in practice there seems to be a gap between:

• a new shared skill being installed/added
• the gateway/runtime detecting it
• existing chats actually exposing that skill in their effective skill catalog / prompt

This makes shared skills hard to use operationally in long-lived agent systems.

Problem

A common OpenClaw usage pattern is:

1. users have multiple agents
2. agents have ongoing long-lived chats
3. users add or update shared custom skills over time
4. users expect those skills to become available to all relevant agents/chats

In practice, this does not seem to work reliably.

Observed behavior

A new shared skill can be present on disk and even loaded by the gateway config/watch layer, but:

• fresh sessions in some agent contexts may still not show it
• existing ongoing chats may not become aware of it
• list your skills can remain stale or incomplete
• users may need hacks like:
  • manually prompting the session to read a skill file
  • restarting the gateway
  • duplicating skills into workspace-local skills/
  • creating fresh sessions/chats

Why this matters

This breaks the core value of shared skills:

• reduced duplication
• consistent capability across agents
• confidence that agents know the current tool/skill surface

Without reliable propagation, shared skills become operationally fragile.

Expected behavior

When a shared skill is added, updated, or removed from a configured global/shared skill source:

1. the runtime should detect the change
2. affected agents should have their effective skill catalogs updated
3. existing chats/sessions should refresh their skill awareness predictably
4. users should be able to verify the active skill state

Ideal user expectation

If I add a shared skill to a configured shared source, then:

• new sessions should see it immediately
• existing sessions should see it automatically on next turn, or via an explicit refresh action
• list your skills should reflect the real current state

Reproduction example

Setup

• multiple agents, each with separate workspaces
• shared custom skills stored in a global/shared location
• gateway configured to load/watch that location

Repro

1. start gateway
2. have an existing ongoing chat with an agent
3. add a new shared skill to the shared skill directory
4. confirm gateway detects/config-reloads the skill source
5. ask the ongoing chat to list skills
6. optionally create a fresh session for another agent and ask again

Actual result

The new shared skill may still not appear in the skill list or effective prompt.

Expected result

The new shared skill should appear for eligible agents/chats without manual hacks.

Proposed solution

I think this needs both a runtime fix and a user-facing refresh mechanism.

1) Maintain a clear effective skill catalog revision

When a shared skill is added/updated/removed in a loaded skill source, increment a runtime/global effective skill revision.

Sessions should know:

• their current skill snapshot revision
• the current effective catalog revision for the agent/context

If stale, refresh is needed.

2) Auto-refresh stale session skill snapshots on next turn

Before building the assistant prompt for a new turn:

• compare the session snapshot revision to the current effective revision
• if stale, rebuild the session’s effective skill snapshot automatically

This refresh should respect:

• shared/global loaded skills
• workspace-local skills
• managed/bundled skills
• agent allowlists / denylists
• channel/context filters

3) Add an explicit refresh action

Please add a native command/action such as:

• /skills refresh
• /agent refresh-skills

For the current session/chat it should:

• invalidate the current skill snapshot
• rebuild it immediately
• report what changed (added/removed/filtered)

4) Add diagnostics for visibility

Please add a way to explain why a skill is or isn’t visible in a given chat/agent context, e.g.:

• loaded globally: yes/no
• filtered by agent/channel: yes/no
• missing dependency/env requirement: yes/no
• present in current session snapshot: yes/no
• current session revision vs runtime revision

Commands/UI ideas:

• /skills check
• /skills explain <skill-name>

Why this should be prioritized

This is not an edge case. It affects anyone who:

• uses persistent chats
• runs multiple agents
• evolves custom skills over time
• expects shared capability management to work as a real system feature

Without this, “shared skills” are much less useful in practice than they appear conceptually.