tutorial-creator
Generate annotated code reading tutorials from your own codebase. Three surfaces - tutorial generation, vocabulary management, and learning-state inspection. Tracks vocabulary with status state machine, supports six writing-to-learn entry points and five audience-facing entry points.
Terry Nyberg, Coffee & Code LLC · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add Terryc21/tutorial-creator --skill tutorial-creator技能说明
name: tutorial-creator description: Generate annotated code reading tutorials from your own codebase. Three surfaces - tutorial generation, vocabulary management, and learning-state inspection. Tracks vocabulary with status state machine, supports six writing-to-learn entry points and five audience-facing entry points. version: 2.0.1 author: Terry Nyberg, Coffee & Code LLC license: Apache-2.0
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 generationstatus— 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|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:
- Resolve the project root (NEW in this revision). Run
## Project resolutionfirst to determine which.claude/tutorial-config.yamlthis invocation should read or write to. The resolved path becomes$PROJECT_ROOTfor 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. - Read
--modeflag 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,vocab,status. Any other value (includingboth, which earlier drafts listed but never specified): sayUnknown mode "<value>". Valid modes: learn, audience, vocab, status.and stop — do not guess a surface or silently fall through to the gateway. - Else, recognize first-positional subcommand keywords. If the first positional arg is one of:
tutorial→ tutorial surface (Path 1 unless--mode audiencefollows)vocab→ vocab surface; the second positional is the subcommand (add,list,show,edit,merge,review,gap,regen-md,undo)status→ status surface (STATUS.md)undo→ recoveryundoroute (see## Recovery§undocommand). May be followed by--session <id>renumber→ recoveryrenumberroute (see## Recovery§renumber). Requires two more positional args:<old> <new>(e.g.,renumber 8 7.5)open→ registry route (see## Project resolution§opencommand). May be followed by an optional<path>positionalforget→ registry route (see## Project resolution§forgetcommand). Requires one positional arg:<path>Route directly. Skip the gateway question.
- 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. - 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.mdand run the Path 2 routing flow (entry-po