tutorial

Files (15)

• SKILL.md
• commons-surfaces.jpg · assets/
• composer-mention.jpg · assets/
• mobile-pairing.jpg · assets/
• new-room-dialog.jpg · assets/
• room-header-call.jpg · assets/
• room-header-commons.jpg · assets/
• room-list-add.jpg · assets/
• room-list-top.jpg · assets/
• room-menu-invite.jpg · assets/
• settings-integrations.jpg · assets/
• user-card-plug.jpg · assets/
• manifest.json
• getting_started.py · scripts/
• tour_page.py · scripts/

SKILL.md (first lines)

# 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.

## s.space mode: the Getting started page

Used when an owner message in their s.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 `$AGENT_MXID`, else the s.space channel env file's (the
   launcher-named device file first). `publish` refuses to run without one: a page without the
   ownership tag could never be found again.
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:

   ```bash
   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 s.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 s.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 says "your agent" instead
of your name. The room's entry records the audience, and a later run without `--audience` keeps
it. Summon only whoever the owner asked for. Either way the page holds your name or "your
agent" and fixed text, nothing from the owner's accounts, and the question about their work stays
in chat.

**One page per room, created once.** `<workspace>/state/tutorial/getting-started.json` keeps
each room's entry.
- Before the page is made, the entry records `creating` and an operation id.
- The page is made with `room.commons.pages.create`, whose first body already carries the
  ownership marker (`<meta name="sutando-tutorial" content="<agent mxid>">`). A retry with the
  same operation id returns the same page, so an unclear create is retried, never repeated.
- The entry is `pending` until the rest of the page is appended, then `complete`. Any failure
  leaves an entry the next run resumes; nothing is created twice.
- A re-link or reinstall that reuses the DM rewrites the page in place, as does `/tutorial` sent
  again. A page someone removed from the list is created again.
- The ownership tag also records the feature list's revision the page was built from
  (`data-revision="tutorial.2026-10-23.1"`). **Rebuild rule:** a page is rebuilt in place when the
  engine's list revision is newer than the page's. `publish --if-newer` applies exactly that rule
  and nothing else: a complete page whose revision is current is left alone even when a rebuild
  would differ (another name or core), a stale page is rewritten with the prompts and roles it was
  last built with (recorded in the entry), a page from before lists had a revision counts as stale,
  and a `pending` page is finished whatever its revision. A page someone edited since it was last
  written (its text no longer hashes to the entry) is kept, with or without `--if-newer`, and
  whatever the revision: the result says `"action": "kept"`, stderr names the page, and the entry

From sonichi/sutando, MIT.

More from sonichi/sutando