Context
After markdown-only skill plugins land (tracked separately as the next deliverable), the natural follow-on is hybrid plugins — a single plugin shipping both:
- A SKILL.md authored to agentskills.io (orchestration, instructions, references)
- A
.wasm binary exporting custom tools the skill can call
This is the pattern for capability bundles where the skill body references tools that don't exist anywhere else — e.g. a design-assistant plugin shipping a SKILL.md describing the workflow plus a WASM tool exporting image_gen_fal and layout_compose that the skill orchestrates. The skill becomes the user-facing entry point; the tools are the privileged operations.
This issue scopes the bridge between the two: a skill in plugin X can name and invoke a tool exported by plugin X.
Target
Per the agentskills.io specification, allow:
-
Plugins declaring multiple capabilities: capabilities = [\"skill\", \"tool\"] in manifest.toml. Both wasm_path and SKILL.md must be present and valid.
-
Plugin-owned tool namespace: tools exported by the plugin's WASM are addressable from the plugin's SKILL.md body via a stable convention — e.g. plugin:<plugin-name>/<tool-name>. The skill loader resolves these references against the plugin host's tool registry at skill execution time.
-
Tool discovery from SKILL.md: skills SHOULD be able to declare which plugin-owned tools they use in their frontmatter (similar to MCP tool declarations in Claude skills) so the host can validate the references exist before invoking the skill.
-
Permission inheritance: tools and skills in the same plugin share the manifest's permission grant. A plugin declaring http_client exposes it to both its WASM tools and its skill body's any-tool-invocations. No separate per-skill permission scoping in v1.
-
Skill execution orchestrates plugin tools: when the agent invokes a hybrid plugin's skill, the skill body runs, and any tool calls it makes resolve through the plugin's own tool registry first, then fall through to the global registry. This keeps skill-tool naming local to the plugin.
Why it matters
- Capability bundles: a single install ships both the workflow knowledge (skill) and the privileged operations (tool). Users don't have to find two separate plugins and connect them.
- Plugin-owned namespaces avoid LLM confusion: when twenty plugins ship a tool called
generate, the LLM can disambiguate via the plugin prefix.
- Aligns with how Claude skills already work: skills frequently reference MCP-provided tools. A hybrid plugin is the ZeroClaw equivalent — the plugin replaces the MCP server as the tool provider.
Current state
Scope out
- Skills invoking plugin-only host functions — i.e. capability host functions the plugin host exposes to its own .wasm but not to other plugins or to user-authored skills. This is a "skills-calling-WASM" distinction worth a third issue once the architecture for hybrid plugins is concrete.
- Cross-plugin tool references — skill in plugin A invoking a tool from plugin B. v1 keeps everything plugin-local for predictability.
- Skill versioning relative to the bundled tools — minor version bumps on the WASM tool that change tool signatures break the skill that references them. Mitigation strategies (semver-checked tool signatures, pinned tool versions in skill frontmatter) are out of scope for v1.
Dependencies
Blocked by the markdown-only skill capability issue (must land first).
References
Context
After markdown-only skill plugins land (tracked separately as the next deliverable), the natural follow-on is hybrid plugins — a single plugin shipping both:
.wasmbinary exporting custom tools the skill can callThis is the pattern for capability bundles where the skill body references tools that don't exist anywhere else — e.g. a design-assistant plugin shipping a SKILL.md describing the workflow plus a WASM tool exporting
image_gen_falandlayout_composethat the skill orchestrates. The skill becomes the user-facing entry point; the tools are the privileged operations.This issue scopes the bridge between the two: a skill in plugin X can name and invoke a tool exported by plugin X.
Target
Per the agentskills.io specification, allow:
Plugins declaring multiple capabilities:
capabilities = [\"skill\", \"tool\"]inmanifest.toml. Bothwasm_pathandSKILL.mdmust be present and valid.Plugin-owned tool namespace: tools exported by the plugin's WASM are addressable from the plugin's SKILL.md body via a stable convention — e.g.
plugin:<plugin-name>/<tool-name>. The skill loader resolves these references against the plugin host's tool registry at skill execution time.Tool discovery from SKILL.md: skills SHOULD be able to declare which plugin-owned tools they use in their frontmatter (similar to MCP tool declarations in Claude skills) so the host can validate the references exist before invoking the skill.
Permission inheritance: tools and skills in the same plugin share the manifest's permission grant. A plugin declaring
http_clientexposes it to both its WASM tools and its skill body's any-tool-invocations. No separate per-skill permission scoping in v1.Skill execution orchestrates plugin tools: when the agent invokes a hybrid plugin's skill, the skill body runs, and any tool calls it makes resolve through the plugin's own tool registry first, then fall through to the global registry. This keeps skill-tool naming local to the plugin.
Why it matters
generate, the LLM can disambiguate via the plugin prefix.Current state
Scope out
Dependencies
Blocked by the markdown-only skill capability issue (must land first).
References
crates/zeroclaw-runtime/src/skills/mod.rscrates/zeroclaw-plugins/src/runtime.rs,crates/zeroclaw-plugins/src/wasm_tool.rsdocs/reference/api/plugin-protocol.md