/tutorial

name: tutorial
description: "Show a new owner what to try first. Voice: on \"tutorial\", \"walk me through\" or \"show me what you can do\", walk the workspace tutorial one short section at a time. AG2 Space: on an owner DM message with a line `/tutorial` (the setup app ends the first-contact message with one), after the greeting, create (or refresh) one \"Getting started\" HTML page there, a short AG2 Space tour with one thing to try per part, and summon the owner to it."
user-invocable: true

tutorial

Two modes. Pick by where the request came from.

Voice mode

When the owner says "tutorial", "walk me through" or "show me what you can do" (voice or text):

1. Read `<workspace>/notes/first-time-tutorial.md`. 2. Deliver the first section as a voice-friendly summary (1–2 sentences). 3. Wait for them to try it; when they come back, deliver the next section. 4. Continue until done or they say stop.

Keep each step conversational and brief: this is spoken, not read. Say what to try and skip setup details unless asked. A section that needs an app they have not connected (email, phone, the morning briefing) gets one sentence on connecting it, not the full step.

AG2 Space mode: the Getting started page

Used when an owner message in their AG2 Space DM has a line that is exactly `/tutorial`, or the owner asks for the tutorial there. The setup app ends the automatic first-contact message with that line, so the page follows the first greeting; the owner can send `/tutorial` again at any time. Run the script below by its path: a core that cannot find skills by name still has it. The line asks for this page and nothing else.

**The greeting comes first.** Send the first-contact reply in the DM before anything here. The page is extra: if any step below fails, the greeting stands. Do not edit, retract or repeat it, and do not retry the page in the same turn.

1. Your name, never the owner's, and never a reason to stop. Use `ag2.whoami`'s `display_name` when it has one. When it is null, pass `--name auto`, which falls back in this order:

• your Matrix profile displayname from your homeserver;
• a name made from your mxid's localpart (`@chi-air-blue.agent:…` gives `Chi Air Blue`);
• `Sutando`.

Your mxid is `$AGENT_MXID`, else the AG2 Space channel env file's, else `--agent-mxid`. 2. Tailor the prompts when you know the owner's work. You know it when either:

• the first-contact message has a line `I picked: <labels>.`, for example

`I picked: Founder, Product Manager.`. These are the persona labels the owner chose at onboarding, or their slugs when the client had no labels; or

• `user_profile.md` already says what they do.

In that case write your own prompts for this owner into a temporary JSON file, one per slot: `dm`, `commons`, `teamwork`, `apps`, `import`, `finale`. Write 4–6 of them.

• Each is first person, practical, one line, at most 200 characters, with no links or markup.
• Each must run on a fresh install: only the `apps` slot may assume a connected app.
• The slot decides where the prompt is pasted (your DM or a room), not the wording.

Pass the file as `--prompts <file>`, and pass the `I picked:` payload verbatim as `--roles "Founder, Product Manager."` (the whole line, `I picked:` included, works too). Do not map it to slugs: the script takes labels or slugs and adds a "Picked for: Founder, Product Manager" line under the heading. Without `--roles`, the saved inputs' `roles` are used (step 3). Otherwise leave both out. A missing, bad or partly bad file never fails the run: each slot without a usable prompt keeps the generic one. 3. Create or refresh the page and summon the owner to it:

   python3 skills/tutorial/scripts/getting_started.py publish \
     --room '<owner DM room id>' --name '<your name or auto>' --owner '<owner mxid>'

Every flag is optional when the setup app saved the inputs: `<workspace>/state/onboarding/tutorial-inputs.json` holds `room` (the owner's DM), `owner`, `agent_mxid` and `roles` (the picked personas), and `publish` fills whatever the command line leaves out from it; `--name` defaults to `auto`. The file's `owner` and `roles` apply only when publishing in its own `room`. A missing or malformed file, or a field of the wrong shape, is ignored; with no `--room` and no usable saved room, the script exits 2.

You need not source any env file. `room_commons.py` is found beside this skill, else in the installed skills directory. When the environment names none of its credentials, they are read from the AG2 Space channel env file through the shared resolver (`src/channel_credentials.py`). They are passed to that process only and never printed.

`--core` defaults to `auto`: the core runtime the engine resolves (`bash scripts/sutando-config.sh core-runtime`: the launcher's `SUTANDO_CORE_RUNTIME` stamp, else `core.runtime` in config). Pass `--core claude|codex|unknown` to override it.

It prints one JSON line:

• `action`: `created`, `updated` or `unchanged`;
• `kind`: the page's `html-<id>`;
• `name`: the name it used.

On `created` it summons the owner, so the card in the DM is the one line that carries the page: post no other message about it. On `updated` / `unchanged` it summons no one, including when it adopts a page it found by its ownership marker. The one exception is finishing a page an earlier run created but did not complete. `--summon` forces a summon, e.g. when the owner asks for the tutorial again. 4. Exit 3 (room-commons not installed) or 4 (a room-commons call failed): leave the greeting as is and say nothing about the page unless the owner asks. A failure that is a Sutando or AG2 Space defect goes to `report-feedback`.

Run it in the owner's own DM (the default, `--audience dm`). Only when the owner asks for the page in another room, publish it there with `--audience room`: the page then