Workshop and AI agents¶
Workshop integrates with AI coding agents, exposing documentation as Markdown that agents can fetch and parse directly, or retrieve through Context7, and agentic skills that wrap Workshop and SDKcraft operations so agents don’t have to rediscover the CLIs every session.
LLM-readable docs¶
Workshop publishes two files that follow the llms.txt convention: llms.txt indexes every page with a one-line summary, and llms-full.txt concatenates every page as Markdown.
To fetch a single page as Markdown,
append .md to its URL.
For example,
this page is available at
https://ubuntu.com/workshop/docs/reference/ai-agents.md.
Context7¶
Context7 indexes the Workshop documentation and serves it to AI agents through its Model Context Protocol (MCP) server, so agents can pull current docs without scraping the site.
Agentic skills¶
The use-workshop-skill repository ships three agentic skills, one for each stage of working with Workshop:
Skill |
Use it when |
Start with |
|---|---|---|
A workshop definition exists and you want the agent to operate it. |
Mention Workshop in a prompt. |
|
A repository has no workshop definition yet and you want one derived from its toolchain. |
|
|
You publish software as an SDK and want the agent to design, build, and release it. |
|
If your agent supports plugins,
install the repository as a plugin:
run /plugin marketplace add canonical/use-workshop-skill,
then /plugin install use-workshop@canonical.
The plugin carries all three skills.
Otherwise,
copy the skill directories from .github/skills/ into the target repo,
using the skills path for your agent
(.claude/skills/ for Claude Code,
.github/skills/ for Copilot, and so on).
Always copy use-workshop/ along with the skill you need,
as the other two read its references.
use-workshop¶
Operates the Workshop CLI on an existing definition: launching and refreshing workshops, running commands inside, wiring interfaces, debugging failed changes, and orchestrating parallel environments via Git worktrees. The skill triggers whenever a prompt mentions Workshop and follows every mutating command with the usual verification: workshop changes, workshop tasks, workshop info.
onboard-workshop¶
Bootstraps a definition for a repository that has none.
The skill reads how the repository already builds, tests, and runs,
delivers a feasibility verdict before writing any file,
and proposes a definition that wraps the existing entry points
(make targets, scripts, CI commands) as actions.
Once approved,
it writes .workshop/<NAME>.yaml and any in-project SDKs,
launches the workshop,
and proves each action inside it.
The repository’s own build files stay untouched.
Aim the agent at the repository.
Run
/onboard-workshop onboard <REPO-PATH>and answer the prompts. Run/onboard-workshop analyzeinstead to stop at the feasibility verdict and proposal without creating anything.Acknowledge the verdict and approve the proposal, then review the generated files.
design-sdk¶
Covers the publisher side:
designing, building, and publishing SDKs with SDKcraft.
The skill runs an interactive design conversation:
it asks about the software to package,
how upstream distributes it,
what must persist across refreshes,
which network services and hardware it needs,
and which bases and architectures to build for,
then proposes a design for approval.
Once approved,
it writes sdkcraft.yaml, the hooks, and spread tests,
iterates with sdkcraft try and workshop refresh
until the SDK comes up healthy,
and writes the README.
On request,
it also onboards the SDK repository
with version branches, CI workflows, and a renovate.json,
and publishes the SDK to the SDK Store.
Aim the agent at the new repository.
Run
/design-sdk new <SOFTWARE>and answer the prompts. Run/design-sdkwithout arguments to pick one of the skill’s other paths instead, such asiterate,test,onboard, orpublish.Approve the proposed design, then review the generated files and adjust where the skill’s defaults don’t match your case.