1. Skill Manifest and Metadata
TheSkillManifest is the central configuration file (skill.toml) for any skill. It defines the identity, requirements, and requested capabilities of the skill.
Key Manifest Components
- Identity:
skill_id,version(SemVer), andpublishername. - Entrypoints: Defines the tools exposed by the skill, including their JSON Schema for inputs/outputs and risk profiles crates/palyra-skills/src/manifest.rs#72-98.
- Capabilities: A strict allowlist of resources the skill requires, such as
http_egress_allowlist,filesystem(read/write roots), andsecretscrates/palyra-skills/src/manifest.rs#99-137. - Quotas: Hard limits on execution, including
wall_clock_timeout_ms,fuel_budget, andmax_memory_bytescrates/palyra-skills/src/manifest.rs#138-145.
Compatibility Enforcement
The runtime enforces versioning constraints defined in the manifest’scompat section. It checks the required_protocol_major and min_palyra_version against the current daemon metadata crates/palyra-skills/src/manifest.rs#152-171.
Sources: crates/palyra-skills/src/manifest.rs#12-150, crates/palyra-skills/src/models.rs#1-100
2. Artifact Packaging and Signing
Skills are distributed as signed ZIP archives with a.palyra-skill extension crates/palyra-skills/src/constants.rs#13-17.
The Packaging Process
- Bundle Creation: The
build_signed_skill_artifactfunction takes the manifest, Wasm modules, and assets crates/palyra-skills/src/artifact.rs#11-59. - Sidecar Injection: The packager automatically generates and includes:
skill.toml: The validated manifest.sbom.cyclonedx.json: Software Bill of Materials.provenance.json: Build metadata.
- Signing: A SHA-256 hash of the payload is signed using an Ed25519 private key. The resulting
signature.jsoncontains thekey_idand the signature bytes crates/palyra-skills/src/artifact.rs#50-65.
CLI Integration
Thepalyra skills package build command facilitates this lifecycle, allowing developers to pull signing keys from the palyra-vault or stdin crates/palyra-cli/src/commands/skills.rs#5-67.
Sources: crates/palyra-skills/src/artifact.rs#11-65, crates/palyra-cli/src/commands/skills.rs#5-105
3. Trust Models and Verification
Palyra implements a multi-tiered trust model for skill installation, managed via theSkillTrustStore.
Trust Decisions
- Allowlisted: The publisher’s public key is explicitly trusted in the configuration.
- TOFU (Trust On First Use): The daemon accepts a new publisher key and “pins” it for all future updates of that
skill_idcrates/palyra-cli/src/commands/skills.rs#106-126. - Quarantined: If verification fails or if the skill is newly installed via an experimental builder, it enters a
Quarantinedstate where execution is forbidden until manual operator approval crates/palyra-daemon/src/transport/http/handlers/console/skills.rs#166-179.
Verification Logic
Theverify_skill_artifact function performs:
- Integrity Check: Verifies the ZIP structure and SHA-256 hashes.
- Signature Validation: Confirms the signature matches the payload using the publisher’s public key.
- Trust Evaluation: Checks the
SkillTrustStoreto see if the key is known or if TOFU is permitted crates/palyra-skills/src/verify.rs#25-80.
4. Security Auditing
Before execution, and periodically thereafter, skills undergo an automated security audit viaaudit_skill_artifact_security.
Audit Checks
| Check | Description |
|---|---|
| Module Size | Ensures Wasm modules do not exceed max_module_bytes crates/palyra-skills/src/constants.rs#14. |
| Exports | Limits the number of exported functions to prevent complexity attacks. |
| Imports | Scans Wasm imports to ensure they only target allowed Palyra host modules (e.g., palyra:plugin/*). |
| Capabilities | Validates that requested capabilities (like wildcard HTTP hosts) match the runtime security policy. |
5. Implementation Diagrams
Skill Installation and Verification Flow
This diagram bridges thepalyra-cli command to the palyra-skills logic and the palyrad state.
Skill Execution Capability Resolution
Associates manifest data with theWasmPluginRunner used during tool invocation.
Sources: crates/palyra-daemon/src/wasm_plugin_runner.rs#84-110, crates/palyra-skills/src/runtime.rs#21-23
6. InstalledSkillsIndex and Persistence
The daemon maintains anInstalledSkillsIndex on disk to track the state of all skills across restarts.
Index Record Structure
EachSkillInventoryEntry includes:
- Record: The base skill metadata and
trust_decision. - Runtime Status: Current state (
Active,Quarantined,Error) crates/palyra-cli/src/output/skills.rs#42-55. - Eligibility: Whether the skill is compatible with the current hardware/node capabilities.
Periodic Re-audit
Thepalyrad scheduler triggers periodic re-audits of installed skills. If a skill’s artifact is tampered with on disk, or if a new security policy renders a previously “Safe” skill “Risky,” the skill_status is updated to Quarantined, and an event is logged to the JournalStore crates/palyra-daemon/src/transport/http/handlers/console/skills.rs#164-184.
Sources: crates/palyra-daemon/src/transport/http/handlers/console/skills.rs#9-42, crates/palyra-cli/src/output/skills.rs#25-57