feat(skills): persist rich custom skill packages

[iamjr15]

Summary

• Persist complete custom skill packages instead of only SKILL.md and a narrow source subset.
• Preserve nested source, schemas, templates, references, and common binary assets across sandbox recreation.
• Keep package metadata tenant-scoped in Postgres/R2 while projecting an editable .cheatcode mirror into Daytona.

What's Included

Durable package contract

• Adds a backward-compatible v2 R2 package format with explicit UTF-8/base64 encodings.
• Enforces 128 files, 1 MiB per file, and 8 MiB decoded package limits.
• Excludes dependency, cache, lock, virtualenv, and generated-output trees.

Safe sandbox projection

• Adds a revision manifest for idempotent projection.
• Deletes only stale files previously owned by the package manifest.
• Preserves sandbox-local dependencies and generated output.

Creation and editing

• Canonicalizes SKILL.md after metadata upsert.
• Persists the complete package for native skill_create, runtime save, and Files-driven promotion.
• Extends the baked skill-authoring save command to support the same rich package contract.

Architecture

Postgres remains the authority for user-skill metadata. R2 stores the versioned package body. Each Agent Run projects that package into /workspace/.cheatcode/skills/<slug>/; the revision manifest makes restoration idempotent and bounds stale-file cleanup to managed files.

Decisions Made

Decision	Choice	Reasoning
Binary transport	Base64 per file	Works across Worker JSON, R2, and Daytona without corrupting bytes.
Mirror cleanup	Manifest-owned files only	Avoids deleting local dependencies or generated artifacts.
Package bounds	128 files / 1 MiB file / 8 MiB total	Supports rich skills while bounding memory, request, and storage abuse.
Compatibility	Read legacy v1 packages	Existing custom skills continue restoring without migration downtime.

Edge Cases Handled

Scenario	Handling
Deleted local mirror	Recreated from R2 on the next run.
Edited skill package	Full package is promoted, not only metadata or SKILL.md.
Corrupt mirror manifest	Ignored safely; no broad deletion occurs.
Duplicate or traversing paths	Rejected at the Zod trust boundary.
Binary asset	Validated, stored, restored, and written using base64.

How to Review

1. Start with apps/agent-worker/src/user-skill-packages.ts for the package contract.
2. Review agent-run-user-skills.ts and skill-runtime-managed-routes.ts for creation/restoration/promotion.
3. Review skills/skill-authoring/persist/save.ts for the baked sandbox save path.

Test Plan

• pnpm typecheck
• pnpm lint
• pnpm build
• Linux/AMD64 sandbox image build
• Direct UI creation of a six-file rich skill package
• Direct Files deletion followed by next-run R2 restoration
• Python helper and template invocation after restoration
• JSON schema validation and PNG byte-signature verification
• Clean browser-console reload (only development-key/HMR notices)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
cheatcode	Ignored		Jul 19, 2026 4:09pm