| name | sdk-designer |
| description | Design and build Workshop SDKs from scratch. USE FOR: creating new sdkcraft.yaml, hooks, plugs/slots, services, README, renovate.json, CI workflows; onboarding SDKs with VERSION files and version branches; iterating on SDK design with sdkcraft try/test. DO NOT USE FOR: workshop.yaml authoring (that's the consumer side); general shell scripting; unrelated CI/CD. |
| argument-hint | Describe what software the SDK should package and any known requirements |
SDK Designer
Design, build, test, and onboard Workshop SDKs.
When to Use
- Creating a new SDK from scratch for Workshop
- Onboarding an existing SDK repo (VERSION, renovate, CI, branches)
- Adding or modifying hooks, plugs, slots, or services
- Writing an SDK README
- Iterating on an SDK with
sdkcraft try / sdkcraft test
Procedure
Follow these phases in order. Each phase has a reference file with detailed
patterns, templates, and decision trees.
Phase 1 — Requirements Gathering
Before writing any file, determine:
- What software is being packaged (runtime, toolchain, service, AI agent)?
- How is it distributed upstream (tarball, npm, PyPI, apt, git repo, snap)?
- What needs to persist across workshop updates (caches, config, models)?
- Does it expose a network service (web UI, API server, debug port)?
- Does it need hardware access (GPU, camera, desktop)?
- Single base or multi-base? Does it need to work on multiple Ubuntu versions?
- Single arch or multi-arch? (amd64 only, or also arm64/riscv64?)
- What is the upstream version scheme? (semver, calver, codename?)
- What is the upstream datasource for Renovate? (npm, pypi, github-releases, node-version, golang-version?)
- How many version tracks? Single
latest channel, or multiple major/minor branches?
If information is missing or ambiguous, ask the user before proceeding.
Phase 2 — Design
Use the SDK Patterns Reference to make design
decisions:
- Choose the platform layout — single-base (
build-base) vs multi-base
(multiple ubuntu@ entries in platforms)
- Choose the parts strategy — plugin type (nil, dump, npm, rust, cmake,
make), source acquisition, override-pull/build
- Choose the interface layout — mount plugs for persistence, gpu/desktop/ssh
plugs for hardware, tunnel slots for services, mount slots for sharing
- Choose the hooks — which of setup-base, setup-project, check-health,
save-state, restore-state are needed
- Decide parts vs hooks — ship pre-built binaries in parts, or install
dynamically in hooks (apt packages → hooks; pinned binaries → parts)
Phase 3 — Implement
Create the SDK files in this order:
- sdkcraft.yaml — metadata, platforms, parts, plugs, slots
- hooks/ — setup-base, setup-project, check-health, etc.
- services/ — systemd unit files (if the SDK runs a daemon)
- VERSION — single line with the current upstream version
- renovate.json — Renovate config for automated version updates
- .github/workflows/ — build.yml, upload.yml (CI/CD)
- README.md — following the README Template
Use the sdkcraft.yaml Reference for
the exact field specifications and the
Hooks Reference for hook patterns.
Phase 4 — Build, Test, Iterate
Follow the Build-Test-Iterate Workflow
to validate the SDK locally before publishing:
sdkcraft try → workshop launch → workshop shell → verify → iterate
Phase 5 — Onboard for CI
Follow the Onboarding Reference for the git
branching and CI setup:
- Commit all files on main
- Remove VERSION from main
- Create version branch(es) from the commit with VERSION
- Remove Renovate workflows from version branches
- Push
Phase 6 — Write README
Use the README Template to write a README
that matches the established pattern across all SDKs.
