| name | kit-author |
| description | Author Docker Sandboxes kits (agents and mixins) — spec.yaml schema, full lifecycle from sourcing through composition, injection, and runtime, plus distribution and TCK testing. |
| globs | ["**/spec.yaml","**/spec.yml","spec/**","tck/**"] |
Kit Author Skill
How to design, write, validate, and distribute kit artifacts (kind: sandbox and kind: mixin) for Docker Sandboxes. Kits are declarative — a spec.yaml plus an optional files/ tree — and the sbx engine translates them into container customizations at sandbox creation or kit add time.
Use this skill when:
- Writing a new kit (mixin or agent) from scratch
- Editing an existing kit in this repository
- Debugging why a kit's commands, files, network rules, or credentials are not taking effect
- Packaging, publishing, or consuming kits from OCI or git sources
- Reviewing kit PRs in this repository
References
Topics
Primary topics describe the v2 spec form (schemaVersion: "2"):
- Spec anatomy —
spec.yaml top-level fields (mixins, licenses, extends, locked, args) and every section (sandbox with image:/build: + entrypoint/command, agentInstructions with filename/content, credentials[] with apiKey/oauth and the scheme sugar, permissions.network, ports, environment, setup with install/startup/files, volumes, files/).
- Lifecycle — Sourcing → load (schemaVersion-forked decode) → normalize → validate → extends → compose → configure → hooks → container → runtime. What happens at each stage as observed by the kit author.
- Composition —
extends: inheritance vs --kit composition. Merge strategies per section, conflict rules, what "last wins" means.
- Authoring guide — Step-by-step recipes for a minimal mixin and a full sandbox kit. Where to put files. When to use
files/ vs setup.files.
- Bindings — The user-side
~/.config/sbx/credentials.yaml file: how kits and users split the credential contract.
- Image publishing — For a
kind: sandbox kit whose image this repo builds: drop a Dockerfile at the kit root and name it docker.io/sbx/<kit>-image:latest; CI discovers it, no workflow edit. Why sandbox.build: is not the answer yet, and the pre-publish window where the TCK cannot pull the image.
- Distribution — Local dir, OCI digests, git commit-SHA references. Strict pinning rule. Schema-version compatibility (v2 is a breaking grammar).
sbx kit push/pull/inspect/validate/delete.
- Testing — TCK suite, e2e under (mandatory locally — CI's e2e legs are skipped for fork PRs), manual verification, proving allow-list enforcement.
Legacy reference:
- v1 → v2 migration — Every v1 surface, its v2 equivalent, the
migrate-v1-to-v2.go script's coverage, and what to migrate by hand. The loader forks on schemaVersion; v2 is a clean grammar with no shims, while v1 keeps loading with deprecation warnings on Artifact.Warnings until the Phase 6 cutover.
