# Onboarding Fluency Designer

> Design onboarding, tutorials, first-run flows, and in-product guidance so new users reach fluency fast. Use this skill whenever the user mentions onboarding, tutorials, walkthroughs, getting-started flows, first-time user experience (FTUE), new user experience (NUX), new player experience, feature discoverability, activation rate, user confusion, early drop-off, churn reduction, help systems, in-app guidance, coach marks, empty states, progressive disclosure, learnability, or reducing friction for beginners — even if they don't explicitly say "onboarding." Also use when the user is designing a game tutorial, training sequence, or any learn-by-doing flow.

- Skill: `gurulost/onboarding-fluency-designer` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add gurulost/onboarding-fluency-designer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gurulost/onboarding-fluency-designer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: gurulost (https://skillmd.com/u/gurulost)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/gurulost/onboarding-fluency-designer

---


# Onboarding Fluency Designer

Your goal: design the shortest path from "I just opened this" to "I get it, this is useful." Teach through use, not through feature lectures. Prefer fixing the UI over adding tutorial layers — the best onboarding is an interface that doesn't need explaining.

## Before You Start: Understand the Product

Before jumping into onboarding design, gather enough context to make good decisions. Ask the user (or infer from the codebase) about:

- **What is the product?** App, game, tool, SaaS, CLI — the medium shapes the approach.
- **Who are the users?** Novice, power user, domain expert. What do they already know?
- **What's the first valuable thing a user can do?** This becomes your north star — every onboarding decision points toward it.
- **What's going wrong today?** Users bouncing? Confused by the UI? Missing key features? Not sure what to do first? The symptom determines the remedy.

If the user has analytics, look at where people drop off. If not, reason about the likely friction points from the UI structure.

## Workflow

Follow these steps in order. Each step has a decision point — don't skip ahead without resolving it.

### Step 1: Define First Meaningful Success

Pick one short, authentic task that proves the product's value. "Signed up" is not success — that's just the door. Success is completing something real.

Write down:
- The success event (what specifically happened)
- The failure event (what tells you they didn't get there)
- The shortest path from entry to that success

This anchors every decision that follows. If you're unsure what counts as success, ask the user.

### Step 2: Fix the UI or Add Onboarding?

Default to improving core learnability. Tutorials are a tax on the user's patience — add them only when the UI genuinely can't teach itself. The reason this matters: if your labels are confusing, a tooltip explaining the confusing label is a band-aid. Fix the label.

Add onboarding layers only when at least one of these is true:
- The interaction paradigm is novel (users can't predict how controls work)
- Key actions are hidden and high complexity makes them hard to discover
- Early mistakes are costly or irreversible
- Mandatory setup must happen before the product delivers value

Read [decision-framework.md](references/decision-framework.md) for the full gating matrix and cognitive-load triage table.

### Step 3: Map Friction and Mental-Model Gaps

Walk through the first session as the user experiences it:

`intent → action → system feedback → user interpretation → next action`

At each step, identify:
- **Mental model mismatch**: What does the user expect to happen vs. what actually happens? These gaps cause the most confusion and are where tutorials feel necessary — but often the real fix is making the system behave more predictably.
- **Memory burden**: What must they remember across steps? (Offload this to the UI.)
- **Cognitive load type**: Is this intrinsic complexity (unavoidable domain stuff), extraneous load (UI clutter), or germane load (productive learning)? Only germane load should be preserved.
- **Error risk**: What can go wrong, and can they recover?

See [decision-framework.md](references/decision-framework.md) §3–4 for cognitive-load interventions and mental-model repair steps.

### Step 4: Choose a Scaffolding Stack

Design from least intrusive to most explicit. Start with layer 1 and only escalate when lower layers fail. This ordering matters because every layer you add costs the user attention — which is the scarcest resource in a first session.

1. **Self-descriptive UI** — Clear labels, visible affordances, consistent patterns
2. **Empty states + starter content** — Show what goes here, why it matters, one CTA
3. **Contextual hints** — At decision points, not on launch. Dismissible and reopenable.
4. **Single coach marks** — One action per mark. Never chain them.
5. **Interactive practice** — Constrained, low-risk tasks. Sandbox for risky domains.
6. **Staged wizards** — Only for truly sequential, dependency-bound setup.
7. **Persistent help** — Always-visible path back to guidance (`?` button, tips panel).

Read [pattern-playbook.md](references/pattern-playbook.md) for the full pattern selection table with implementation rules and anti-patterns for each.

**Common mistake to avoid:** Don't build a front-loaded feature tour and call it onboarding. Users skip them, resent them, and forget everything immediately. If guidance can't be rediscovered later, it doesn't count.

### Step 5: Design Adaptive Guidance and Fading

Static help that never adjusts is either too much for experienced users or too little for struggling ones. Use behavior signals to tune guidance:

**Trigger more help when:**
- Repeated errors on the same action (they're stuck)
- Backtracks within a short window (they're lost)
- Long hesitation on a critical step (they're unsure)
- Feature thrashing without completing anything (they're exploring aimlessly)

**Fade help after consistent success:**
- Collapse verbose hints into brief reminders
- Hide coach marks they've already acted on
- Shift from directive prompts to optional reference

The key principle: guidance should always be **skippable now** and **recoverable later**. Never lock help behind a one-time modal that can't be reopened.

### Step 6: Accessibility and Safety

These aren't nice-to-haves — they determine whether your onboarding actually works for all users:

- All guidance UI must be keyboard-navigable and screen-reader accessible
- Overlays and modals must not trap focus
- Critical information must never live only inside tooltips (they disappear)
- Risky actions get progressive enabling — don't let a new user accidentally delete their work
- Provide undo, safe defaults, and clear recovery paths

### Step 7: Instrument and Validate

Measure whether your onboarding actually improves outcomes. The metrics that matter:
- **Time to first meaningful success** (your north star)
- **Activation rate** on critical milestones
- **Early error rate** and **recovery rate**
- **Help rediscovery rate** (do people find guidance when they need it later?)

Run a no-onboarding baseline first. If your guidance doesn't beat the baseline on effectiveness, efficiency, and satisfaction — remove it. Onboarding that doesn't measurably help is just noise.

Read [measurement-experiments.md](references/measurement-experiments.md) for the event schema, experiment card template, and adaptive trigger thresholds.

## Game and Interactive Tutorials

Games deserve special attention because they teach through play, not through documentation. The best game tutorials are invisible — the player learns by doing, constrained by level design.

**Core loop: Show → Do → Reinforce**
- **Show**: Demonstrate the mechanic in a controlled moment (environmental cue, NPC action, scripted event)
- **Do**: Let the player try it immediately with training wheels (constrained space, reduced enemies, forgiving timing)
- **Reinforce**: Create a situation soon after where they use it again voluntarily

**Design principles for game onboarding:**
- Introduce one mechanic at a time. Don't stack new concepts.
- Use constrained practice rooms or safe scenarios before full complexity.
- Teach through level design and environmental sign-posting, not text dumps.
- Keep the HUD minimal at start — reveal advanced info as the player earns it.
- Maintain consistent visual semantics: same color and placement for similar action types.
- Let the player fail safely. Recoverable failure teaches faster than prevention.

**Anti-patterns in game tutorials:**
- Unskippable cutscenes that explain controls
- Pausing gameplay to display text walls
- Forcing the player through every feature before letting them play
- Tutorial pop-ups during intense moments
- "Press X to continue" chains with no actual practice

## Deliverables

Scale your output to the request. A quick "help me improve my tutorial" doesn't need all 8 items. A full onboarding redesign might. Use judgment.

The full deliverable set:
1. **First-session fluency blueprint** — The path from entry to first success
2. **UI fixes list** — What to improve before adding any tutorial layer
3. **Pattern stack plan** — Which scaffolding patterns apply to which screens
4. **Adaptive trigger/fading table** — When help appears and when it withdraws
5. **Microcopy pack** — Actual text for hints, empty states, error messages
6. **Accessibility checklist** — Keyboard, screen reader, focus management
7. **Instrumentation plan** — Event names, properties, success metrics
8. **Experiment plan** — Including a no-onboarding control condition

## References

Consult these for detailed tables, matrices, and templates:
- [decision-framework.md](references/decision-framework.md) — Gating matrix for UI fix vs. onboarding, cognitive load triage, scaffolding functions, friction test
- [pattern-playbook.md](references/pattern-playbook.md) — Pattern selection table with implementation rules, layering strategy, microcopy rules, game-specific patterns
- [measurement-experiments.md](references/measurement-experiments.md) — Core metrics, event instrumentation schema, experiment card template, adaptive guidance triggers, interpretation rules