Skill Manifest (skill.toml)
Theskill.toml file is the central authority for a skill’s identity, capabilities, and security requirements. It is parsed using parse_manifest_toml crates/palyra-skills/src/manifest.rs#12-17.
Manifest Structure
A skill manifest is divided into several key sections:| Section | Purpose |
|---|---|
| Metadata | Defines skill_id, version, publisher, and name. |
| Entrypoints | Lists available tools that the agent can invoke. |
| Capabilities | Declares required access to the filesystem, network, and secrets. |
| Quotas | Sets execution limits (CPU fuel, memory, wall-clock time). |
| Compat | Defines minimum protocol and runtime version requirements. |
Capability Declarations
Skills operate in a zero-trust environment and must explicitly request every capability they intend to use:- Filesystem: Defined via
read_rootsandwrite_rootscrates/palyra-skills/examples/echo-http/skill.toml#24-27. - HTTP Egress: An allowlist of hostnames the skill may contact crates/palyra-skills/examples/echo-http/skill.toml#29-29.
- Secrets: Scoped access to keys stored in the Palyra Vault crates/palyra-skills/examples/echo-http/skill.toml#33-36.
- Wildcard Opt-in: Certain capabilities allow wildcards (e.g.,
*) only if thewildcard_opt_inflag is explicitly set crates/palyra-skills/src/manifest.rs#100-137.
Tool Entrypoints
Each tool in the[[entrypoints.tools]] array defines its interface via JSON Schema crates/palyra-skills/examples/echo-http/skill.toml#8-22.
- Risk Profile: Tools specify if they are
sensitiveor requireapprovalcrates/palyra-skills/examples/echo-http/skill.toml#14-14. - Namespacing: Tool IDs must be prefixed with the skill’s
publishername crates/palyra-skills/src/manifest.rs#74-79.
Skill Artifact Lifecycle
The lifecycle of a skill involves packaging, verification, auditing, and eventual execution or quarantine.1. Packaging and Signing
Skills are bundled into a.palyra-skill ZIP archive using build_signed_skill_artifact crates/palyra-skills/src/artifact.rs#11-11.
- Integrity: Every artifact includes an Ed25519 signature of the payload crates/palyra-skills/src/lib.rs#15-16.
- Supply Chain: Artifacts must include a CycloneDX SBOM and a provenance record crates/palyra-skills/src/manifest.rs#170-180.
2. Verification and Trust (SkillTrustStore)
Upon installation or check, the system invokesverify_skill_artifact crates/palyra-skills/src/verify.rs#24-24.
- SkillTrustStore: Manages trusted publisher keys. It supports “Trust On First Use” (TOFU) if enabled crates/palyra-cli/src/commands/skills.rs#117-127.
- Integrity Check: The system verifies the Ed25519 signature against the publisher’s public key.
3. Security Audit
Theaudit_skill_artifact_security function performs static analysis on the Wasm modules crates/palyra-skills/src/audit.rs#12-12.
- Limits: Checks against
DEFAULT_SKILL_AUDIT_MAX_MODULE_BYTESandMAX_EXPORTED_FUNCTIONScrates/palyra-skills/src/lib.rs#13-17. - Capability Mapping: Converts manifest declarations into internal
CapabilityGrantscrates/palyra-skills/src/runtime.rs#21-23.
4. Runtime States
A skill’s status is tracked in theskill_status table crates/palyra-cli/tests/skills_lifecycle.rs#130-140.
- Eligible: Passed all checks and is ready for use.
- Quarantined: Execution is blocked due to a failed audit, revoked trust, or manual operator intervention crates/palyra-cli/src/args/skills.rs#138-158.
Data Flow: Manifest to Runtime Policy
The following diagram bridges the “Natural Language” manifest declarations to the “Code Entities” that enforce them. Title: Skill Capability and Policy Resolution Sources: crates/palyra-skills/src/manifest.rs#12-17, crates/palyra-skills/src/runtime.rs#21-23, crates/palyra-skills/src/models.rs#1-100, crates/palyra-skills/examples/echo-http/skill.toml#1-45Lifecycle State Machine
The following diagram illustrates the transitions an artifact undergoes from a local build to an active system skill. Title: Skill Lifecycle Transitions Sources: crates/palyra-skills/src/verify.rs#24-24, crates/palyra-skills/src/audit.rs#12-12, crates/palyra-cli/src/commands/skills.rs#106-140, crates/palyra-cli/src/args/skills.rs#138-181Implementation Details
Trust Management
TheSkillTrustStore persists publisher identities and their associated public keys.
- TOFU: If
allow_tofuis enabled during verification, the first seen key for a publisher is pinned crates/palyra-cli/src/commands/skills.rs#138-140. - Integrity: The store itself is protected to prevent unauthorized modification of trusted keys crates/palyra-cli/src/commands/skills.rs#119-127.
Compatibility Checks
Before a skill is loaded,assert_runtime_compatibility ensures the daemon can support the skill’s requirements crates/palyra-skills/src/manifest.rs#149-168.
- Protocol Version: Compares
required_protocol_majoragainstCANONICAL_PROTOCOL_MAJORcrates/palyra-skills/src/manifest.rs#152-157. - Runtime Version: Checks
min_palyra_versionagainst the current build metadata crates/palyra-skills/src/manifest.rs#158-167.
Skill Inventory
TheSkillInventoryEntry struct provides a unified view of a skill’s metadata, installation state, and runtime eligibility crates/palyra-cli/src/output/skills.rs#42-55. This is used by the CLI and Dashboard to display the current state of the plugin system.
Sources: crates/palyra-skills/src/manifest.rs#149-168, crates/palyra-cli/src/commands/skills.rs#106-140, crates/palyra-cli/src/output/skills.rs#25-57, crates/palyra-skills/src/lib.rs#1-33