[Bug]: Plugin manifest `skills` field not published to agent skill discovery paths

[100yenadmin]

Bug type

Behavior bug (incorrect output/state without crash)

Beta release blocker

No

Summary

When a plugin manifest declares "skills": [...], those skills are not published to the global skill-discovery paths the agent SDK reads from (~/.agents/skills/ and ~/.openclaw/skills/). The agent gets ENOENT when it tries to read the SKILL.md, so plugin tools that depend on the SKILL.md prompt never appear in the agent's tool palette.

Steps to reproduce

1. Install a plugin that declares skills in its manifest. Example: lossless-claw at ~/.openclaw/extensions/lossless-claw/ with openclaw.plugin.json:

   {
     "id": "lossless-claw",
     "kind": "context-engine",
     "skills": ["skills/lossless-claw"]
   }

2. Confirm the actual SKILL.md exists on disk: ~/.openclaw/extensions/lossless-claw/skills/lossless-claw/SKILL.md (a real 3275-byte file).
3. Start a session. The agent (running inside the gateway) tries to load the LCM skill using the agent SDK convention path ~/.agents/skills/lossless-claw/SKILL.md.
4. Observe gateway log:

   [tools] read failed: ENOENT: no such file or directory, access '/Users/lume/.agents/skills/lossless-claw/SKILL.md' raw_params={"path":"/Users/lume/.agents/skills/lossless-claw/SKILL.md"}
   

5. Confirm neither ~/.agents/skills/lossless-claw/ nor ~/.openclaw/skills/lossless-claw/ exists. The plugin's skill is unreachable from the agent.

Expected behavior

When a plugin manifest declares "skills": [...], OpenClaw's plugin loader should publish those skills so the agent SDK can find them — for example by symlinking into ~/.openclaw/skills/<skill-id>/, by registering them into the agent skill-discovery search path, or by some equivalent mechanism. This is what the manifest.skills field implies.

The same pattern affects every stock plugin that ships skills (browser, memory-wiki, tavily, open-prose, irc, matrix, telegram, slack) — none of them appear under ~/.agents/skills/ or ~/.openclaw/skills/ either, so the same defect blocks any plugin from shipping a usable skill.

Actual behavior

The plugin's tools (e.g. lcm_grep, lcm_describe, lcm_expand, lcm_expand_query, lcm_recent for lossless-claw) are correctly registered at runtime, but the SKILL.md is unreachable. As a result the agent never reads the skill prompt, so:

• The plugin's tools don't surface in the agent's tool palette.
• The agent appears to "not know about" tools that are actually registered.
• The user only sees a confusing ENOENT in gateway logs (if they look).

The manifest skills field is effectively dead — declared but unreachable.

Looking at src/agents/skills/plugin-skills.ts, resolvePluginSkillDirs() returns the resolved on-disk paths inside the plugin root, but those paths are never published to the agent SDK's discovery paths. Issue #64816 (closed by bc24b547d088) wired plugin skills into the workspace skill snapshot for <available_skills> prompt rendering, but the agent SDK file-based discovery paths (~/.agents/skills/, ~/.openclaw/skills/) are still not populated, which is why the agent-side ENOENT still fires.

OpenClaw version

2026.5.3-1 (2eae30e)

Operating system

macOS 25.4.0 (Darwin arm64)

Install method

npm global

Model

anthropic/claude-opus-4.5 (effective for the failing agent run)

Provider / routing chain

openclaw -> anthropic

Logs, screenshots, and evidence

[tools] read failed: ENOENT: no such file or directory, access '/Users/lume/.agents/skills/lossless-claw/SKILL.md' raw_params={"path":"/Users/lume/.agents/skills/lossless-claw/SKILL.md"}

Filesystem state confirming the manifest declares the skill but the discovery path is empty:

$ cat ~/.openclaw/extensions/lossless-claw/openclaw.plugin.json | jq '.skills'
[
  "skills/lossless-claw"
]

$ ls ~/.openclaw/extensions/lossless-claw/skills/lossless-claw/SKILL.md
~/.openclaw/extensions/lossless-claw/skills/lossless-claw/SKILL.md   (3275 bytes)

$ ls ~/.agents/skills/lossless-claw/SKILL.md
ls: cannot access '~/.agents/skills/lossless-claw/SKILL.md': No such file or directory

$ ls ~/.openclaw/skills/ | grep lossless-claw
(no result — the entry that does exist is a manual user symlink, not auto-published)

Impact and severity

Affected: every plugin that declares "skills" in openclaw.plugin.json — confirmed for lossless-claw and all stock plugins that ship skills (browser, memory-wiki, tavily, open-prose, irc, matrix, telegram, slack).

Severity: High. Plugin-shipped skill prompts never reach the agent, so any tool palette that depends on the SKILL.md is silently incomplete. The plugin appears installed and tools are registered, but the agent does not behave as documented.

Frequency: Always (every session, for every plugin that ships skills).

Consequence: Plugin authors cannot reliably ship a skill alongside their plugin. Users hit confusing symptoms — tools registered but agent unaware — with the only signal being an ENOENT line in gateway logs. Manual workaround: symlink each plugin's skill directory into ~/.openclaw/skills/, which defeats the purpose of the manifest field.

Additional information

Suggested fixes (any one would resolve the user-visible defect):

1. Auto-publish plugin-declared skills into ~/.openclaw/skills/<skill-id>/ (symlink) at plugin registration time. Preferred — single source of truth, no API change.
2. Extend the agent SDK's skill-discovery search path at registration time to include each enabled plugin's <plugin>/skills/ directory.
3. If manifest.skills is intentionally informational only, document that explicitly and give plugin authors a supported install hook to publish skills themselves.

Related: #64816 (closed) addressed CLI-vs-<available_skills> parity for bundled plugin skills. This issue is the remaining gap on the agent SDK file-discovery side.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve.

Summary
Keep open: current main has the prior manifest-to-snapshot wiring, but source inspection still shows plugin-declared skill directories are consumed in place rather than exposed through the file-discovery roots named in the report.

Reproducibility: Do we have a high-confidence way to reproduce the issue? Not as a live gateway failure in this review, but source inspection confirms the reported publication gap: enabled plugin skill dirs are loaded directly and no current path publishes them into the file-discovery roots named by the report.

Next step
This is a narrow source-reproducible skills/plugin loader gap with clear likely files, but the repair lane should validate the exact discovery surface before changing publication behavior.

Review details

Best possible solution:

Add a generic contained search-path or publication integration for enabled plugin skill directories so prompt snapshots and agent file discovery see the same enabled skill set, with no plugin-specific ids.

Do we have a high-confidence way to reproduce the issue?

Do we have a high-confidence way to reproduce the issue? Not as a live gateway failure in this review, but source inspection confirms the reported publication gap: enabled plugin skill dirs are loaded directly and no current path publishes them into the file-discovery roots named by the report.

Is this the best way to solve the issue?

Is this the best way to solve the issue? The direction is right, but the safest implementation is likely to register plugin skill roots with the agent discovery layer or create a guarded managed mirror rather than adding unconditional global symlinks.

Acceptance criteria:

• pnpm test src/agents/skills/plugin-skills.test.ts src/agents/skills.loadworkspaceskillentries.test.ts src/agents/pi-embedded-runner/skills-runtime.integration.test.ts
• pnpm test src/agents/skills.buildworkspaceskillsnapshot.test.ts
• pnpm check:changed

What I checked:

• Manifest contract: The plugin manifest reference defines skills as skill directories to load relative to the plugin root. Public docs: docs/plugins/manifest.md. (docs/plugins/manifest.md:184, c59c20e9fd48)
• Plugin skill resolution: resolvePluginSkillDirs() resolves enabled plugin skills entries to paths inside each plugin root and returns those paths directly. (src/agents/skills/plugin-skills.ts:74, c59c20e9fd48)
• Workspace loader integration: The workspace skill loader appends plugin skill directories to the extra-dir scan list and labels them openclaw-extra; this path does not materialize entries in the managed or personal agent skill roots. (src/agents/skills/workspace.ts:636, c59c20e9fd48)
• Existing coverage boundary: Current tests verify plugin-shipped skills are loaded into loadWorkspaceSkillEntries() and filtered by plugin config, but they do not cover file-discovery publication. (src/agents/skills.loadworkspaceskillentries.test.ts:141, c59c20e9fd48)
• Bundled plugins declare skills: The bundled browser plugin declares skills: ["./skills"], matching the affected stock-plugin pattern described in the report. (extensions/browser/openclaw.plugin.json:12, c59c20e9fd48)
• Related prior issue: The provided related context says Plugin-bundled skill visible to CLI but not surfaced to agent available_skills in live session #64816 was closed after wiring plugin skills into the workspace skill snapshot for available-skills prompt rendering; this report describes the remaining file-discovery side of the same product area.

Likely related people:

• Peter Steinberger: Available blame for the plugin skill resolver and workspace skill merge path points to commit 5b528f4, which owns the current manifest-skill loading behavior in this checkout. (role: recent maintainer / introduced visible current behavior; confidence: medium; commits: 5b528f4dfe; files: src/agents/skills/plugin-skills.ts, src/agents/skills/workspace.ts)

Remaining risk / open question:

• I did not live-run a gateway session with the external lossless-claw plugin, so the exact ENOENT path is taken from the issue logs plus source inspection rather than reproduced locally.
• A physical publication fix needs a guarded collision and realpath-containment policy for third-party plugin skills; blindly mirroring or linking plugin content into shared roots would be riskier than registering contained discovery roots.

Codex review notes: model gpt-5.5, reasoning high; reviewed against c59c20e9fd48.