Skip to main content
This page details the Palyra skill packaging format, the cryptographic trust model used to verify third-party extensions, and the lifecycle of skill artifacts from build to periodic re-audit.

​
Overview

Palyra skills are packaged as signed ZIP archives with the .palyra-skill extension crates/palyra-skills/src/constants.rs#15-15. They combine a manifest, Wasm modules, assets, and security metadata (SBOM and provenance). Trust is established via Ed25519 signatures and managed through a local SkillTrustStore that supports explicit allowlisting and Trust On First Use (TOFU) policies.

​
Skill Manifest (skill.toml)

The skill.toml file is the central metadata document for a skill. It defines the skill identity, tool entrypoints, and required capability grants.

​
Key Manifest Sections

​
Data Flow: Packaging to Execution

The following diagram illustrates how a skill.toml manifest is processed into runtime constraints. Manifest Processing Flow Sources: crates/palyra-skills/src/lib.rs#11-24, crates/palyra-skills/src/runtime.rs#21-23, crates/palyra-skills/examples/echo-http/skill.toml#1-45

​
Artifact Structure and Signing

A .palyra-skill file is a ZIP archive containing specific reserved paths for security metadata:
PathDescription
skill.tomlThe manifest defined by SKILL_MANIFEST_PATH crates/palyra-skills/src/constants.rs#15-15.
signature.jsonEd25519 signature of the manifest and all payload files crates/palyra-skills/src/constants.rs#15-15.
sbom.cdx.jsonCycloneDX SBOM for dependency auditing crates/palyra-skills/src/constants.rs#15-15.
provenance.jsonSLSA-style provenance data crates/palyra-skills/src/constants.rs#15-15.

​
Signing Implementation

The build_signed_skill_artifact function crates/palyra-skills/src/artifact.rs#11-11 (exported via crates/palyra-skills/src/lib.rs#11-11) performs the following:
  1. Hashes all modules and assets.
  2. Generates a signature using an Ed25519 private key crates/palyra-skills/src/manifest.rs#19-19.
  3. Packages the payload into a ZIP archive with the signature sidecar.
Sources: crates/palyra-skills/src/lib.rs#11-17, crates/palyra-skills/src/constants.rs#13-17

​
SkillTrustStore and TOFU Policy

The SkillTrustStore manages the public keys of publishers. It implements a Trust On First Use (TOFU) policy, where the first time a publisher’s skill is installed, their public key is “pinned” to the local store.

​
Trust Decisions

When verify_skill_artifact is called crates/palyra-skills/src/verify.rs#24-24, it returns a TrustDecision:
  • Allowlisted: The publisher’s key was already explicitly trusted in the store.
  • TofuPinned: The key matches a previously pinned key for this publisher.
  • TofuNewlyPinned: A new publisher was encountered, and their key was added to the store (only if allow_tofu is true).

​
Implementation in CLI

The palyra skills package verify command crates/palyra-cli/src/commands/skills.rs#106-128 demonstrates the interaction between the artifact bytes and the SkillTrustStore. Code Entity Space: Trust Verification Sources: crates/palyra-cli/src/commands/skills.rs#113-128, crates/palyra-skills/src/lib.rs#24-24, crates/palyra-skills/src/verify.rs#24-24

​
Security Auditing and Quarantine

Palyra performs both static and periodic audits of installed skills.

​
Static Security Audit

The audit_skill_artifact_security function crates/palyra-skills/src/audit.rs#12-12 enforces limits on Wasm modules before execution:

​
Skill Status and Quarantine

Skill health is tracked in the skill_status table within the JournalStore crates/palyra-cli/tests/skills_lifecycle.rs#129-140.
  • Quarantine: If a skill fails a periodic re-audit or its signature becomes invalid, it is marked as Quarantined.
  • Re-audit Loop: The palyra skills check command crates/palyra-cli/src/args/skills.rs#67-81 iterates through the skills_dir to verify the integrity of all installed artifacts against the SkillTrustStore.

​
Lifecycle State Machine

Skills move through states managed by the CLI and Daemon:
  1. Installed: Artifact extracted to the managed skills directory.
  2. Verified: Cryptographic signature matches a trusted publisher.
  3. Eligible: Meets version and protocol requirements.
  4. Quarantined: Disabled due to audit failure or manual operator override crates/palyra-cli/src/args/skills.rs#138-158.
Sources: crates/palyra-cli/src/output/skills.rs#104-113, crates/palyra-cli/src/args/skills.rs#138-181, crates/palyra-cli/tests/skills_lifecycle.rs#143-173

​
CLI Usage Reference

The palyra CLI provides a complete suite for managing the skill lifecycle:
CommandAction
skills package buildCreates a signed .palyra-skill from source crates/palyra-cli/src/commands/skills.rs#5-67.
skills installVerifies, pins (TOFU), and extracts an artifact crates/palyra-cli/src/args/skills.rs#9-34.
skills checkPerforms a bulk audit of all installed skills crates/palyra-cli/src/args/skills.rs#67-81.
skills quarantineManually disables a skill for a specific reason crates/palyra-cli/src/args/skills.rs#138-158.
skills verifyValidates a single artifact’s signature against the trust store crates/palyra-cli/src/args/skills.rs#106-120.
Sources: crates/palyra-cli/src/args/skills.rs#1-218, crates/palyra-cli/src/commands/skills.rs#1-144