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, agentic skills that wrap Workshop and SDKcraft operations so agents don’t have to rediscover the CLIs every session, and SDKs that install the agents themselves in a workshop.

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
use-workshop	A workshop definition exists and you want the agent to operate it.	Mention Workshop in a prompt.
onboard-workshop	A repository has no workshop definition yet and you want one derived from its toolchain.	`/onboard-workshop onboard <REPO-PATH>`
design-sdk	You publish software as an SDK and want the agent to design, build, and release it.	`/design-sdk new <SOFTWARE>`

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 analyze instead 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-sdk without arguments to pick one of the skill’s other paths instead, such as iterate, test, onboard, or publish.
Approve the proposed design, then review the generated files and adjust where the skill’s defaults don’t match your case.

Agent SDKs¶

Coding agents are published as SDKs on the SDK Store. Search for them with sdk find:

$ sdk find agent

  NAME                  VERSION     PUBLISHER            SUMMARY
  ...
  claude-code           2.1.273     Canonical✓           Claude Code CLI
  codex                 0.156.1     Canonical✓           OpenAI Codex CLI agent
  ...
  copilot               1.0.88      Canonical✓           GitHub Copilot CLI - AI-powered coding assistant for the terminal
  ...

The query matches an SDK’s name, title, summary, description, or publisher, so the results also include tools for agents, such as memory servers and skill managers, and SDKs that only mention agents in their descriptions.

The mark after a publisher’s name shows the publisher’s validation status in the SDK Store. When the output doesn’t go to a terminal with a UTF-8 locale, for example when it’s piped to another command, sdk prints an ASCII fallback instead:

Mark	Fallback	Publisher
`✓`	`**`	Verified, such as Canonical
`✪`	`*`	Starred
None	None	Not validated

Before adding an agent SDK to a workshop, inspect it with sdk info:

$ sdk info claude-code

  name:       claude-code
  publisher:  Canonical✓
  license:    https://www.anthropic.com/legal/commercial-terms
  website:    https://github.com/canonical/claude-code-sdk

  ...

  CHANNELS
    CHANNEL           VERSION  BUILD       BASE  REV     SIZE
    latest/stable     2.1.273  2026-09-24  all    37  88.10MB
    latest/candidate  ↑
    latest/beta       ↑
    latest/edge       ↑

Check these fields before you rely on an agent SDK:

Field	What to check
`publisher`	Who publishes the SDK, with the same validation mark as in sdk find. The account name follows in parentheses when it differs from the display name.
`license`	The terms that cover the agent the SDK installs; for a proprietary agent, this is often a link to the vendor’s terms.
`website`	Where the SDK’s source lives, so you can review its hooks, plugs, and README before you install it.
`CHANNELS`	The tracks and risk levels that the SDK is published on, with the version, base, and revision each channel offers. A `↑` means that the risk level has no revision of its own and follows the one above it. Pass `--arch` `all` to list every architecture.

An agent SDK installs the agent in the workshop, where it runs as the workshop user like every other command. Before you let an agent work without its approval prompts, review what the workshop does and doesn’t protect in the security policy.