design-sdk

---
name: design-sdk
description: Design, build, and publish Workshop SDKs with sdkcraft — interview and research the software, generate sdkcraft.yaml with hooks and spread smoke tests, iterate via sdkcraft try plus workshop refresh, write the README, then onboard the SDK repo with version branches, CI workflows, and renovate. Use when creating or maintaining a publisher-side (Store) SDK from its own repository — "design an SDK for X", "create an sdkcraft.yaml", "set up renovate and CI for my SDK repo".
argument-hint: "[new|design|generate|iterate|test|readme|onboard|publish] [software or SDK repo]"
---

<!-- SPDX-License-Identifier: GPL-3.0-only -->
<!-- Copyright 2026 Canonical Ltd. -->

<essential_principles>
Five rules that always apply to designing SDKs. Every workflow assumes them.

1. **Interview first; design from named patterns.** Before writing any file,
   settle: what software — and whether it is a standalone application or a
   library/environment other SDKs consume — how upstream distributes it,
   what must persist,
   whether it serves a network service, hardware needs, bases and
   architectures, version scheme, renovate datasource, track count. Every
   proposed construct maps to a pattern in
   `references/reference-sdk-patterns.md` or
   `references/design-best-practices.md` — never an invented field or flag.
   A pattern whose catalog entry is marked evolving (hermes — the Python
   mechanism SDKcraft's maintainers call unsettled) is recommended WITH that
   caveat, as the current exemplar to prove in the try loop, never as
   settled convention. Every question carries a recommendation ("Options:
   A / B — Recommendation: A, because <evidence>"), batched into one
   message.

2. **Copy, don't synthesize, YAML.** Shapes come from `templates/` here, the
   reference SDKs, and `../use-workshop/templates/` — never from memory.
   Schema facts come from `references/sdkcraft-definition.md`; if a key is
   not there, it does not exist. `stage-packages`/`stage-snaps` are
   hard-rejected — apt work belongs in `setup-base`. There is no `apps:` or
   `services:` key — daemons ship as a dump part plus a systemd user unit.

3. **Nothing ships untried.** Every generated or edited SDK goes through the
   try loop — `sdkcraft clean && sdkcraft try`, consume as `try-<NAME>` in a
   test workshop, `workshop launch --verbose --wait-on-error` or
   `workshop refresh` — and lands with spread smoke tests that prove real
   functionality, before it is called done.

4. **The hook contract is fixed.** Exactly five hooks; `setup-project` runs
   as the `workshop` user, all others as root. Per hook kind, SDKs run
   system → user-listed in definition order → sketch, with no dependency
   resolution — list order IS the dependency mechanism. A refresh reuses the
   post-`setup-base` snapshot; state crosses a refresh only via
   `$SDK_STATE_DIR` or a mount. `check-health` must test real functionality
   and report via `workshopctl set-health` within 5 seconds per attempt.

5. **Interfaces follow policy, and the README says so.** Choose by the
   heuristic: mount = persistence/sharing, gpu = acceleration, tunnel =
   network service, ssh-agent = remote auth, secret = a credential the user
   supplies at runtime (0.9.8+; never a file in a mount, never in the SDK). Know which connections happen
   automatically (gpu; mount to the system slot; qualifying tunnels) and
   which need `connections:` or `workshop connect`. When several slots are
   eligible for one plug, order is not guaranteed — write `connections:`.
   The README is concise, follows the template, and states exactly the
   manual wiring a consumer must do.
</essential_principles>

<docs>
Authoritative readable docs:
- Base URL: `https://ubuntu.com/workshop/docs/`
  Per-file `<source_docs>` blocks list paths RELATIVE to this base, with `.md` suffixes (e.g. `reference/cli/workshop.md`). Fetch by concatenating `<base>` + relative path → `https://ubuntu.com/workshop/docs/reference/cli/workshop.md`. The CLI reference is four combined pages — `workshop.md`, `sdk.md`, `sdkcraft.md`, `workshopctl.md` — each holding every subcommand of that tool as a section; there are no per-subcommand pages.
- Whole-tree fallback: `<base>/llms.txt` (index) and `<base>/llms-full.txt` (the full docs tree concatenated). Load one when a specific relative page isn't enough (e.g., the user asks something the skill doesn't directly cover and you want to scan the full docs tree). The docs are also served through the Context7 MCP server for agents that have it.

The base URL may change. It is recorded HERE only — every other file lists relative paths so a single edit re-points the whole skill. Do not embed local `docs/` paths in any file under this skill; the docs site is the source of truth.
</docs>

<sibling_skill>
This skill depends on its sibling `use-workshop` (shipped in the same
plugin): `<required_reading>` blocks cite `../use-workshop/references/*` by
relative path, and consumer-side operating questions (running, refreshing,
debugging a workshop someone uses) route there. The other sibling,
`onboard-workshop`, owns deriving a workshop definition FOR an application
repo — "set up a workshop for this repo" is its territory, not an SDK
design. If the siblings are not installed (single-skill vendoring), fetch
the equivalent docs pages via `<docs>` instead — e.g.
`explanation/interfaces/plugs-and-slots.md` for connection policy,
`reference/cli/workshop.md` for command signatures — and tell the user the
plugin is meant to be installed whole.
</sibling_skill>

<intake>
Pick the matching path (subcommand — what the user wants):

1. `new` — Design and build an SDK end-to-end ("design an SDK for X")
2. `design` — Design only; stop at the proposal, write no files
3. `generate` — Materialize an approved design as files
4. `iterate` — Run or debug the try-refresh loop on an existing SDK source
5. `test` — Add or run spread smoke tests (`sdkcraft test`)
6. `readme` — Write the SDK README from the template
7. `onboard` — Set up the SDK repo: version branches, CI workflows, renovate
8. `publish` — SDK Store: register, upload, release, credentials
9. Consumer-side workshop work (run/refresh/debug, workshop.yaml, in-project
   SDKs) — not this skill; use `use-workshop` or `onboard-workshop`

**If invoked with $ARGUMENTS, route directly without asking.** Arguments
whose first token is not a recognized subcommand route to the `new` chain
with the whole argument string as the software description — with one
exception. A sibling's subcommand (`init`, `run`, `actions`, `connect`,
`worktrees`, `ide`, `multi`, `debug`, `purge` — `use-workshop`'s verbs), or
any request that is a sibling's territory (a consumer-side workshop
operation, onboarding an app repo), is HANDED OFF per the sibling rows in
`<routing>`: name the sibling skill and stop — do not improvise `workshop`
operations here even though the borrowed references describe them. The
carve-out: anything involving an SDK under development stays HERE — a
failed launch/refresh while applying a `try-<NAME>` SDK, a hook you are
authoring, a test workshop from the iterate loop — that is `iterate`, not
a hand-off.
</intake>

<routing>
| Subcommand | User intent (paraphrases) | Path |
|------------|---------------------------|------|
| `new` | "design an SDK for X", "create an SDK for X", "package X as a Workshop SDK", "make X installable in workshops" | `workflows/design-sdk.md` → `workflows/generate-sdk.md` → `workflows/iterate-and-debug.md` → `workflows/write-spread-tests.md` → `workflows/write-readme.md` |
| `design` | "what would an SDK for X look like", "just the design", "don't write files yet", "propose the SDK structure" | `workflows/design-sdk.md`, STOP at the Design Proposal |
| `generate` | "write the files we agreed", "generate the sdkcraft.yaml", "apply the design" | `workflows/generate-sdk.md` → `workflows/iterate-and-debug.md` |
| `iterate` | "sdkcraft try fails", "the hook errors on refresh", "iterate on my SDK", "pack fails", "the SDK doesn't come up healthy" | `workflows/iterate-and-debug.md` |
| `test` | "add spread tests", "smoke tests for the SDK", "sdkcraft test", "prove the SDK works in CI" | `workflows/write-spread-tests.md` |
| `readme` | "write the SDK README", "document the SDK" | `workflows/write-readme.md` |
| `onboard` | "onboard my SDK repo", "set up renovate", "version branches", "automate SDK releases", "CI for my SDK repo" | `workflows/onboard-repo.md` |
| `publish` | "publish to the SDK Store", "register the name", "upload a revision", "release to stable", "store credentials", "flip to production" | `workflows/publish-store.md` |
| — | Consumer side: run/refresh/connect/debug a workshop, edit workshop.yaml, author an in-project SDK | `use-workshop` skill — name it and STOP: at most one pointer command, never an operations walkthrough. The borrowed sibling references are in context for authoring test workshops in the iterate loop, NOT for answering consumer questions — "the cheatsheet is loaded" is not a reason to answer here |
| — | "set up a workshop for this repo", "workshop-ify this project" (an app repo, not an SDK) | `onboard-workshop` skill |

The `new` chain stops after `write-readme.md` unless the user asked for repo
automation — then continue into `workflows/onboard-repo.md`. Any chain can
be cut short with "stop after <stage>".
</routing>

<reference_index>
Own references (in `references/`):

| File | Use for |
|------|---------|
| `sdkcraft-definition.md` | sdkcraft.yaml anatomy: fields, platform layouts, parts, the interface union, reserved names, pack-time linters |
| `design-best-practices.md` | Parts-vs-hooks doctrine, setup-base vs setup-project, env vars, the systemd service pattern, health checks, SDK dependencies |
| `runtime-hooks.md` | Five-hook contract: execution context, per-operation order, cross-SDK ordering, snapshot semantics, set-health, per-hook patterns |
| `reference-sdk-patterns.md` | Exemplar catalog mined from the reference SDKs — named shapes to copy |
| `spread-tests.md` | `sdkcraft test` mechanics, tests/ layout, the smoke-test menu |
| `onboarding-ci.md` | Branching model, sdkcraft-actions workflows, renovate.json anatomy, the onboarding git sequence |
| `store-publishing.md` | login/register/upload/release, channels and tracks, credentials |
| `secrets.md` | `secret` plugs (0.9.8+): declaring one, the delivery patterns (credential helper, wrapper, systemd `LoadCredential=`), failure handling, exposure, testing |
| `anti-patterns.md` | Design and generation traps (and the right alternative) |

Borrowed from the sibling (load by relative path):

| File | Use for |
|------|---------|
| `../use-workshop/references/interfaces.md` | Interface semantics; auto vs manual connect; wiring decision tree |
| `../use-workshop/references/command-cheatsheet.md` | Verbatim `workshop`/`sdk` command signatures for the try loop |
| `../use-workshop/references/async-and-recovery.md` | Change/task model; `--wait-on-error`/`--continue`/`--abort` |
| `../use-workshop/references/definition-file.md` | workshop.yaml anatomy for authoring test workshops |
| `../use-workshop/references/sdk-types.md` | SDK kinds; where try SDKs fit |
| `../use-workshop/references/secrets.md` | The consumer's side of a `secret` plug — store, slot, connect, errors — for the README and test workshops |
</reference_index>

<workflows_index>
| Workflow | Subcommand | Purpose |
|----------|------------|---------|
| `design-sdk.md` | `design` | Interview → verify upstream facts → match patterns → Design Proposal, STOP for approval |
| `generate-sdk.md` | `generate` | Materialize the proposal: sdkcraft.yaml, hooks, services, tests scaffold, VERSION |
| `iterate-and-debug.md` | `iterate` | The try-refresh loop until the SDK comes up healthy |
| `write-spread-tests.md` | `test` | Encode manual verifications as spread jobs; run `sdkcraft test` |
| `write-readme.md` | `readme` | Concise README from the template, connection story included |
| `onboard-repo.md` | `onboard` | VERSION, renovate.json, CI workflows, the version-branch git sequence |
| `publish-store.md` | `publish` | Store registration, upload, release, credentials, staging→prod flip |
</workflows_index>

<verification_loop>
After ANY mutating workshop command, run the triplet and report it:

```
workshop changes              # find latest change ID
workshop tasks <ID>           # confirm Status: Done (or surface the failure)
workshop info [<workshop>]    # confirm final status (Ready / Waiting / Error)
```

Designing adds two checks on top:
- After every `sdkcraft try`, confirm from its output that the try artifact
  landed, and that the test workshop's `sdks:` list consumes `try-<NAME>`
  before launching or refreshing — while any `connections:` entry names the
  bare `<NAME>` (`<NAME>:<slot>`; the prefix is for `sdks:` only).
- After `sdkcraft test`, report the result per job (job name → pass/fail),
  never as a bare exit status.

Report back as: **"Change <ID>: <status>. Workshop status: <Ready|...>.
Notes: <...>."**
</verification_loop>

<success_criteria>
A run of this skill is complete when:
- [ ] The request was routed to exactly one path (or stopped at
      `<out_of_scope>` with a handoff).
- [ ] That workflow's `<required_reading>` references were loaded first.
- [ ] A Design Proposal was delivered and approved before any file was
      generated.
- [ ] Every generated or edited SDK went through the try loop and came up
      healthy (`workshop info` reports `status: ready`).
- [ ] Spread tests cover launch plus the SDK's primary functionality.
- [ ] The README matches the template with no verbosity on connections or
      implementation details.
- [ ] An onboarding left `main` as the template branch (never VERSION) and
      every version branch carrying its own VERSION commit without the
      renovate workflows, with `LONG_TERM_BRANCHES` set or named as a
      remaining manual step.
- [ ] Every mutating workshop command was followed by the verification
      triplet.
</success_criteria>

<out_of_scope>
- Consumer-side operations — running, refreshing, connecting, debugging a
  workshop, editing a workshop definition someone uses, parallel worktrees →
  the `use-workshop` skill. Authoring test workshops that consume
  `try-<NAME>` during the iterate loop IS in scope here.
- Onboarding an application repo into Workshop ("set up a workshop for this
  repo") → the `onboard-workshop` skill. This skill packages software AS an
  SDK others install; it does not derive workshop definitions from app
  toolchains.
- Authoring in-project SDKs (`.workshop/<name>/sdk.yaml`) → `use-workshop`
  (`workflows/author-in-project-sdk.md` there). Promoting one to a
  publishable SDK starts with `workflows/design-sdk.md` here.
- Interactive `workshop sketch-sdk` flows. They require an `$EDITOR` session
  and cannot be driven by an agent. Acknowledge the command as vocabulary,
  name the constraint, and iterate by editing the SDK source plus the try
  loop instead (`workflows/iterate-and-debug.md`).
- `workshopctl` beyond its two SDK-side uses. IN scope: emitting
  `workshopctl set-health <okay|waiting|error> [<message>]` *inside* a
  `check-health` hook you are authoring (`references/runtime-hooks.md`),
  and calling `workshopctl get-secret <SDK>.<PLUG>` from an SDK's wrapper,
  credential-helper setting, or (via `LoadCredential=`) systemd unit
  (`references/secrets.md`). Anything else about it is a docs pointer.
</out_of_scope>

<self_healing>
After completing a run, check whether any issue you hit came from a gap in
this skill's instructions, references, or workflows.

What qualifies for a skill update:
- Tooling drift (an `sdkcraft`/`workshop` subcommand or flag changed, was
  added, or was removed)
- Structural problems (a referenced file is missing, a routing row points at
  the wrong workflow, a dangling cross-reference)
- A missing edge case or failure mode that caused a wrong design or an
  incomplete iteration loop
- An incorrect assumption about the environment (snap layout, LXD behavior,
  docs URLs, Store behavior)

Off-limits for self-edits: `<essential_principles>`, the semantics of the
`<routing>` table, `<out_of_scope>` fencing, and anything under `tests/` —
skill changes are eval-gated and belong in a reviewed PR.

How to update:
1. Report the gap: which file, what is wrong, and the proposed change quoted
   in full.
2. If running from a writable checkout of the skill repo, apply the change
   with Edit/Write after the user confirms. Otherwise (normal case — the
   skill is installed read-only via the plugin marketplace and also consumed
   by GitHub Copilot), propose the change as a PR against
   `canonical/use-workshop-skill`.
3. Preserve conventions: section order, XML tagging, the `<UPPERCASE-NAME>`
   placeholder style, and relative docs paths resolved via `<docs>`.
</self_healing>

<style>
- When emitting YAML, copy from a template under `templates/` — do not
  synthesize from memory.
- Quote numeric-looking versions and channels (`version: "1.0"`,
  `"24/stable"`).
- Ground every `sdkcraft` invocation in `reference/cli/sdkcraft.md` (via
  `<docs>`) and every `workshop` invocation in the sibling cheatsheet — if a
  flag isn't listed, it doesn't exist.
- Prefer the reference SDKs' vocabulary for part and plug names (`cache`,
  `models`, `venv`) over invented ones.
- Hooks in a publishable SDK must be executable (`chmod +x`) and
  shellcheck-clean — both are enforced at pack time, unlike in-project SDKs.
- Keep the design phase read-only; the first write happens in
  `generate-sdk.md` after approval.
</style>

• SKILL.md 17 KB
• references/anti-patterns.md 7 KB
• references/design-best-practices.md 9 KB
• references/onboarding-ci.md 8 KB
• references/reference-sdk-patterns.md 10 KB
• references/runtime-hooks.md 7 KB
• references/sdkcraft-definition.md 11 KB
• references/secrets.md 9 KB
• references/spread-tests.md 6 KB
• references/store-publishing.md 4 KB
• templates/README-template.md 3 KB
• templates/renovate.json 1 KB
• templates/test-workshop.yaml 1 KB
• templates/binary/sdkcraft.yaml 1 KB
• templates/github-workflows/build.yml 1 KB
• templates/github-workflows/forward-port.yml 1 KB
• templates/github-workflows/renovate-check.yml 1 KB
• templates/github-workflows/renovate.yml 1 KB
• templates/github-workflows/upload.yml 1 KB
• templates/hooks/check-health 1 KB
• templates/hooks/restore-state 1 KB
• templates/hooks/save-state 1 KB
• templates/hooks/setup-base 1 KB
• templates/hooks/setup-project 1 KB
• templates/minimal/sdkcraft.yaml 1 KB
• templates/service/sdkcraft.yaml 2 KB
• templates/service/services/app.service 1 KB
• templates/tests/spread.yaml 1 KB
• templates/tests/main/launch/task.yaml 1 KB
• templates/tests/main/launch/workshop.yaml.in 1 KB
• tests/BASELINE.md 21 KB
• tests/Makefile 5 KB
• tests/README.md 2 KB
• tests/prompt.json 1 KB
• tests/promptfooconfig.yaml 3 KB
• tests/agentic/promptfooconfig.yaml 2 KB
• tests/agentic/fixtures/broken-echoer/VERSION 1 KB
• tests/agentic/fixtures/broken-echoer/sdkcraft.yaml 1 KB
• tests/agentic/fixtures/broken-echoer/bin/echoer 1 KB
• tests/agentic/fixtures/broken-echoer/hooks/setup-base 1 KB
• tests/agentic/fixtures/hello-sdk-repo/README.md 1 KB
• tests/agentic/fixtures/hello-sdk-repo/sdkcraft.yaml 1 KB
• tests/agentic/fixtures/hello-sdk-repo/hooks/setup-base 1 KB
• tests/agentic/fixtures/hello-tool/README.md 1 KB
• tests/agentic/fixtures/hello-tool/VERSION 1 KB
• tests/agentic/fixtures/hello-tool/bin/hello-tool 1 KB
• tests/agentic/tasks/design-pack-mini.yaml 4 KB
• tests/agentic/tasks/onboard-sdk-repo.yaml 4 KB
• tests/agentic/tasks/try-verify.yaml 2 KB
• tests/reconstruction/README.md 3 KB
• tests/reconstruction/compare-sdk.py 12 KB
• tests/reconstruction/promptfooconfig.yaml 3 KB
• tests/reconstruction/provider-design-cli.js 5 KB
• tests/reconstruction/run-sdk-reconstruction.sh 11 KB
• tests/reconstruction/expectations/claude-code-sdk.json 1 KB
• tests/reconstruction/expectations/ollama-sdk.json 1 KB
• tests/reconstruction/expectations/uv-sdk.json 1 KB
• tests/results/2026-08-24-agentic-claude-sonnet-4-6.json 3 KB
• tests/results/2026-08-24-design-reconstruction-3sdk.md 3 KB
• tests/results/2026-08-24-design-reconstruction-ollama-claude-code.json 1 KB
• tests/results/2026-08-24-design-reconstruction-uv.json 1 KB
• tests/results/2026-08-24-routing-claude-cli-claude-sonnet-4-6.json 12 KB
• tests/results/2026-08-25-routing-claude-cli-claude-sonnet-4-6.json 12 KB
• tests/results/2026-08-31-routing-claude-cli-claude-sonnet-4-6.json 13 KB
• tests/results/2026-09-01-routing-claude-cli-claude-sonnet-4-6.json 11 KB
• tests/results/2026-09-22-agentic-claude-sonnet-4-6.json 3 KB
• tests/results/2026-09-22-routing-claude-cli-claude-sonnet-4-6.json 13 KB
• tests/results/2026-10-06-agentic-claude-sonnet-4-6.json 3 KB
• tests/results/2026-10-06-routing-claude-cli-claude-sonnet-4-6.json 12 KB
• tests/results/2026-10-19-routing-claude-cli-claude-sonnet-4-6.json 13 KB
• tests/results/2026-10-20-agentic-claude-sonnet-4-6.json 3 KB
• tests/results/2026-10-20-routing-claude-cli-claude-sonnet-4-6.json 15 KB
• tests/results/2026-10-20-routing-copilot-gpt-6.1-sol.json 17 KB
• tests/results/2026-10-23-routing-claude-cli-claude-sonnet-4-6.json 15 KB
• tests/results/2026-10-23-routing-copilot-gpt-6.1-sol.json 14 KB
• tests/results/2026-10-24-agentic-claude-sonnet-4-6.json 3 KB
• tests/scenarios/design.yaml 11 KB
• tests/scenarios/dispatch.yaml 5 KB
• tests/scenarios/generate.yaml 6 KB
• tests/scenarios/honesty-bestpractice.yaml 9 KB
• tests/scenarios/iterate.yaml 5 KB
• tests/scenarios/onboarding.yaml 6 KB
• tests/scenarios/out-of-scope.yaml 5 KB
• tests/scenarios/skill-selection.yaml 3 KB
• tests/scripts/bundle-extras.txt 1 KB
• tests/scripts/regenerate-bundle.sh 1 KB
• tests/scripts/run-agentic.sh 1 KB
• tests/scripts/run-routing.sh 1 KB
• workflows/design-sdk.md 8 KB
• workflows/generate-sdk.md 5 KB
• workflows/iterate-and-debug.md 6 KB
• workflows/onboard-repo.md 6 KB
• workflows/publish-store.md 3 KB
• workflows/write-readme.md 3 KB
• workflows/write-spread-tests.md 3 KB