---
name: tutorial-format
description: "Write numbered, OS-specific click-by-click tutorials when the user must finish an action the agent cannot. Use whenever you would say you'll need to, I can't access, please go to, or you hit an API, MCP, OAuth, 2FA, browser login, consent, API-key, token, settings, or tool limitation that requires a human to click, authorize, paste a secret, or change an account setting — even if they did not ask for a tutorial."
license: MIT
metadata:
  author: Efrain Plascencia (frin-bot)
  version: "1.0.0"
  homepage: https://github.com/frin-bot/tutorial-format
---

# Tutorial Format

Turn every **human-gated** action into a single, followable tutorial. The agent keeps doing agent work. The human gets a checklist they can execute without guessing.

This skill does **not** replace tools. If you can complete the action (open a URL, call `setup_mcp`, write a file, run a command), do that first. Only hand the user a tutorial for the part that actually requires their hands, eyes, password, or account.

## When to Use

Use this skill when **any** of these are true:

- A tool, API, or MCP cannot finish the job (missing auth, consent card, unpaid plan, disabled integration, 2FA, CAPTCHA, human-in-the-loop).
- You are about to write "you'll need to…", "I can't access…", "please go to…", "open Settings and…".
- The user must click, log in, authorize, create a key, paste a secret, flip a setting, or confirm on another device.
- The next step lives in a vendor dashboard, OS dialog, browser permission prompt, or mobile app.

Do **not** use this skill when:

- You can do the action with available tools.
- The user only asked for an explanation, not to perform the action.
- You would be instructing unauthorized access, bypassing security, or handling someone else's account.

## Goal of every tutorial

After reading it, a non-expert can finish the job **without asking what to click next**. Each step names the exact control, what they should see, and what to do if they don't.

## Procedure

1. **Name the blocker in one sentence.** Product + what's missing + why the agent can't do it. Example: "Notion MCP is connected, but the integration has no access to the Jobs database."
2. **Do everything that is still agent-doable.** Open the official URL if you can. Prefill files. Run `setup_mcp` / OAuth tools when they exist. The tutorial covers only the remainder.
3. **Detect environment before writing steps.** OS, browser vs desktop app, already-logged-in vs cold start. If unknown, write for the user's known OS and say so; do not dump Windows + macOS + Linux in one wall of text.
4. **Write one tutorial, one job.** If there are two unrelated human actions, two tutorials (or two clearly labeled phases). Don't mix "create an API key" with "then redesign the workflow".
5. **Stop and wait.** After the tutorial, do not continue as if they finished. Tell them exactly what to reply (`done`, a screenshot, a pasted value, an error string).

Completion criterion: the user could hand the tutorial to someone else and that person would succeed.

## Output template

Use this structure every time. Drop a section only when it would be empty.

```markdown
## You need to do this

**Why:** <one sentence: agent cannot X because Y>
**Goal:** <what "done" looks like in the product>
**Time:** ~<N> minutes
**Where:** <product / exact URL>
**You will need:** <account, role, device, browser>

### Before you start
- <prereq that would waste their time if missing>

### Steps

**Step 1 — <short title>**
<one action. Exact label in "quotes".>
**You should see:** <one-line description of the screen / result>
**If not:** <the most likely miss + the fix>

**Step 2 — …**

### Done when
- <checkable criterion>
- <second criterion if needed>

When that's done, reply with: <exactly what to send back>
```

## Writing rules

**One action per step.** "Open Settings" is a step. "Open Settings, find API, create a key, copy it" is four steps.

**Name the control, don't narrate the vibe.** Write `Click "New secret key"` not `Create a key somewhere in the API area`. Menu paths use `>` : `Settings > API > Keys`.

**Expected result after every step.** People get lost between clicks. "You should see" is the map pin.

**Official URLs only.** Prefer `https://…` deep links over "search for X". If you cannot verify the current URL, say that and give the in-product path.

**Copy-paste as fenced blocks.** Commands, redirect URIs, callback URLs, and scope names go in their own blocks so they can be copied on a phone.

**Secrets stay on their side of the screen.** Tell them where to paste a token (password manager, `.env` field, consent card). Default: do **not** ask them to paste secrets back into chat. If the agent truly needs the value, say so, say why, and tell them they can redact after.

**Role and permission honesty.** If the action needs Admin / Owner / billing access, say that in "You will need" before Step 1. Don't discover it at Step 7.

**Don't invent UI.** If you are not sure a button still exists, write the job (`create a personal access token with repo scope`) and the official docs URL rather than a guessed label.

**No dummy walkthroughs.** If the user already completed part of the flow, skip those steps. Start at the first incomplete action.

**Keep it short.** 5–12 steps is the sweet spot. If you need 20, you bundled more than one job — split phases.

## OS and device forks

- If the OS is known, write only that OS.
- If the same product has browser and desktop apps, pick one (the one they are in) and mention the other in a single "Using the other app?" line.
- Mobile 2FA / authenticator steps get their own phase, because the user will look away from this chat.

Windows example path style: `Start > Settings > Apps > Installed apps`.
macOS: `System Settings > Privacy & Security`.
Linux: the actual distro/desktop if known; otherwise the command.

## What to do instead of a tutorial

| Situation | Do this, not a tutorial |
|---|---|
| MCP missing / disabled / needs OAuth in this app | Use the app's MCP install/consent flow first |
| You can open the page | Open it, then tutorial only the clicks on that page |
| You can write the config once they paste a value | Prepare the file, tutorial only the copy/paste |
| The action is a single yes/no in this chat | Ask that question; don't wrap it in seven steps |

## After they reply

- If they said `done` and you can verify (tool call, read-back, authenticated request), verify before continuing.
- If they pasted an error, troubleshoot from **If not** — don't restart at Step 1.
- If they stalled, ask which step number they are on. Don't resend the whole tutorial unless they asked.

## Pitfalls

- **Tutorial as apology.** Lead with the goal, not "unfortunately I am unable".
- **Screenshot dumps without steps.** A picture of a settings page is not a procedure.
- **Mixing agent commands into human steps.** `Run gh auth login` is a human step only if *they* must run it. If you can run it, you run it.
- **Skipping verification.** "Done when" must be something they can see (green check, listed integration, key ending in `…abc`, toggle on).
- **Continuing past the handoff.** The turn that emits the tutorial should end there.

## Verification (agent self-check)

Before sending, confirm:

- [ ] Why / Goal / Where are filled
- [ ] Every step is one action with a quoted control or an exact command
- [ ] Every step has **You should see**
- [ ] Secrets are not requested back unless required
- [ ] The reply line tells them what to send next
- [ ] You stopped; you did not keep working as if they finished

Worked examples: [references/examples.md](references/examples.md)