palyra-skills crate provides the foundational infrastructure for extending the Palyra ecosystem through portable, signed, and audited artifacts. Skills are packaged as ZIP-based bundles containing WebAssembly (WASM) modules, static assets, and a manifest that defines capabilities and security requirements.
Skill Artifact Structure
A Skill artifact is a ZIP archive (typically with a.palyra-skill extension) that follows a strict internal layout. This format ensures that all necessary metadata, security provenance, and executable code are bundled together for distribution and verification.
Internal File Layout
The following files are defined as standard paths within the artifact:skill.toml: The mandatory manifest defining the skill’s identity and requirements crates/palyra-skills/src/lib.rs#15-15.signature.ed25519: A cryptographic signature of the artifact’s payload crates/palyra-skills/src/lib.rs#15-15.sbom.cyclonedx.json: A Software Bill of Materials for supply chain transparency crates/palyra-skills/src/lib.rs#15-15.provenance.json: Build-time attestation data crates/palyra-skills/src/lib.rs#13-13.
Manifest Schema
Theskill.toml file contains the SkillManifest, which includes:
- Identity:
skill_id,version, andpublishercrates/palyra-skills/src/models.rs#10-15. - Capabilities: Required permissions such as
http_egress,storage_access, andsecret_refscrates/palyra-skills/src/models.rs#40-55. - Tools: Definitions of functions exported by the WASM modules that the daemon can invoke.
Skill Packaging Data Flow
The following diagram illustrates how the CLI assembles these components into a signed artifact. Diagram: Skill Packaging Flow Sources: crates/palyra-skills/src/lib.rs#1-11, crates/palyra-cli/src/commands/skills.rs#59-67Cryptographic Signing & Trust Store
Palyra usesEd25519 signatures to ensure the integrity and authenticity of skills. Every artifact must be signed by a publisher’s private key before it can be installed in a production environment.
Verification Process
When a skill is presented for installation, theverify_skill_artifact function performs several checks:
- Integrity: Validates that the SHA256 hash of the payload matches the signed hash crates/palyra-skills/src/verify.rs#24-24.
- Signature: Verifies the
signature.ed25519using the publisher’s public key crates/palyra-skills/src/lib.rs#24-24. - Trust Store Lookup: Checks if the publisher’s key is already trusted in the local
TrustStorecrates/palyra-daemon/src/transport/http/handlers/console/skills.rs#74-79.
TOFU (Trust On First Use)
The system supports a TOFU mechanism. If a skill is signed by a previously unknown publisher, the operator can choose to “pin” that publisher’s key during the first installation crates/palyra-daemon/src/transport/http/handlers/console/skills.rs#76-79. Subsequent updates to that skill must be signed by the same key. Sources: crates/palyra-skills/src/lib.rs#8-24, crates/palyra-daemon/src/transport/http/handlers/console/skills.rs#74-94Security Auditing & Quarantine
Before a skill is promoted to the “installed” index, it undergoes an automated security audit.Audit Checks
Theaudit_skill_artifact_security function performs static analysis on the WASM modules:
- Resource Limits: Checks module size against
DEFAULT_SKILL_AUDIT_MAX_MODULE_BYTEScrates/palyra-skills/src/lib.rs#13-15. - Interface Validation: Ensures the module only exports allowed functions and does not exceed
DEFAULT_SKILL_AUDIT_MAX_EXPORTED_FUNCTIONScrates/palyra-skills/src/lib.rs#13-15. - Capability Matching: Verifies that the requested capabilities in the manifest match the actual imports in the WASM bytecode.
Quarantine Lifecycle
Skills that fail audit or verification are placed in a Quarantine state. They cannot be executed by the orchestrator until an administrator manually promotes them or resolves the underlying security issue crates/palyra-cli/src/output/skills.rs#104-113. Sources: crates/palyra-skills/src/lib.rs#2-12, crates/palyra-cli/src/output/skills.rs#85-119Lifecycle Management & Installed Index
Thepalyrad daemon maintains an installed-index that tracks all active skills and their versions.
The Installed Skill Record
Each entry in the index is anInstalledSkillRecord, which persists:
- Metadata:
skill_id,version, andinstalled_at_unix_mscrates/palyra-daemon/src/transport/http/handlers/console/skills.rs#122-131. - Security State:
artifact_sha256,signature_key_id, and thetrust_decision(e.g.,tofu_pinned) crates/palyra-daemon/src/transport/http/handlers/console/skills.rs#132-141. - Source: The filesystem path to the managed artifact crates/palyra-daemon/src/transport/http/handlers/console/skills.rs#142-145.
Lifecycle Transitions
The following diagram maps the lifecycle of a skill from a raw artifact to an active tool in the orchestrator. Diagram: Skill Lifecycle & Code EntitiesSkill Status & Health
The daemon provides askill_status API that aggregates the installation state, runtime readiness, and any missing requirements (such as missing secrets defined in the manifest) crates/palyra-daemon/src/transport/http/handlers/console/skills.rs#24-33.
Sources: crates/palyra-daemon/src/transport/http/handlers/console/skills.rs#7-40, crates/palyra-daemon/src/transport/http/handlers/console/skills.rs#115-156, crates/palyra-cli/src/output/skills.rs#25-57