How should shared skills be organized across OpenClaw and other harnesses?

Troubleshooting
, , , ,
1

Adapted community discussion: Paraphrased and condensed from an anonymized public OpenClaw Discord support conversation from August 2026. Technical guidance was reviewed for OpenClaw 2026.9.3.

I want a common set of skills available to all my OpenClaw agents and other agent harnesses. I see skills under both ~/.agents/skills and ~/.openclaw/skills, including compatibility symlinks. Which directory should be canonical, and is it safe to remove duplicate symlinks without making a skill unavailable?

2

For a default OpenClaw state, common skills can live in ~/.agents/skills, while ~/.openclaw/skills remains the managed OpenClaw-specific root. Compatibility symlinks are useful when another harness or installer expects a different root. Removing only a symlink does not remove its target, but another profile, older tool, or harness may still depend on that link.

Before changing anything, identify the winning origin for the intended agent:

openclaw skills list --agent AGENT_ID --verbose
openclaw skills list --agent AGENT_ID --eligible

Start a new session after changing file-backed skills so the agent does not keep an earlier skill snapshot.

3

Could I put common skills at the shared root, then create openclaw, codex, and other harness-specific subfolders underneath it? I was thinking of symlinking each harness skill directory to its own subfolder.

4

That layout is tidy for humans, but folder names do not create harness isolation by themselves. OpenClaw can discover nested skill directories, so harness-specific subfolders under the shared root may still make those skills visible to OpenClaw.

A cleaner pattern is:

  • Put genuinely shared skills in ~/.agents/skills.
  • Put OpenClaw-specific skills in ~/.openclaw/skills.
  • Keep other harness-specific skills in those harnesses’ native roots.
  • When compatibility requires a link, symlink an individual skill directory rather than an entire skill root.

Use agent skill filters when the same installed collection needs different visibility. Then verify the intended origin and eligibility for each agent. A skill being discoverable still does not grant its tools, filesystem access, or sandbox permissions.