onboarding-and-teaching

Use when designing, reviewing, or generating the introduction to ANY mechanic in ANY genre — the four-beat teaching pattern (introduce→test→combine→twist), show-don't-tell level design, progressive di

SKILL.md

GitHub

Onboarding & Teaching

How to introduce any mechanic — in any genre, on any platform — so that instruction is invisible, comprehension is measurable, and the player's first hours build competence instead of confusion.

Tier: universal craft (→ gamestack-core). Applies to every genre and every game. The spatial side of teaching (teaching through space) lives in level-design; the early difficulty curve lives in difficulty-and-balancing.

When to use this

  • Designing a mechanic's first appearance: safe-space room, skill gate, combination encounter, twist
  • Reviewing a tutorial for working-memory overload, anti-patterns, or implicit/explicit balance
  • Building a FTUE (first-time user experience) with a funnel and a measurable early win
  • Generating a teaching ramp for a procedurally defined mechanic set

Scope

This skill owns how mechanics are introduced and learned. Adjacent concerns live in sibling skills:

  • Flow theory, intrinsic motivation, and the skill atom cycle → game-design-fundamentals
  • Teaching through spatial layout, landmarks, and affordances → level-design
  • Difficulty curve and the early challenge ramp → difficulty-and-balancing
  • Tutorial UI, tooltip and HUD design, and feedback overlays → ui-ux-and-feedback
  • First-hour pacing and session arc → pacing-and-the-player-journey

How the pieces fit

  • GUIDE.md — the cited why, in five sub-domains: the four-beat teaching pattern (introduce→test→combine→twist); show-don't-tell and implicit tutorial methods; progressive disclosure, scaffolding, and the mechanic dependency graph; FTUE and early retention design; and the five named anti-patterns. Every rule carries an exemplar + source, a test-for criterion, the named failure mode, and the procedural/headless implication.
  • CHECKLIST.md — Do/Don't + machine-checkable Test-for criteria, grouped by sub-domain. Written to be enforced as validators in a generation loop.

The one idea to anchor on

The best tutorial is a level, not a pop-up. Working memory holds ~3 novel items; exceed it and the mechanic goes untaught even if displayed. Teach one thing at a time — safe and consequence-free first, gated for mastery second, combined with a prior mechanic third, twisted into an unexpected application fourth. Every text box you add is a tacit admission that the level design failed to communicate it; every pop-up a player can skip is instruction that will not be received.

Start with GUIDE.md, then apply CHECKLIST.md.