palyra-skills crate defines the standard for packaging, verifying, and establishing trust for skill artifacts. A skill is a portable unit of capability containing WASM modules, static assets, a manifest, and cryptographic signatures. The system uses an Ed25519-based signing model combined with Trust-on-First-Use (TOFU) or explicit allowlisting to ensure that only authorized code executes within the daemon.
Skill Artifact Format (.palyra-skill)
A.palyra-skill file is a ZIP-compressed archive with a strict internal structure. It bundles execution logic (WASM), configuration (Manifest), and supply-chain metadata (SBOM/Provenance).
Archive Structure
| Path | Description |
|---|---|
skill.toml | The primary manifest defining metadata and capabilities. |
signature.json | Ed25519 signature of the artifact payload. |
sbom.cdx.json | CycloneDX Software Bill of Materials. |
provenance.json | SLSA-style build provenance metadata. |
modules/*.wasm | Compiled WebAssembly modules. |
assets/**/* | Static assets (templates, icons, data files). |
Packaging Data Flow
Thebuild_signed_skill_artifact function orchestrates the creation of an artifact by collecting files, validating the manifest, and signing the resulting payload.
Sources: crates/palyra-cli/src/commands/skills.rs#59-67, crates/palyra-skills/src/lib.rs#11-12
Manifest Schema and Validation
Theskill.toml manifest is the source of truth for a skill’s identity and required permissions. It is parsed into a SkillManifest struct crates/palyra-skills/src/models.rs#1-20.
Key Manifest Sections
- Identity:
skill_id,publisher, andversion. Skill IDs must be namespaced by the publisher (e.g.,acme.echo_http) crates/palyra-skills/src/manifest.rs#74-79. - Entrypoints: Defines the tools exposed to the LLM, including their JSON schemas and risk profiles crates/palyra-skills/src/manifest.rs#65-98.
- Capabilities: Fine-grained access requests for filesystem roots, HTTP egress hosts, and secret scopes crates/palyra-skills/src/manifest.rs#99-137.
- Quotas: Execution limits such as
wall_clock_timeout_ms,fuel_budget, andmax_memory_bytescrates/palyra-skills/src/manifest.rs#138-145.
Trust and Verification
Palyra employs a cryptographic trust model to prevent the execution of tampered or unauthorized skills.Ed25519 Signing
Artifacts are signed using 32-byte Ed25519 private keys. The signature covers the SHA-256 hash of the payload (everything except the signature itself). Theverify_skill_artifact function validates this signature before checking the trust store crates/palyra-skills/src/verify.rs#1-30.
Trust Store and TOFU
TheSkillTrustStore manages known publishers and their public keys.
- Allowlisted: The publisher and key are explicitly trusted in the configuration.
- TOFU (Trust-on-First-Use): If
allow_tofuis enabled, the first time a publisher’s key is encountered, it is “pinned” to the trust store. Subsequent versions of skills from that publisher must use the same key crates/palyra-cli/src/commands/skills.rs#124-140.
Verification Lifecycle
Sources: crates/palyra-skills/src/verify.rs#25-50, crates/palyra-cli/src/commands/skills.rs#112-127Security Auditing and Quarantine
Before a skill is promoted from installation to active execution, it undergoes a security audit and may be placed in a quarantine lifecycle.Static Analysis (Audit)
Theaudit_skill_artifact_security function performs static checks on the artifact crates/palyra-skills/src/audit.rs#1-15:
- Module Size: Ensures WASM modules do not exceed
DEFAULT_SKILL_AUDIT_MAX_MODULE_BYTEScrates/palyra-skills/src/lib.rs#13-15. - Export Limits: Restricts the number of exported functions to prevent excessive attack surface.
- Wildcard Check: Identifies skills requesting wildcard permissions (e.g.,
*for HTTP egress) which require manual operator review crates/palyra-skills/src/manifest.rs#167-183.
Quarantine Lifecycle
Skills can be moved through different states managed by theSkillsCommand crates/palyra-cli/src/args/skills.rs#4-182:
- Quarantined: The skill is installed but disabled due to failed audit, missing trust, or manual operator action.
- Enabled: The operator has explicitly reviewed and authorized the skill for execution.
- Removed: The skill artifact and associated metadata are purged from the
skills_dir.