Skills

Custom Skills are versioned zip bundles stored in S3-compatible storage. An Agent or Session resolves every reference to an immutable Skill Version before execution.

POST   /v1/skills
GET    /v1/skills
GET    /v1/skills/{skill_id}
DELETE /v1/skills/{skill_id}
POST   /v1/skills/{skill_id}/versions
GET    /v1/skills/{skill_id}/versions
GET    /v1/skills/{skill_id}/versions/{version}
GET    /v1/skills/{skill_id}/versions/{version}/content
DELETE /v1/skills/{skill_id}/versions/{version}

Skills routes require configured Files storage and Mango's standard bearer authentication. Create and Version uploads require multipart/form-data.

If writing an archive fails and object cleanup also fails, Mango retains the hidden Version record so startup and periodic reconciliation can retry deletion after storage recovers. A failed first upload also retains its hidden parent Skill until cleanup completes. Existing ready Versions remain available. Uploads use one-minute internal database leases renewed every 20 seconds; cleanup claims only ended or expired uploads and retries every 20 seconds. Completion checks ownership, including a unique archive object key for each upload attempt, so an old writer cannot affect a reused time-based Version. Lease loss cancels the upload. Independent object cleanup guards survive removal or reuse of a Version's metadata. Unknown remote writes keep a guard until writer completion can be confirmed. See the recovery design.

Bundle contract

Create and Version uploads accept a zip archive or path-qualified multipart files smaller than 30 MB. A bundle contains one top-level directory and a root SKILL.md; validation rejects traversal, absolute paths, links, duplicate paths, and invalid frontmatter metadata.

Every Version response includes size_bytes and checksum_sha256 for the exact canonical zip returned by its content endpoint. Workers must verify both before using the archive; transport success alone is not an integrity check. Mango also persists the exact expanded size of each validated canonical bundle and uses it for Session admission. Negative or unknown-size metadata is rejected. Earlier development databases that used unknown-size records must be rebuilt with the current schema; they are not a supported migration path.

Agent and Session responses expose typed custom references with type, skill_id, and a concrete version. Agent requests use the documented custom reference. An omitted Version or latest is replaced by a concrete ready Version before the Agent Version or Session snapshot is stored. Active Agent and Session pins prevent deleting an archive that is still executable.

Runtime behavior

Self-hosted worker Sessions initially expose only Skill name, description, and instruction path metadata. A private Skill dispatcher selects the immutable bundle, returns Launching skill: <name>, and injects the complete main instruction file on demand. Supporting files and scripts remain available through ordinary sandbox tools. Docker presents a read-only bind mount; remote adapters present a permission-hardened local copy and preserve the canonical archive in Mango storage.

Primary and self Agent bundles use /workspace/skills/<name>/; external roster Agents use isolated namespaces below /workspace/skills/.agents/.

For self-hosted Environments, the Go Environment Worker downloads the frozen primary and roster Agent pins before starting tool dispatch. Primary Skills use <workdir>/skills/<name> and external roster Agents use the same stable scoped layout as the Agent loop. The worker accepts only Mango's canonical zip shape, bounds per-archive and whole-Session compressed/expanded content and file count, rejects path escapes and non-regular members, and atomically publishes one symlink-safe Session tree. It removes that tree when the Work item ends. Model-visible paths are relative skills/... paths rooted at that workdir, so a launcher may choose a location other than /workspace. Permanent validation failures durably terminate the Session; temporary retrieval failures remain eligible for Work lease reclaim.

External managed catalogs and repository auto-loading are not implemented. Session overrides are applied before Skill admission; Skills storage and Agent definitions do not depend on the operator's launcher implementation.

See Environment Work for the external worker boundary and Sandboxes for worker-owned preparation.