tutorial-creator

Generate personalized coding lessons from your own codebase. A Claude Code skill that turns the files you actually work on every day into annotated tutorials, tracks the vocabulary you've learned, and shows you where you're confused.

Works with any Swift, TypeScript, Python, or Rust project. Originally built during development of Stuffolio, a real iOS/macOS app whose codebase serves as the bundled demo.

~9 min read · scan the TL;DR if you only have 30 seconds

TL;DR

• What: Generate annotated lessons from your own code, track vocabulary you've learned across sessions, and see exactly what you're confused about.
• Why: Traditional tutorials teach syntax with toy examples; real projects have async workflows, state management, and accumulated design decisions. tutorial-creator builds fluency from the code you ship every day.
• Install: git clone into ~/.claude/skills/; then /skill tutorial-creator in any session.
• Try first: /skill tutorial-creator — opens the gateway question. Pick "Write a tutorial for myself" → "Topic + file" → point it at any file. ~10 min to a real annotated lesson.
• Example output: Day 16 — captured-self staleness in SwiftUI, a real production-bug walkthrough with pre/post tests and gap analysis.
• Maturity: v2.0.1 (2.0 feature release 2026-05-10); used through Stuffolio's daily practice; deeper curation for Swift, working built-in progressions for TypeScript / Python / Rust.

Newer to Claude Code?

A skill is a markdown file Claude Code knows how to run. When you type /skill tutorial-creator, Claude follows the instructions in this skill, asks what you want to do, then either generates a lesson, manages your vocabulary, or shows you your learning state. You don't have to memorize anything — the skill walks you through each choice.

Install

Install as a Claude Code plugin:

/plugin marketplace add Terryc21/tutorial-creator

/plugin install tutorial-creator@tutorial-creator

Then in any Claude Code session:

/skill tutorial-creator

First-run setup prompts you for the project to learn from, your language (Swift / TypeScript / Python / Rust auto-detected), and your experience level. The skill creates .claude/tutorial-config.yaml and a tutorials directory in the project you point it at.

<details> <summary><strong>Manual install (no plugin system)</strong></summary>

The skill lives at skills/tutorial-creator/ inside this repo, so clone the repo somewhere and link (or copy) that subdirectory into your skills directory — cloning the repo directly into ~/.claude/skills/tutorial-creator nests the skill one level too deep and Claude Code won't find it.

git clone https://github.com/Terryc21/tutorial-creator ~/src/tutorial-creator && ln -s ~/src/tutorial-creator/skills/tutorial-creator ~/.claude/skills/tutorial-creator

For one project only, link into that project's skills directory instead:

mkdir -p /path/to/project/.claude/skills && ln -s ~/src/tutorial-creator/skills/tutorial-creator /path/to/project/.claude/skills/tutorial-creator

</details> <details> <summary><strong>Migrating from v1.1 to v2.0</strong></summary>

If you used v1.1 and have an existing VOCABULARY.md, run a one-time import after installing v2.0:

/skill tutorial-creator vocab regen-md --import

This converts your existing VOCABULARY.md Markdown table into the v2.0 vocabulary.yaml source-of-truth file. Migrated terms get status: reviewing (no v1.1 test history exists). You can vocab edit to add types, vocab merge to collapse duplicates, and vocab review to start earning mastered status.

</details>

See CHANGELOG.md for full release notes and the v1.1 → v2.0 changelog.

What gets generated

Above: real gap analysis after generating Day 16. The skill found two prerequisite gaps in the user's earlier curriculum and proposed half-step bridge tutorials (Day 15.5 and Day 9.5) that slot between existing days without renumbering.

Three sample outputs are checked into skills/tutorial-creator/examples/:

• Day 3 — ScoutResultsLookupView — early-progression Swift tutorial annotating a single SwiftUI view file. Pre-test, annotated source, post-test, vocabulary table.
• Day 16 — Captured-self staleness — later-progression deep dive on a subtle Swift concurrency bug pattern in the user's own codebase.
• useDebouncedValue hook — non-Swift example: TypeScript / React custom hook, same tutorial shape.

Each is a real tutorial generated from a real codebase, not a fabricated illustration.

---

Why this exists

Most AI coding tools optimize for speed: generate code faster, scaffold features faster, ship faster.

But many developers are now generating code faster than they can comfortably read or understand it.

tutorial-creator explores a different idea: AI should help developers build fluency and understanding, not just produce more code.

While building Stuffolio, I realized something uncomfortable: Claude Code was helping me generate Swift code faster than I was developing fluency reading it. Traditional tutorials taught syntax using toy examples like let x = 5, but real projects don't look like that. Real projects contain async workflows, state management, dependency injection, conditional rendering, architectural patterns, edge cases, and accumulated design decisions.

I didn't want to stop building and go study disconnected tutorial exercises. I wanted to learn from the actual code appearing in my own project every day. So I built a Claude Code skill that turns real project files into personalized annotated lessons.

This skill:

• Generates personalized coding lessons from your own codebase
• Tracks vocabulary and concept progression across sessions
• Detects missing prerequisites and proposes bridge tutorials automatically
• Helps you learn naturally while continuing to ship real software
• Manages vocabulary as a first-class object, not a side effect of writing tutorials
• Shows you which terms you're confused about and proposes targeted lessons
• Supports six entry points to learning (daily progression, topic + file, topic only, question, gap-driven, external source)

---

Three surfaces, gateway-mediated

v2.0 splits the skill into three top-level surfaces, with a gateway question that asks you what you actually want to do before assuming you want to write a tutorial.

| Surface | Purpose | Subcommands | |---|---|---| | tutorial | Generate a lesson | 6 entry points (writing-to-learn) + 5 (audience-facing) into 6 venue templates | | vocab | Manage your vocabulary | add, list, show, edit, merge, review, gap, regen-md, undo | | status | Inspect your learning state | Read-only dashboard |

Bare invocation opens the gateway:

/skill tutorial-creator

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)

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

Six entry points for writing-to-learn

The skill doesn't assume you have a topic + file in mind. Pick the entry that matches where you are:

| Entry | Use when… | |---|---| | [a] Daily progression | You want the next concept in your learning sequence | | [b] Topic + file | You have both a topic and a source file | | [c] Topic only | You have a topic; let the skill find the best file | | [d] Question-led | You're stuck on something specific ("why does my SwiftData fetch return zero?") | | [e] Gap-driven | Show me what I'm confused about; pick from there | | [f] Notes & synthesis | From a doc, post, video, or past session — help me consolidate |

Entry [c] ranks candidate files by pedagogical fit (small file with concentrated examples beats large file with scattered ones), shows evidence (line counts, line ranges, brief reasons), and lets you pick. If no good example exists in your codebase, it offers a synthesized minimal example instead of silently picking a marginal file.

Entry [d] is the highest-value, highest-risk entry. When the question is ambiguous, the skill surfaces the ambiguity ("I see two ways to interpret this; which fits?") rather than picking one and proceeding. The honest-machine voice is load-bearing here.

Entry [e] reads from the vocab gap view (terms with status: confused) and generates a tutorial targeted at one of them. The tutorial's framing acknowledges the gap directly — Pre-Test targets the specific aspect the user has been getting wrong.

Vocabulary as a first-class object

In v1.1, vocabulary was a side effect of writing tutorials: the only way a term entered VOCABULARY.md was by being introduced in a generated tutorial. v2.0 decouples them.

Now you can:

• vocab add <term> — capture a term outside a lesson (encountered in a code review, read in someone else's tutorial, mentioned in a meeting). The skill drafts a definition; you accept or edit.
• vocab review — spaced-repetition test session. The skill picks 5 terms, prioritizing confused > stale > random. You write each definition; the skill grades leniently by default (concept match, not verbatim) and updates status.
• vocab gap — see exactly which terms you've been getting wrong, ranked by how long you've been stuck. Feeds entry [e] gap-driven directly.
• vocab list --status=confused — filter by any status (new / reviewing / mastered / confused).
• vocab merge <a> <b> — collapse duplicates (@Observable and Observable macro) while preserving test history.

Status is earned through tests, not user-set. Mastered requires 3 consecutive correct results; confused requires 2 of last 3 partial/wrong. The one allowed manual transition is mastered → reviewing (you noticed you've forgotten something). Getting back to mastered requires re-earning it.

Status dashboard

A read-only at-a-glance view of your learning state:

• Tutorials shipped, last lesson, streak, suggested next concept
• Vocabulary counts by status (mastered / reviewing / confused / new)
• Due for review (terms unreviewed > 14 days)
• Gap radar (top 3-5 confused terms with staleness)
• Suggested next lesson (combines vocab gap + progression)

Recovery / undo

Every tutorial generation logs a session record and snapshots the four files it modifies. undo reverts the last generation cleanly. Vocab additions are revertable for 24 hours via vocab undo. Day numbers can be retroactively renumbered via renumber <old> <new>, which rewrites references across PROGRESS.md, VOCABULARY.md, and other tutorials.

Audience-facing path

v2.0 adds a second gateway path for users who want to publish what they've learned. Instead of writing-to-learn, you're writing-to-teach. Five entry points (annotated source / incid