> ## Documentation Index
> Fetch the complete documentation index at: https://docs-code.palyra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills and Wasm Plugin System

<details>
  <summary>Relevant source files</summary>

  The following files were used as context for generating this wiki page:

  * crates/palyra-a2ui/Cargo.toml
  * crates/palyra-auth/Cargo.toml
  * crates/palyra-cli/src/args/extension.rs
  * crates/palyra-cli/src/args/skills.rs
  * crates/palyra-cli/src/commands/extension.rs
  * crates/palyra-cli/src/commands/skills.rs
  * crates/palyra-cli/src/output/skills.rs
  * crates/palyra-cli/tests/help\_snapshots/skills-help.txt
  * crates/palyra-cli/tests/skills\_lifecycle.rs
  * crates/palyra-common/Cargo.toml
  * crates/palyra-daemon/src/plugins.rs
  * crates/palyra-daemon/src/transport/http/handlers/console/plugins.rs
  * crates/palyra-daemon/src/transport/http/handlers/console/skills.rs
  * crates/palyra-daemon/src/wasm\_plugin\_runner.rs
  * crates/palyra-identity/Cargo.toml
  * crates/palyra-plugins/runtime/Cargo.toml
  * crates/palyra-plugins/runtime/src/lib.rs
  * crates/palyra-plugins/sdk/Cargo.toml
  * crates/palyra-plugins/sdk/src/lib.rs
  * crates/palyra-plugins/sdk/wit/palyra-sdk.wit
  * crates/palyra-policy/Cargo.toml
  * crates/palyra-skills/Cargo.toml
  * crates/palyra-skills/examples/echo-http/skill.toml
  * crates/palyra-skills/src/artifact.rs
  * crates/palyra-skills/src/audit.rs
  * crates/palyra-skills/src/constants.rs
  * crates/palyra-skills/src/error.rs
  * crates/palyra-skills/src/extension.rs
  * crates/palyra-skills/src/lib.rs
  * crates/palyra-skills/src/manifest.rs
  * crates/palyra-skills/src/models.rs
  * crates/palyra-skills/src/runtime.rs
  * crates/palyra-skills/src/tests.rs
  * crates/palyra-skills/src/trust.rs
  * crates/palyra-skills/src/verify.rs
  * scripts/test/install-clean-desktop.sh
  * scripts/test/uninstall-clean-desktop.sh
</details>

The Palyra Skill system provides a secure, signed artifact format (`.palyra-skill`) for extending agent capabilities using WebAssembly (Wasm). It implements a layered security model combining Ed25519 code signing, publisher trust via Trust-On-First-Use (TOFU), and a resource-constrained Wasmtime runtime with fine-grained capability grants.

## Skill Artifact Format

A skill artifact is a ZIP-compressed archive containing a mandatory manifest, signed modules, and optional assets. The structure is strictly validated to prevent path traversal and unauthorized file inclusion [crates/palyra-skills/src/artifact.rs#1-20](http://crates/palyra-skills/src/artifact.rs#1-20).

### Manifest Structure (`skill.toml`)

The `skill.toml` file defines the identity, entrypoints, and required capabilities of the skill. It is parsed using `parse_manifest_toml` [crates/palyra-skills/src/manifest.rs#38-43](http://crates/palyra-skills/src/manifest.rs#38-43).

| Section             | Description                                                                                                                                                   |
| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `manifest_version`  | Current version (2) [crates/palyra-skills/src/constants.rs#20-20](http://crates/palyra-skills/src/constants.rs#20-20).                                        |
| `skill_id`          | Unique identifier (e.g., `acme.echo_http`) [crates/palyra-skills/src/tests.rs#27-27](http://crates/palyra-skills/src/tests.rs#27-27).                         |
| `entrypoints.tools` | Defines the tool ID, input/output JSON schemas, and risk profile [crates/palyra-skills/src/tests.rs#33-47](http://crates/palyra-skills/src/tests.rs#33-47).   |
| `capabilities`      | Explicit allowlists for HTTP egress, filesystem roots, and secrets [crates/palyra-skills/src/tests.rs#49-65](http://crates/palyra-skills/src/tests.rs#49-65). |
| `operator.plugin`   | Maps tools to specific Wasm modules and entrypoint functions [crates/palyra-skills/src/tests.rs#79-83](http://crates/palyra-skills/src/tests.rs#79-83).       |

### Internal Artifact Layout

* `skill.toml`: The validated manifest [crates/palyra-skills/src/constants.rs#28-28](http://crates/palyra-skills/src/constants.rs#28-28).
* `signature.json`: Ed25519 signature of the payload SHA-256 hash [crates/palyra-skills/src/constants.rs#28-28](http://crates/palyra-skills/src/constants.rs#28-28).
* `modules/`: Wasm binaries [crates/palyra-cli/src/commands/skills.rs#43-52](http://crates/palyra-cli/src/commands/skills.rs#43-52).
* `sbom.cdx.json`: CycloneDX Software Bill of Materials [crates/palyra-skills/src/constants.rs#27-27](http://crates/palyra-skills/src/constants.rs#27-27).
* `provenance.json`: SLSA-style build provenance [crates/palyra-skills/src/constants.rs#27-27](http://crates/palyra-skills/src/constants.rs#27-27).

## Security and Trust Model

Palyra employs a "Fail-Closed" trust model for skill execution.

### Code Signing and Verification

Artifacts are signed during the `skills package build` flow using an Ed25519 key [crates/palyra-cli/src/commands/skills.rs#79-87](http://crates/palyra-cli/src/commands/skills.rs#79-87). The `verify_skill_artifact` function ensures the signature matches the payload and that the publisher is trusted [crates/palyra-skills/src/verify.rs#43-43](http://crates/palyra-skills/src/verify.rs#43-43).

### Publisher Trust (TOFU + Allowlist)

Trust is managed via the `SkillTrustStore` [crates/palyra-skills/src/models.rs#19-19](http://crates/palyra-skills/src/models.rs#19-19):

1. **Allowlist**: Explicitly trusted publisher public keys.
2. **TOFU (Trust-On-First-Use)**: If enabled, the first time a publisher's key is seen, it is recorded and trusted for subsequent updates [crates/palyra-cli/src/commands/skills.rs#145-146](http://crates/palyra-cli/src/commands/skills.rs#145-146).
3. **Integrity**: The `trust.json` file is protected by a SHA-256 HMAC to prevent manual tampering [crates/palyra-cli/src/commands/skills.rs#139-139](http://crates/palyra-cli/src/commands/skills.rs#139-139).

### Security Audit

Before installation, artifacts undergo a `SkillSecurityAudit` which checks for:

* **Wasm Export Limits**: Prevents excessive surface area [crates/palyra-skills/src/constants.rs#27-27](http://crates/palyra-skills/src/constants.rs#27-27).
* **Filesystem Safety**: Detects symlink escapes or unsafe permissions [crates/palyra-daemon/src/plugins.rs#158-163](http://crates/palyra-daemon/src/plugins.rs#158-163).
* **Capability Overreach**: Flags skills requesting broad wildcards (e.g., `*` for HTTP egress) [crates/palyra-skills/src/manifest.rs#147-155](http://crates/palyra-skills/src/manifest.rs#147-155).

## Wasm Plugin Runtime

Plugins are executed in a sandboxed environment powered by `wasmtime`. The `WasmRuntime` enforces strict resource quotas and capability mediation [crates/palyra-plugins/runtime/src/lib.rs#1-6](http://crates/palyra-plugins/runtime/src/lib.rs#1-6).

### Resource Quotas

Limits are defined in `RuntimeLimits` and enforced per-invocation [crates/palyra-plugins/runtime/src/lib.rs#44-54](http://crates/palyra-plugins/runtime/src/lib.rs#44-54):

* **Fuel Budget**: Instruction-level metering (default 10M) [crates/palyra-plugins/runtime/src/lib.rs#59-59](http://crates/palyra-plugins/runtime/src/lib.rs#59-59).
* **Memory**: Linear memory cap (default 64MB) [crates/palyra-plugins/runtime/src/lib.rs#60-60](http://crates/palyra-plugins/runtime/src/lib.rs#60-60).
* **Instances/Tables**: Caps on module instantiation and table elements [crates/palyra-plugins/runtime/src/lib.rs#61-62](http://crates/palyra-plugins/runtime/src/lib.rs#61-62).

### Capability Mediation

Plugins cannot access the host directly. Instead, they receive opaque integer handles for granted resources [crates/palyra-plugins/runtime/src/lib.rs#98-112](http://crates/palyra-plugins/runtime/src/lib.rs#98-112).

#### Data Flow: Skill Invocation

```mermaid theme={null}
graph TD
    subgraph "Daemon Host"
        A["Agent/Tool Call"] --> B["WasmPluginRunner"]
        B --> C["Policy Check (WasmPluginRunnerPolicy)"]
        C --> D["Manifest Grant Intersection"]
        D --> E["Wasmtime Store (Fuel/Mem Limits)"]
    end

    subgraph "Wasm Guest (Sandbox)"
        E --> F["Plugin Module"]
        F --> G["SDK Imports (WIT)"]
    end

    G --> H["Host Capability Service"]
    H --> I["HTTP/Secrets/FS"]
```

*Sources: [crates/palyra-daemon/src/wasm\_plugin\_runner.rs#163-186](http://crates/palyra-daemon/src/wasm_plugin_runner.rs#163-186), [crates/palyra-plugins/runtime/src/lib.rs#3-6](http://crates/palyra-plugins/runtime/src/lib.rs#3-6)*

## Plugin SDK and WIT Interface

The interaction between the host and the Wasm guest is defined by the Palyra Plugin SDK using the WebAssembly Interface Type (WIT) format.

### WIT Interface (`palyra-sdk.wit`)

The SDK exposes "Tier A" capabilities via the `palyra:plugins/host-capabilities` import module [crates/palyra-plugins/sdk/src/lib.rs#24-24](http://crates/palyra-plugins/sdk/src/lib.rs#24-24).

**Key SDK Constants:**

* **World Name**: `palyra-plugin` [crates/palyra-plugins/sdk/src/lib.rs#22-22](http://crates/palyra-plugins/sdk/src/lib.rs#22-22).
* **Entrypoint**: `run` [crates/palyra-plugins/sdk/src/lib.rs#46-46](http://crates/palyra-plugins/sdk/src/lib.rs#46-46).
* **Handle Bases**: HTTP (10,000), Secret (20,000), Storage (30,000), Channel (40,000) [crates/palyra-plugins/runtime/src/lib.rs#29-32](http://crates/palyra-plugins/runtime/src/lib.rs#29-32).

### Typed Plugin Contracts

Beyond simple tools, plugins can implement specific host extension points called `TypedPluginContractKind` [crates/palyra-plugins/sdk/src/lib.rs#60-73](http://crates/palyra-plugins/sdk/src/lib.rs#60-73).

| Contract Kind        | Purpose                                                                                                                                |
| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------- |
| `memory_provider`    | Custom agent memory storage/retrieval [crates/palyra-plugins/sdk/src/lib.rs#80-80](http://crates/palyra-plugins/sdk/src/lib.rs#80-80). |
| `routing_strategy`   | Logic for selecting LLM providers [crates/palyra-plugins/sdk/src/lib.rs#82-82](http://crates/palyra-plugins/sdk/src/lib.rs#82-82).     |
| `run_lifecycle_hook` | Logic executed at agent run start/end [crates/palyra-plugins/sdk/src/lib.rs#83-83](http://crates/palyra-plugins/sdk/src/lib.rs#83-83). |
| `delivery_adapter`   | Custom channel messaging logic [crates/palyra-plugins/sdk/src/lib.rs#89-89](http://crates/palyra-plugins/sdk/src/lib.rs#89-89).        |

### Code Entity Mapping

```mermaid theme={null}
classDiagram
    class "WasmPluginRunner" {
        +run_wasm_plugin(policy, input, timeout)
        -execute_module(policy, skill, bytes, entrypoint)
    }
    class "WasmRuntime" {
        +engine: Engine
        +linker: Linker
        +run(entrypoint, input)
    }
    class "SkillManifest" {
        +skill_id: String
        +publisher: String
        +capabilities: SkillCapabilities
    }
    class "PluginBindingRecord" {
        +plugin_id: String
        +enabled: bool
        +capability_diff: PluginCapabilityDiff
    }

    WasmPluginRunner --> WasmRuntime : "instantiates"
    WasmPluginRunner --> SkillManifest : "validates grants"
    WasmPluginRunner --> PluginBindingRecord : "resolves config"
```

*Sources: [crates/palyra-daemon/src/wasm\_plugin\_runner.rs#163-167](http://crates/palyra-daemon/src/wasm_plugin_runner.rs#163-167), [crates/palyra-plugins/runtime/src/lib.rs#22-25](http://crates/palyra-plugins/runtime/src/lib.rs#22-25), [crates/palyra-daemon/src/plugins.rs#68-96](http://crates/palyra-daemon/src/plugins.rs#68-96)*

## CLI and Console Integration

The skill lifecycle is exposed through the `palyra skills` CLI and the Web Console.

* **Packaging**: `run_skills(SkillsCommand::Package)` handles artifact creation and signing [crates/palyra-cli/src/commands/skills.rs#23-36](http://crates/palyra-cli/src/commands/skills.rs#23-36).
* **Inventory**: `console_skills_list_handler` provides a JSON view of installed skills and their runtime status [crates/palyra-daemon/src/transport/http/handlers/console/skills.rs#23-27](http://crates/palyra-daemon/src/transport/http/handlers/console/skills.rs#23-27).
* **Dynamic Building**: The `Dynamic Tool Builder` allows generating skill scaffolds from natural language prompts or learning candidates [crates/palyra-daemon/src/transport/http/handlers/console/skills.rs#94-112](http://crates/palyra-daemon/src/transport/http/handlers/console/skills.rs#94-112).

### Sources:

* [crates/palyra-cli/src/commands/skills.rs]()
* [crates/palyra-daemon/src/wasm\_plugin\_runner.rs]()
* [crates/palyra-plugins/runtime/src/lib.rs]()
* [crates/palyra-plugins/sdk/src/lib.rs]()
* [crates/palyra-skills/src/lib.rs]()
* [crates/palyra-skills/src/manifest.rs]()
* [crates/palyra-skills/src/artifact.rs]()
* [crates/palyra-daemon/src/transport/http/handlers/console/skills.rs]()
* [crates/palyra-daemon/src/plugins.rs]()