palyra-skills crate provides the core logic for packaging, verifying, and managing the lifecycle of agent capabilities. It ensures that skills—which contain executable WASM modules and sensitive capability requests—are signed by trusted publishers and audited before execution.
Skill Manifest (skill.toml)
Every skill is defined by askill.toml manifest. This file declares the skill’s identity, its entrypoint tools, and the specific capabilities (filesystem, network, secrets) it requires from the host.
| Field | Description | Source |
|---|---|---|
skill_id | Unique dot-separated identifier (e.g., acme.echo_http). | crates/palyra-skills/src/manifest.rs#59-59 |
publisher | The entity responsible for the skill. Used for namespace validation. | crates/palyra-skills/src/manifest.rs#58-58 |
entrypoints.tools | List of tools exposed to the LLM, including JSON schemas and risk levels. | crates/palyra-skills/src/manifest.rs#65-69 |
capabilities | Requests for http_egress_allowlist, filesystem, and secrets. | crates/palyra-skills/src/manifest.rs#99-123 |
quotas | Resource limits: fuel_budget, max_memory_bytes, and wall_clock_timeout_ms. | crates/palyra-skills/src/manifest.rs#138-145 |
- Tool IDs must be namespaced with the publisher name (e.g.,
acme.echo) crates/palyra-skills/src/manifest.rs#74-79. - Wildcards in capabilities (e.g.,
read_roots = ["skills/*"]) require an explicitwildcard_opt_inflag crates/palyra-skills/src/manifest.rs#100-107. - Runtime compatibility is checked against
min_palyra_versionandrequired_protocol_majorcrates/palyra-skills/src/manifest.rs#149-168.
SkillArtifact Packaging and Signing
A.palyra-skill artifact is a signed ZIP archive containing the manifest, WASM modules, assets, and security metadata (SBOM and Provenance).
The Build Process
- Gather Inputs: Manifest TOML, WASM bytes, static assets, CycloneDX SBOM, and SLSA provenance crates/palyra-cli/src/commands/skills.rs#20-51.
- Sign: The
build_signed_skill_artifactfunction uses an Ed25519 key to sign the SHA-256 hash of the payload crates/palyra-skills/src/lib.rs#11-11. - Bundle: Files are packed into a ZIP with standard paths:
skill.toml,_palyra/signature.json,_palyra/sbom.cdx.json, and_palyra/provenance.jsoncrates/palyra-skills/src/lib.rs#13-17.
Trust Store and TOFU
TheSkillTrustStore manages the public keys of trusted publishers. It supports Trust On First Use (TOFU) for local development or unmanaged environments.
- Verification:
verify_skill_artifactchecks the signature against theSkillTrustStore. If the publisher is unknown andallow_tofuis enabled, the key is pinned to that publisher crates/palyra-cli/src/commands/skills.rs#125-126. - Trust Decisions: Decisions are categorized as
Allowlisted(explicitly trusted),TofuPinned(already seen), orTofuNewlyPinnedcrates/palyra-cli/src/commands/skills.rs#136-140. - Integrity: The trust store is typically stored in a JSON file and loaded/saved with integrity checks during the install/verify flow crates/palyra-cli/src/commands/skills.rs#119-127.
Lifecycle Management
Skills move through various states managed by the CLI and thepalyrad daemon.
1. Installation
Theskills install command validates the artifact, verifies the signature, and extracts the contents to the managed skills directory crates/palyra-cli/src/args/skills.rs#9-34. It also registers the skill’s initial status in the JournalStore crates/palyra-cli/tests/skills_lifecycle.rs#186-197.
2. Periodic Reaudit
The daemon runs aPeriodicSkillReaudit task (via the Cron subsystem) to ensure installed skills still meet security policies.
- WASM Audit: Checks for excessive exported functions or module size crates/palyra-skills/src/lib.rs#13-15.
- Policy Check: Validates that the skill’s requested capabilities align with the current
palyra-policycrates/palyra-skills/src/lib.rs#21-23.
3. Quarantine State
If a skill fails an audit or is manually flagged, it is moved to aQuarantine state.
- Effect: Quarantined skills cannot be loaded into the WASM runtime.
- Triggers: Signature mismatch, failed security audit, or operator command
skills quarantinecrates/palyra-cli/src/args/skills.rs#138-158. - Storage: Status is persisted in the
skill_statustable of the SQLiteJournalStorecrates/palyra-cli/tests/skills_lifecycle.rs#125-175.
Security Auditing
Theaudit_skill_artifact_security function performs static analysis on the skill artifact before it is allowed to run.
- Module Limits: Enforces
DEFAULT_SKILL_AUDIT_MAX_MODULE_BYTESandDEFAULT_SKILL_AUDIT_MAX_EXPORTED_FUNCTIONScrates/palyra-skills/src/lib.rs#13-14. - Capability Mapping: Converts manifest requests into
CapabilityGrantsandPolicyRequestscrates/palyra-skills/src/lib.rs#21-23. - Check Results: The CLI
skills checkcommand aggregates these audits, reportingtrust_accepted,audit_passed, andquarantine_requiredcrates/palyra-cli/src/output/skills.rs#104-113.