OpenClaw skills snapshot: why new skills appear only after /new

This is one of those OpenClaw behaviors that feels inconsistent until you trace the internals. You install a skill, you can see the file on disk, but the agent still answers as if that skill does not exist. Then you run /new, start a fresh session, and suddenly the skill is visible.

What OpenClaw actually injects into the agent

The agent does not scan directories on its own and it does not infer skills from vague hints. OpenClaw builds an explicit model-facing block and inserts it into the system prompt under a mandatory skills section. That block is an XML list of eligible skills, including the skill name, description, and the file path to SKILL.md.

In the OpenClaw source, this happens in the system prompt builder and embedded run path. The runtime computes a skillsPrompt, then passes it into the prompt builder before the model turn begins.

Where OpenClaw loads skills from

OpenClaw merges skills from several roots and applies precedence. The important locations are:

1. <workspace>/skills for agent or project-specific skills
2. ~/.openclaw/skills for managed shared skills
3. Bundled skills shipped with the OpenClaw install

In npm-installed environments, bundled skills usually resolve from a path like /usr/local/lib/node_modules/openclaw/skills. That is why agents often mention that location even when you never touched it directly.

Why two agents can behave differently on the same image

The key mistake is assuming the Docker image is the whole story. In practice, two pods on the same image can still diverge because the effective skill set depends on:

• What skill files exist on each pod volume
• Which skills are currently eligible on that pod
• What the current session already has cached in its skills snapshot

That last point is the one most people miss. OpenClaw persists session metadata, including the skills snapshot used for that session. If a session already exists, the runtime can keep using that older snapshot instead of rebuilding from the current filesystem state on every turn.

The real reason /new fixes it

Starting a new session forces OpenClaw down the fresh-session path. On that path, it rebuilds the skill snapshot from the configured workspace and skill roots, then injects the updated prompt into the new agent session. So the user-visible change is not that the model suddenly learned how to search better. The change is that OpenClaw finally handed the model a new list.

OpenClaw also has a watcher for SKILL.md changes, but watcher-driven refresh still depends on the runtime seeing the change and deciding the snapshot version is stale. A new session is the cleanest and most reliable way to guarantee refresh.

Concrete example from a hosted deployment

We investigated two hosted OpenClaw pods on the same image version. The older pod had many skills in ~/.openclaw/skills and its main session snapshot already included them. The newer pod had almost no managed skills yet, plus one workspace skill in ~/.openclaw/workspace/skills.

The newer pod's CLI eligibility check could see that workspace skill. But the active main session prompt still contained only the bundled skills. After starting a new session, the agent could see the new skill immediately. That is exactly what the snapshot model predicts.

Operational takeaway for hosted OpenClaw

If you install, edit, or add a new skill and want the agent to reliably use it right away, tell the user to start a new session with /new. This is especially important in managed environments where the skill file may already be present on disk but the current session is still carrying an older prompt snapshot.

• Installed skill not mentioned by the agent? Start a new session.
• Edited SKILL.md but behavior did not change? Start a new session.
• Different pods list different skills on the same image? Compare on-disk skill roots and session snapshots, not just image tags.

Why this matters for product UX

Without this explanation, the behavior looks random. Users interpret it as a failed install, a broken volume mount, or model inconsistency. The real issue is simpler: OpenClaw has a session-scoped skill prompt cache.

Once you understand that, the correct UX is obvious: after installing a skill, show a small note telling users that the new skill becomes visible to the agent from the next session.

Final takeaway

OpenClaw skills are not only a filesystem feature. They are also a prompt-construction feature and a session-lifecycle feature. If you want to reason about why a skill is or is not visible, you need to inspect all three layers: the skill roots on disk, the current eligibility state, and the session's persisted skills snapshot.