Skip to content
Skills Library
Programming · Building & coding

onboard-workshop

/onboard-workshop

Analyze an arbitrary repository and bootstrap a tailored Workshop definition from its existing build, test, and debug toolchain — feasibility verdict first, then propose, generate, launch, and verify. Use when a repo has no workshop definition yet and the user wants one derived from how the repo already builds and tests — "set up a workshop for this repo", "workshop-ify this project", "can this repo run in Workshop?".

Licence
GPL-3.0
Last repository change
23.10.2026

Assessment and security

92/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content27 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
74
Scripts
12
HTML comments
2
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.

Licence

GPL-3.0, otwarta.

What to check before installing
  • 12 scripts in this package. Review them before installing, as Claude may execute them.
  • SKILL.md zawiera komentarze HTML (2). Nie widać ich w podglądzie Markdown, a model je czyta.

Scripts: tests/agentic/fixtures/onboard-impossible/Sources/FjordlineApp.swift, tests/agentic/fixtures/onboard-mini-node/build.js, tests/agentic/fixtures/onboard-mini-node/server.js, tests/agentic/fixtures/onboard-mini-node/test/basic.test.js, tests/reconstruction/compare-definition.py, tests/reconstruction/provider-onboard-cli.js, tests/reconstruction/run-reconstruction.sh, tests/reconstruction/scrub-repo.

What it does and when to use it

Analyze an arbitrary repository and bootstrap a tailored Workshop definition from its existing build, test, and debug toolchain — feasibility verdict first, then propose, generate, launch, and verify. Use when a repo has no workshop definition yet and the user wants one derived from how the repo already builds and tests — "set up a workshop for this repo", "workshop-ify this project", "can this repo run in Workshop?".

Triggers from the description

set up a workshop for this repoworkshop-ify this projectcan this repo run in Workshop?

Arguments

/onboard-workshop [onboard|analyze|generate|verify|refine] [repo path]
Original author description

Analyze an arbitrary repository and bootstrap a tailored Workshop definition from its existing build, test, and debug toolchain — feasibility verdict first, then propose, generate, launch, and verify. Use when a repo has no workshop definition yet and the user wants one derived from how the repo already builds and tests — "set up a workshop for this repo", "workshop-ify this project", "can this repo run in Workshop?".

How it works

SKILL.md has no level-two headings · 208 lines, 1,687 words

SKILL.md preview
---
name: onboard-workshop
description: Analyze an arbitrary repository and bootstrap a tailored Workshop definition from its existing build, test, and debug toolchain — feasibility verdict first, then propose, generate, launch, and verify. Use when a repo has no workshop definition yet and the user wants one derived from how the repo already builds and tests — "set up a workshop for this repo", "workshop-ify this project", "can this repo run in Workshop?".
argument-hint: "[onboard|analyze|generate|verify|refine] [repo path]"
---

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

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

1. **Honesty gate.** The feasibility verdict (FULL / PARTIAL / INFEASIBLE)
   is delivered BEFORE any file is generated. Never silently drop a detected
   need to make the proposal look complete; every gap is named with a reason
   and workaround (or "none"). PARTIAL requires explicit user acknowledgment;
   INFEASIBLE ends the run with a report and docs pointers — a subpar
   workshop is worse than no workshop.

2. **Stay inside the envelope, and don't state guesses as facts.** Every
   proposed construct must map to a real definition key, interface, or SDK
   source per `references/capability-envelope.md`. No git-URL SDKs, no
   workshop-level env/services keys, no invented SDK names or channels — an
   SDK name is CHECKABLE (`sdk find`/`sdk info`), so a guess never goes into
   `sdks:` at all; fall back to an in-project SDK or a GAP. Inside a hook the
   situation differs: an install command has no registry to check against,
   and the hook must install *something*. There, write the best candidate and
   mark it — inline `# UNVERIFIED:` plus an `Unverified:` entry in the verdict
   — never as settled fact. Knowing a tool is needed is not knowing how it is
   installed; the tag is what keeps that distinction visible to the reader.

3. **Every question carries a recommendation.** Never ask an open question.
   Format: "Options: A / B — Recommendation: A, because <evidence>." Batch
   all questions into one message.

4. **Copy, don't synthesize, YAML.** Shapes come from `templates/` here and
   `../use-workshop/templates/` — never from memory.

5. **Encode, then prove.** The definition must ENCODE the toolchain mapping
   — actions for every build/test/lint/serve entry point, tunnels for dev
   servers, hooks for setup — prose advice ("you could run npm test with
   xvfb") is not a substitute for putting it in the files. A generated
   action is then done when `workshop run <action>` succeeded inside the
   workshop — or it is reported UNVERIFIED with a reason. Wrap the repo's
   existing entry points (Makefiles, scripts, CI commands); never
   re-implement them, and never MODIFY them: an onboarding writes only
   `.workshop/**` and the `.gitignore` line — the repo's existing Makefiles,
   build scripts, tests, and configurations stay untouched.
</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/*` and
`../use-workshop/templates/*` by relative path, and operating questions route
there. If the sibling is not installed (single-skill vendoring), fetch the
equivalent docs pages via `<docs>` instead — e.g.
`reference/definition-files/workshop-definition.md` for definition anatomy,
`reference/cli/workshop.md` for command signatures — and tell the user the
plugin is meant to be installed whole.

A second sibling, `design-sdk`, owns the publisher side: making a repo's
software installable AS a Store SDK — `sdkcraft.yaml`, packed-SDK hooks,
spread tests, publishing, and SDK-repo automation. That is not an
onboarding; route it there.
</sibling_skill>

<intake>
Pick the matching path:

1. `onboard` — Onboard a repo end-to-end ("set up a workshop for this repo")
   — all four workflows in order
2. `analyze` — Analyze only / feasibility check ("can this run in
   Workshop?") — stop after the verdict and proposal
3. `refine` — Refine an earlier proposal ("use a different base/SDK") —
   re-propose, then regenerate
4. `verify` — Verify a freshly generated definition ("prove it works") —
   launch and verify only
5. Operate, troubleshoot, or evolve an EXISTING workshop — not this skill;
   use `use-workshop`

**If invoked with $ARGUMENTS, route directly without asking.** The leading
token is matched against the subcommands above (`generate` maps to the
"generate what we agreed" row); the rest is the repo path or request detail.
Arguments with no recognized leading verb are a plain request — route them
via the paraphrase table below.
</intake>

<routing>
| Subcommand | User intent (paraphrases) | Path |
|------------|---------------------------|------|
| `onboard` | "onboard", "set up a workshop for this repo", "workshop-ify", "make this project run in Workshop", "bootstrap from my toolchain", "derive a workshop from this codebase" | `workflows/analyze-repo.md` → `workflows/propose-plan.md` → `workflows/generate-definition.md` → `workflows/launch-and-verify.md` |
| `analyze` | "can this repo run in Workshop", "is this feasible", "what would a workshop for this look like", "analyze first", "don't create anything yet" | `workflows/analyze-repo.md` → `workflows/propose-plan.md`, STOP at the proposal |
| `generate` | "generate what we agreed", "apply the proposal", "write the definition" | `workflows/generate-definition.md` → `workflows/launch-and-verify.md` |
| `verify` | "verify it", "prove the actions work", "launch what you generated" | `workflows/launch-and-verify.md` |
| `refine` | "tweak the proposal", "different base", "swap the SDK", "drop the docs actions" | `workflows/propose-plan.md` → `workflows/generate-definition.md` → `workflows/launch-and-verify.md` |
| — | Existing workshop: run/refresh/connect/debug/parallel envs | `use-workshop` skill — do not improvise operations here |
| — | "make this repo's tool an SDK others can install", "publish as a Store SDK", "sdkcraft.yaml", "SDK repo CI/renovate" | `design-sdk` skill — publisher-side work is not an onboarding |
</routing>

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

| File | Use for |
|------|---------|
| `toolchain-signals.md` | Detection pass; signal→construct table; action conventions; Repo Facts format |
| `capability-envelope.md` | What Workshop can/can't express; feasibility rubric; verdict format |
| `sdk-catalog.md` | Fallback SDK catalog when live `sdk find` is unavailable |
| `reference-patterns.md` | Proven wiring patterns; optional live enrichment |

Borrowed from the sibling (load by relative path):

| File | Use for |
|------|---------|
| `../use-workshop/references/definition-file.md` | Full workshop.yaml anatomy |
| `../use-workshop/references/sdk-types.md` | SDK kinds; store-first decision tree |
| `../use-workshop/references/in-project-sdk.md` | sdk.yaml schema; hook taxonomy |
| `../use-workshop/references/interfaces.md` | Interface semantics; auto vs manual connect |
| `../use-workshop/references/secrets.md` | Credentials (0.9.8+): the `--env NAME` route and the `secret` slot + manual connect — read only when the repo's dev loop needs an API key or token |
| `../use-workshop/references/runtime.md` | Container vs VM runtime (`runtime: lxd-vm`; `confinement:` before 0.9.8) — read only if the user asks for a VM workshop (it is out of envelope) |
| `../use-workshop/references/command-cheatsheet.md` | Verbatim command signatures |
| `../use-workshop/references/async-and-recovery.md` | Change/task model; recovery flags |
</reference_index>

<workflows_index>
| Workflow | Subcommand | Stage |
|----------|------------|-------|
| `analyze-repo.md` | `analyze` | A: read-only toolchain analysis → Repo Facts |
| `propose-plan.md` | `analyze`/`refine` | B/C: capability map → verdict → interview → approved proposal |
| `generate-definition.md` | `generate` | D: write `.workshop/<name>.yaml` + in-project SDKs |
| `launch-and-verify.md` | `verify` | E/F: launch, verify, action proof loop, final report |
</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 <name>          # confirm final status
```

Onboarding adds the **action proof loop** on top: after launch, every
generated action is exercised via `workshop run <action>` and every tunnel is
probed from the host; results go in the final report's proof table
(PASS / FAIL / UNVERIFIED + reason). See `workflows/launch-and-verify.md`.
</verification_loop>

<success_criteria>
A run of this skill is complete when:
- [ ] The feasibility verdict was delivered before any file was generated.
- [ ] Every question asked carried an explicit recommendation.
- [ ] INFEASIBLE runs generated nothing; PARTIAL gaps were acknowledged.
- [ ] Generated files were listed with paths; `.workshop.lock` is gitignored.
- [ ] The action proof table covers every generated action and tunnel.
- [ ] The final onboarding report was emitted.
</success_criteria>

<out_of_scope>
- Operating, troubleshooting, or evolving an existing workshop (refresh,
  interfaces, parallel worktrees, purge) → the `use-workshop` skill. This
  includes AFTER a successful onboarding: do not append an operations
  tutorial to the final report — one or two pointer commands
  (`workshop shell`, `workshop run <action>`) at most, then hand off.
- Repos that already contain a definition → `use-workshop`
  (`workflows/bootstrap-project.md` there); onboarding never overwrites one.
- `sdkcraft *` (building/publishing Store SDKs) → the sibling `design-sdk`
  skill: sdkcraft.yaml design, packed-SDK hooks, spread tests, publishing,
  and SDK-repo automation all live there. Standalone `workshopctl` → point at
  `<base>/reference/cli/workshopctl.md`, then stop.
- Interactive `workshop sketch-sdk` flows (require `$EDITOR`) — write
  in-project SDKs directly instead.
</out_of_scope>

<self_healing>
After a run, check whether an issue came from a gap in this skill's files.

What qualifies: tooling drift (command/flag changes), structural problems
(missing file, wrong routing row, dangling cross-reference), a missed
toolchain signal that caused a wrong proposal, an incorrect environment
assumption.

Off-limits for self-edits: `<essential_principles>` (the honesty gate above
all), the verdict semantics in `references/capability-envelope.md`,
`<routing>` semantics, `<out_of_scope>` fencing, and anything under `tests/`
— those changes are eval-gated and belong in a reviewed PR.

How to update: report the gap (file, wrong content, proposed change quoted in
full); apply only in a writable checkout after user confirmation; otherwise
propose a PR against `canonical/use-workshop-skill`. Preserve conventions:
section order, XML tagging, placeholder style, relative docs paths via
`<docs>`.
</self_healing>

<style>
- Lead with evidence: every proposal line cites the repo file it came from.
- Prefer the repo's own vocabulary for action names (their Makefile target
  names, their script names).
- When emitting YAML, copy from a template — do not synthesize from memory.
- Keep the analysis read-only; the first write happens in
  `generate-definition.md` after approval.
- Ground every command in the sibling cheatsheet — if a flag isn't listed
  there, it doesn't exist.
</style>
Files in this package (74)
  • SKILL.md 12 KB
  • references/capability-envelope.md 12 KB
  • references/reference-patterns.md 7 KB
  • references/sdk-catalog.md 5 KB
  • references/toolchain-signals.md 16 KB
  • templates/workshop-dev-server.yaml 1 KB
  • templates/in-project-sdk/sdk.yaml 2 KB
  • templates/in-project-sdk/hooks/check-health 1 KB
  • templates/in-project-sdk/hooks/setup-base 1 KB
  • tests/BASELINE.md 38 KB
  • tests/Makefile 6 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/onboard-impossible/README.md 1 KB
  • tests/agentic/fixtures/onboard-impossible/.github/workflows/ci.yml 1 KB
  • tests/agentic/fixtures/onboard-impossible/Fjordline.xcodeproj/project.pbxproj 1 KB
  • tests/agentic/fixtures/onboard-impossible/Sources/FjordlineApp.swift 1 KB
  • tests/agentic/fixtures/onboard-mini-node/build.js 1 KB
  • tests/agentic/fixtures/onboard-mini-node/package.json 1 KB
  • tests/agentic/fixtures/onboard-mini-node/server.js 1 KB
  • tests/agentic/fixtures/onboard-mini-node/.github/workflows/ci.yml 1 KB
  • tests/agentic/fixtures/onboard-mini-node/test/basic.test.js 1 KB
  • tests/agentic/tasks/honesty-gate.yaml 1 KB
  • tests/agentic/tasks/onboard-mini-node.yaml 3 KB
  • tests/reconstruction/README.md 6 KB
  • tests/reconstruction/compare-definition.py 15 KB
  • tests/reconstruction/promptfooconfig.yaml 3 KB
  • tests/reconstruction/provider-onboard-cli.js 6 KB
  • tests/reconstruction/run-reconstruction.sh 15 KB
  • tests/reconstruction/scrub-repo.py 4 KB
  • tests/reconstruction/expectations/formally-verify-rust-neetcode-with-creusot.json 2 KB
  • tests/reconstruction/expectations/mir.json 2 KB
  • tests/reconstruction/expectations/store-workshop.json 2 KB
  • tests/reconstruction/expectations/subiquity.json 2 KB
  • tests/reconstruction/expectations/vscode-workshop.json 1 KB
  • tests/reconstruction/expectations/workshop-akcano.json 1 KB
  • tests/results/2026-07-23-routing-anthropic-messages-claude-sonnet-4-6.json 8 KB
  • tests/results/2026-08-13-reconstruction-4repo.md 11 KB
  • tests/results/2026-08-13-routing-anthropic-messages-claude-sonnet-4-6.json 9 KB
  • tests/results/2026-08-13-routing-openrouter-z-ai-glm-5.2.json 12 KB
  • tests/results/2026-08-20-agentic-claude-sonnet-4-6.json 1 KB
  • tests/results/2026-08-20-routing-claude-cli-claude-sonnet-4-6.json 10 KB
  • tests/results/2026-08-24-agentic-claude-sonnet-4-6.json 3 KB
  • tests/results/2026-08-24-routing-claude-cli-claude-sonnet-4-6.json 19 KB
  • tests/results/2026-09-22-agentic-claude-sonnet-4-6.json 1 KB
  • tests/results/2026-09-22-control-pre097-routing-claude-cli-claude-sonnet-4-6.json 18 KB
  • tests/results/2026-09-22-routing-claude-cli-claude-sonnet-4-6.json 11 KB
  • tests/results/2026-10-06-routing-claude-cli-claude-sonnet-4-6.json 11 KB
  • tests/results/2026-10-19-routing-claude-cli-claude-sonnet-4-6.json 11 KB
  • tests/results/2026-10-20-agentic-claude-sonnet-4-6.json 1 KB
  • tests/results/2026-10-20-routing-copilot-gpt-6.1-sol.json 15 KB
  • tests/results/2026-10-23-routing-claude-cli-claude-sonnet-4-6.json 12 KB
  • tests/results/2026-10-23-routing-copilot-gpt-6.1-sol.json 12 KB
  • tests/results/2026-10-24-agentic-claude-sonnet-4-6.json 1 KB
  • tests/scenarios/analyze.yaml 5 KB
  • tests/scenarios/dispatch.yaml 3 KB
  • tests/scenarios/feasibility-honesty.yaml 9 KB
  • tests/scenarios/generate.yaml 7 KB
  • tests/scenarios/interview.yaml 3 KB
  • tests/scenarios/out-of-scope.yaml 2 KB
  • tests/scenarios/sdk-selection.yaml 6 KB
  • tests/scenarios/skill-selection.yaml 4 KB
  • tests/scenarios/verify-actions.yaml 4 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
  • tests/scripts/update-sdk-catalog.sh 2 KB
  • workflows/analyze-repo.md 3 KB
  • workflows/generate-definition.md 7 KB
  • workflows/launch-and-verify.md 5 KB
  • workflows/propose-plan.md 5 KB

Versions

The database has no other skills named onboard-workshop.

Database snapshot: 13.11.2026 · package version db51d50ba765 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 92use-workshop
    Operate the Workshop CLI fluently — launch and refresh workshops, run commands inside them, manage interfaces, debug failed changes, and orchestrate parallel environments via git worktrees. Use when the user mentions workshop, .workshop.yaml, an LXD-backed dev environment, or…
  • 92design-sdk
    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…
  • 100workshop-deployment
    Package code and assets, sync to S3, and push content to AWS Workshop Studio. Use when deploying workshop changes or when asked to update the workshop.
  • 100workshop
    Workshop coach for the Research Desk (SEC agents) workshop. Use when the user types /workshop, asks for a workshop act or module ("act 2", "next act", "where am I"), wants a TODO(workshop-N) implemented or explained, or asks for help following WORKSHOP.md.
  • 100data-workshop
    Data Workshop internals — source landing, immutable dataset pipelines and runs, lineage-bound external imports, version inspection and consumer pinning. Use when changing these services, Console screens or MCP contracts.
  • 96repo-bootstrap
    Use when the user asks to bootstrap a new repo or project.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.