openclaw - 💡(How to fix) Fix [Feature]: Expose skills-registry, frontmatter, and env-sanitizer helpers via plugin-sdk

Summary

Re-export the existing loadWorkspaceSkillEntries, parseFrontmatter, resolveOpenClawMetadata, and sanitizeSystemRunEnvOverrides helpers from openclaw/plugin-sdk/skills-runtime (and ./plugin-sdk/sandbox) so third-party plugins can reach the skills registry, SKILL.md frontmatter parser, and host-env sanitizer that OpenClaw already uses internally.

Problem to solve

openclaw/plugin-sdk/skills-runtime currently exposes only refresh-state helpers (src/plugin-sdk/skills-runtime.ts). The published package's "exports" map blocks plugin imports outside ./plugin-sdk/*, so any third-party plugin that needs to inspect or operate on installed skills must reimplement directory resolution, frontmatter parsing, and env-overlay sanitization from scratch.

This forces plugin authors into the same two fragile workarounds #74900 calls out for the embedding-provider case: either deep-import internals with no semver protection, or carry a hand-rolled copy that silently drifts from upstream.

Concrete real-world plugin: a third-party plugin registering a skills.setup gateway RPC method (runs an installed skill's setup hook, complementary to #80213) carries ~120 lines of code that exists solely because the upstream helpers aren't reachable.

The hand-rolled YAML parser is the most concerning piece: it can't handle quoted strings with embedded #, doesn't honor block scalars, and silently trails upstream's parser as the SKILL.md frontmatter shape evolves.

Proposed solution

Two additions to src/plugin-sdk/skills-runtime.ts, following the same re-export pattern as src/plugin-sdk/agent-runtime.ts (export * from "../agents/agent-scope.js" + sibling re-exports):

// existing:
export {
  bumpSkillsSnapshotVersion,
  getSkillsSnapshotVersion,
  registerSkillsChangeListener,
  shouldRefreshSnapshotForVersion,
  type SkillsChangeEvent,
} from "../agents/skills/refresh-state.js";

// proposed additions:
export {
  loadWorkspaceSkillEntries,
  loadVisibleWorkspaceSkillEntries,
} from "../agents/skills/workspace.js";

export {
  parseFrontmatter,
  resolveOpenClawMetadata,
  resolveSkillKey,
} from "../agents/skills/frontmatter.js";

export type {
  Skill,
  SkillEntry,
  ParsedSkillFrontmatter,
  OpenClawSkillMetadata,
} from "../agents/skills/types.js";

One addition to src/plugin-sdk/sandbox.ts (or a new ./plugin-sdk/host-env):

export {
  sanitizeSystemRunEnvOverrides,
  isDangerousHostEnvOverrideVarName,
} from "../infra/host-env-security.js";

All four target files already export the listed symbols. The proposal is purely re-export plumbing in plugin-sdk/*; no changes to the underlying helpers' implementations or signatures.

Alternatives considered

• Widen the "exports" map to expose ./agents/* directly. Rejected — leaks the entire internals tree past a stable boundary and prevents future refactors. The SDK re-export pattern keeps the public surface curated.
• skills.status over an in-process gateway RPC (#76756 would enable this). Useful for the curated-metadata case but doesn't carry raw frontmatter, doesn't help the env-sanitizer case, and adds an RPC round-trip for what is conceptually a local read. Complementary, not a substitute.
• Continue hand-rolling per plugin (status quo). Each plugin that touches the skills domain re-derives the same code; the hand-rolled YAML parsers in particular silently trail upstream's.

Impact

• Affected: every third-party plugin that needs to inspect installed skills, parse SKILL.md frontmatter, or sanitize environment overlays before spawning a sub-process. Examples: setup-hook plugins (complementary to #80213), audit / lint tooling, custom skill-management UIs, integration-management plugins.
• Severity: medium. Plugins can ship today by reimplementing — they're not blocked — but each reimplementation is a future-correctness liability.
• Frequency: one-time author cost per plugin, then ongoing drift as upstream evolves the SKILL.md shape and env-sanitizer policy.
• Consequence: plugin code duplicates ~100 LoC of upstream logic per implementation, with the YAML parser specifically prone to silent divergence. Today's third-party skills-setup plugin is a concrete instance of this cost.

Evidence/examples

• Existing precedent for the proposed pattern: src/plugin-sdk/agent-runtime.ts re-exports agent-scope.js and ~14 sibling modules via the same shape.
• Existing related proposals:
  • #80219 — [plugin sdk] Consolidate author surface, lifecycle semantics, and export sprawl — whole-surface audit. This proposal is one concrete sub-case of the export-sprawl problem #80219 lays out.
  • #74900 — stable public SDK path for embedding provider API — same shape of ask, different domain. Sets the precedent this proposal follows.
  • #76759 — export StatusSummary and ModelCatalogEntry types from plugin-sdk — another narrow "expose these symbols via plugin-sdk" request.

Additional information

• Verified against: [email protected] (the project's currently-pinned release). Same gap exists on main.
• Not a duplicate of #80213. That issue defines the skill-author-side setup.script hook spec. This proposal is the plugin-side SDK gap that affects any plugin operating on the skills domain — and would still apply to audit / inspection / UI plugins after #80213 lands.
• Backward compatibility: purely additive. Existing imports from openclaw/plugin-sdk/skills-runtime continue to work.