tutorial-creator

tutorial-creator

Three surfaces, gateway-mediated:

• tutorial — generate a lesson (six writing-to-learn entries, five audience-facing entries)
• vocab — manage vocabulary independent of lesson generation
• status — inspect your learning state (read-only dashboard)

The legacy v1.1 invocation (/skill tutorial-creator <topic> <source>) still works; it routes to writing-to-learn entry [b] (topic + file).

Usage

/skill tutorial-creator                         # opens gateway question
/skill tutorial-creator <topic> <source>        # legacy v1.1 path → entry [b]
/skill tutorial-creator tutorial <args>         # tutorial surface
/skill tutorial-creator vocab <subcommand>      # vocab surface
/skill tutorial-creator status                  # status surface
/skill tutorial-creator undo                    # revert last generation
/skill tutorial-creator undo --session <id>     # revert a specific session (rare)
/skill tutorial-creator renumber <old> <new>    # rename Day-N + rewrite cross-references
/skill tutorial-creator --mode learn|audience|both|vocab|status [args]
                                                 # skip gateway, route directly
/skill tutorial-creator open <path>             # register a tutorial-creator project
                                                 #  in ~/.claude/tutorial-creator/registry.yaml
                                                 #  so future invocations from any cwd find it
/skill tutorial-creator open                    # list registered projects + pick one
                                                 #  (sets it as the registry default)
/skill tutorial-creator forget <path>           # remove a project from the registry
                                                 #  (no filesystem changes; project files stay)
/skill tutorial-creator --project-dir <path> [args]
                                                 # one-shot override; resolves config
                                                 #  from <path>/.claude/tutorial-config.yaml
                                                 #  instead of the default discovery rule

Where the project lives. .claude/tutorial-config.yaml and .claude/tutorial-sessions/ live in the resolved project root, not necessarily cwd. The skill walks a discovery chain on every invocation; see ## Project resolution. This means you can keep a tutorial-creator project at /Volumes/.../Tutorials/ and invoke /skill tutorial-creator status from any working directory and it Just Works — same mental model as git status walking up from cwd to find .git/.

Routing logic

Every invocation runs through this dispatch:

1. Resolve the project root (NEW in this revision). Run ## Project resolution first to determine which .claude/tutorial-config.yaml this invocation should read or write to. The resolved path becomes $PROJECT_ROOT for the rest of the invocation; all subsequent file operations described in this document use $PROJECT_ROOT/.claude/, $PROJECT_ROOT/{tutorials_dir}/, etc. Steps 1–4 below assume this has run.
2. Read --mode flag if present. If set, echo it back to the user as a one-line confirmation, then jump directly to that surface or path. Skip the gateway question. Mode values: learn, audience, both, vocab, status.
3. Else, recognize first-positional subcommand keywords. If the first positional arg is one of:
4. tutorial → tutorial surface (Path 1 unless --mode audience follows)
5. vocab → vocab surface; the second positional is the subcommand (add, list, show, edit, merge, review, gap, regen-md, undo)
6. status → status surface (STATUS.md)
7. undo → recovery undo route (see ## Recovery § undo command). May be followed by --session <id>
8. renumber → recovery renumber route (see ## Recovery § renumber). Requires two more positional args: <old> <new> (e.g., renumber 8 7.5)
9. open → registry route (see ## Project resolution § open command). May be followed by an optional <path> positional
10. forget → registry route (see ## Project resolution § forget command). Requires one positional arg: <path>

Route directly. Skip the gateway question.

1. Else, parse two-positional legacy form. If the user invoked with two positional args matching <topic> <source> AND the source is an existing file in the project, treat as entry [b] legacy path — produce a v1.1-shaped tutorial. This preserves the v1.1 invocation contract for users who haven't seen the v2 changes.
2. Else, ask the gateway question. Present the four-option menu (below). Route based on answer.

Gateway question

Use AskUserQuestion (or plain-text prompt if AskUserQuestion is unavailable):

What do you want to do?

[1] Write a tutorial for myself      (for my own learning)
[2] Write a tutorial for others      (preparing a lesson for others to learn)
[3] Manage vocabulary                 (edit vocabulary)
[4] Inspect my learning state         (see my progress and what I'm forgetting)

• Answer [1] → tutorial surface, Path 1 (writing-to-learn). Ask the entry-point question (six options; see ## Tutorial surface — entry points).
• Answer [2] → tutorial surface, Path 2 (audience-facing). Load AUDIENCE.md and run the Path 2 routing flow (entry-point question, audience question, honest-machine opt-in, length budget, venue selection, then handoff to the chosen venues/<name>.md).
• Answer [3] → vocab surface (load VOCAB.md).
• Answer [4] → status surface (load STATUS.md).

Mode-mismatch detection

If the user picked Path 2 (audience-facing) AND their topic phrasing matches one of these patterns, soft-nudge once:

• starts with I want to understand
• starts with I'm confused about
• starts with why does my
• starts with what is

Nudge text:

This phrasing reads like writing-to-learn. Confirm audience-facing, or switch to writing-to-learn?

Single-fire per session. A session-scoped flag (mode_mismatch_nudge_fired: true) flips after the first surface. Subsequent matching topics in the same session do NOT re-nudge. The user has demonstrated awareness.

Not blocking. The user always has final say. The nudge is purely advisory; either answer proceeds without delay.

Tutorial surface — entry points

After gateway answer = [1] (writing-to-learn), ask:

Where does the lesson start?

[a] Daily progression       — pick what's next based on my progress
[b] Topic + file            — I have both a topic and a source file
[c] Topic only              — I have a topic, find the best file
[d] Question                — I'm stuck on something specific
[e] Gap-driven              — show me my "confused" vocabulary, pick from there
[f] Notes & synthesis       — from a doc, post, video, or past session

After gateway answer = [2] (audience-facing), ask:

Where does the tutorial start?

[a] Annotated source         — file in my codebase that demonstrates the pattern
[b] Incident-grounded        — a real failure or decision I want to write about
[c] Synthesized example      — contrived minimal example for the concept
[d] External source          — public repo, Apple sample, blog post
[e] Documentation-grounded   — Apple Developer docs, RFCs, etc.

After the entry letter is picked, the Path 2 flow runs four more AskUserQuestion prompts in this order, then hands off to a venue template:

1. Audience question. Options: beginner / intermediate / senior / mixed. Drives in-voice content shifts (definitions vs. tradeoffs).
2. Honest-machine opt-in. Y / N. When Y, the venue template appends a section on what the article does NOT cover (section name varies by venue; resolved from venues/_schema.yaml#venues.<name>.honest_machine_section_name).
3. Length budget. Options: S / M / L / X. Each option label includes the venue's word target and ceiling, looked up from `venues/_schema