Skip to main content
This page details the lifecycle of a Palyra Skill, from its creation as a signed artifact to its execution under a zero-trust security model. It covers the manifest schema, the cryptographic trust store, the automated security audit pipeline, and the management of quarantine states.

​
Skill Artifact Format

A Palyra Skill is a cryptographically signed ZIP archive (typically with a .palyra-skill extension) containing the WASM modules, static assets, and security metadata required for execution crates/palyra-skills/src/constants.rs#15-16.

​
Manifest (skill.toml)

The skill.toml file is the central authority for a skill’s identity and capability requirements. It defines the tools exported to the LLM and the specific sandbox permissions required.
SectionDescription
metadataIncludes skill_id, version, publisher, and name crates/palyra-skills/src/models.rs.
entrypointsDefines the JSON schemas for tool inputs/outputs and risk levels crates/palyra-skills/examples/echo-http/skill.toml#8-22.
capabilitiesRequests specific sandbox holes: filesystem access, HTTP egress allowlists, and secret scopes crates/palyra-skills/examples/echo-http/skill.toml#24-41.
compatDefines required_protocol_major and min_palyra_version to ensure runtime stability crates/palyra-skills/src/manifest.rs#149-151.

​
Security Metadata

Every artifact must contain three critical security files:
  1. signature.json: An Ed25519 signature of the artifact payload, including the public key ID of the publisher crates/palyra-skills/src/constants.rs#15.
  2. sbom.cdx.json: A CycloneDX Software Bill of Materials for vulnerability scanning crates/palyra-skills/src/manifest.rs#170-176.
  3. provenance.json: Build-time attestation data crates/palyra-skills/src/constants.rs#13.

​
Packaging Data Flow

The palyra skills package build command orchestrates the assembly of these components. Sources: crates/palyra-cli/src/commands/skills.rs#5-67, crates/palyra-skills/src/manifest.rs#51-147

​
Trust Model and SkillTrustStore

Palyra employs a Trust on First Use (TOFU) model combined with explicit publisher allowlisting. Trust is managed by the SkillTrustStore, which persists public keys associated with specific publishers crates/palyra-skills/src/verify.rs#125-126.

​
Trust Decisions

When a skill is verified via verify_skill_artifact, the system returns one of three states:
  • Allowlisted: The publisher’s key was explicitly added to the trust store by an administrator.
  • TofuPinned: The publisher was previously seen, and the current signature matches the stored key.
  • TofuNewlyPinned: The publisher is new, and the key has been recorded for the first time (requires --allow-tofu flag) crates/palyra-cli/src/commands/skills.rs#136-140.

​
Verification Logic

Verification ensures that the artifact has not been tampered with and that the publisher is trusted. Sources: crates/palyra-skills/src/verify.rs#24-25, crates/palyra-cli/src/commands/skills.rs#117-127

​
Security Audit Pipeline

The audit_skill_artifact_security function performs static analysis on the skill’s WASM modules and manifest before execution is permitted crates/palyra-skills/src/lib.rs#12.

​
Audit Checks

  1. WASM Module Validation: Scans for suspicious imports/exports and ensures the module conforms to the palyra-plugins-sdk requirements.
  2. Resource Limits: Validates that requested fuel_budget and max_memory_bytes do not exceed system-wide security policies crates/palyra-skills/src/manifest.rs#138-145.
  3. Capability Sanitization: Rejects dangerous skill IDs (e.g., path traversal attempts) and ensures wildcard capabilities (like read_roots = ["*"]) are explicitly opted-in crates/palyra-skills/src/manifest.rs#149-194.
  4. Compatibility Check: Verifies the min_palyra_version against the current daemon version crates/palyra-skills/src/manifest.rs#149-168.
Sources: crates/palyra-skills/src/manifest.rs#51-147, crates/palyra-skills/src/tests.rs#149-170

​
Skill Lifecycle and Quarantine

Skills transition through several states stored in the JournalStore under the skill_status table crates/palyra-cli/tests/skills_lifecycle.rs#130-140.

​
Lifecycle States

  • Installed: Artifact is unpacked in the skills-managed directory.
  • Quarantined: The skill is disabled due to an audit failure or manual operator intervention.
  • Eligible: The skill has passed all audits and trust checks and is ready for LLM discovery.

​
Periodic Re-Audit

The daemon runs a background job (spawn_scheduler_loop) that periodically triggers re-audits of all installed skills. This ensures that if the daemon’s security policies are updated, existing skills are re-evaluated for compliance crates/palyra-cli/src/args/skills.rs#121-137.

​
CLI Management Commands

The palyra skills command group provides the primary interface for managing these states:
CommandAction
installUnpacks artifact, verifies trust, and runs initial audit crates/palyra-cli/src/args/skills.rs#9-34.
quarantineManually moves a skill to the quarantined state with a reason crates/palyra-cli/src/args/skills.rs#138-158.
checkManually triggers the audit and trust verification pipeline crates/palyra-cli/src/args/skills.rs#67-81.
listDisplays inventory with runtime_status and eligibility crates/palyra-cli/src/output/skills.rs#25-57.
Sources: crates/palyra-cli/src/args/skills.rs, crates/palyra-cli/src/output/skills.rs#85-119