Onboarding Flows skill for Claude Code

Onboarding is done when a new user reaches the product’s activation moment — the first time they get the outcome they signed up for — in the fewest possible steps, can leave and resume without losing progress, and every screen between signup and that moment has earned its place with data.

Scope

This skill owns the in-product first-run journey. Lifecycle emails that nudge users back belong to email-campaigns; empty, loading and error state design to empty-error-states; wording of tips and buttons to ux-microcopy; event tracking setup to product-analytics; A/B test design to conversion-optimization.

Ground rules

• Onboarding is the product, not a layer on top. If a tour is needed to explain a screen, fix the screen first.
• Every step before activation must either be required to deliver value or measurably improve it. Everything else is deferred.
• Doing beats showing: a user who creates one real invoice learns more than one who watches five tooltips about invoices.
• Personalization questions must change what the user sees next. If the answer is only stored for marketing, cut the question or move it after activation.
• Progress persists server-side per user and account. LocalStorage-only onboarding restarts on every new device and breaks for invited teammates.

Workflow

- [ ] 1. Define the activation moment and current baseline
- [ ] 2. Map the current path from landing to activation; count steps and time
- [ ] 3. Cut, defer or automate steps
- [ ] 4. Choose first-run patterns per step
- [ ] 5. Design the hand-off into normal use (empty states, checklist, return path)
- [ ] 6. Specify state, skip/resume, and events
- [ ] 7. Prototype, walk it as a new user, measure, iterate

1. Activation moment

Define it as an observable event, ideally validated against retention:

• Candidates: “sent first invoice”, “connected a data source and saw a chart”, “invited one teammate who logged in”, “deployed first project”.
• Validate: compare 30-day retention of users who did vs did not hit each candidate within their first week (correlation, not proof, but it ranks candidates). Pick the one with the biggest retention gap that a new user can reach in one session.
• Record baselines: signup → activation rate, median time to activation, and the step with the largest drop-off.

If there is no data yet, state the assumed moment explicitly and instrument it first.

2. Map the path

Walk the flow as a brand-new user (incognito, new email). List every screen, field, decision and wait (email verification, data import, approval). Time it. Typical findings: verification email blocking first use, a 9-field signup, a mandatory plan choice, an empty dashboard with no next step.

3. Cut, defer, automate

Step	Default decision
Email verification	Let users in immediately; require verification before sending, inviting or billing
Signup fields beyond email/password or SSO	Defer: name, company, role, phone after activation or when needed
Plan / payment selection	Defer to trial end unless the business model requires card upfront
Workspace naming	Auto-generate from email domain or name; editable later
Profile photo, notification preferences	Defer entirely; sensible defaults
Importing data	Offer import, but also a path with sample data or a template
Integrations	Only if activation depends on them; otherwise surface after activation

Offer SSO (Google, Microsoft, GitHub for dev tools) above the email form — it removes the password step for most B2B users.

4. First-run patterns

Pattern	Use when	Avoid when
Template gallery	Creation products (docs, sites, dashboards, automations)	Templates are generic filler that users delete
Sample data / demo workspace	Value depends on data the user has not imported yet	Sample data mixes with real data without a clear label and one-click clear
Setup wizard (2–4 steps)	Configuration is truly required (connect domain, pick data source)	Steps are optional; wizards over 5 steps lose users
Getting-started checklist	3–5 independent actions lead to full value	Used as a to-do list of every feature
Contextual hints	A feature is non-obvious at the moment of use	Shown on first load for features not yet relevant
Empty state with one primary action	Every list/collection screen on first visit	— always design these
Product tour (modal sequence)	Rarely; a major redesign for existing users	First-run for new users — completion and recall are poor

Banned defaults: a 5-slide “Welcome to Acme” carousel on first load, tooltips pointing at every nav item, confetti for clicking “Next”, an auto-playing video before the user can touch anything, and a checklist whose first unchecked item is “Watch our intro video”.

5. Checklist and hand-off design

• 3–5 items, each a real outcome (“Send your first invoice”), not a feature visit (“Explore Reports”). Order by dependency, then by value.
• Pre-complete the first item from signup (“Create your account”) so the user starts with visible progress.
• Each item deep-links to the exact place and state where it is done, and completes automatically from the real event — never a manual “Mark as done”.
• Persistent but dismissable (collapsed into a small progress pill after dismissal); disappears for good once complete, with a brief acknowledgment.
• Empty states carry the hand-off: one sentence on what will appear here, one primary action, and the option to load sample data or a template.
• Invite teammates after the user has made something worth sharing, not at step 2 — unless the product is useless alone (chat, multiplayer), in which case invite is the activation path.

6. State, skipping and events

Model onboarding as explicit state, stored on the server:

type OnboardingState = {
  userId: string;
  accountId: string;
  role: "owner" | "invited";            // invited users skip workspace setup
  steps: Record<"profile" | "connect_source" | "first_report" | "invite", {
    status: "pending" | "done" | "skipped";
    at?: string;                         // ISO timestamp
  }>;
  checklistDismissed: boolean;
  activatedAt?: string;                  // set by the activation event, never by the UI
};

• Every step is skippable unless technically required; record skips as data.
• Invited users get a different, shorter path (they join an existing workspace) — this is the most commonly forgotten branch.
• Resume: returning users land on the next incomplete step or the checklist, never back at step 1.
• Gate the flow behind a feature flag so variants can be tested and rolled back.
• Events (names follow the project’s taxonomy): signup_completed, onboarding_step_completed {step}, onboarding_step_skipped {step}, checklist_dismissed, activation_reached {days_since_signup}.

Tour/hint libraries if needed: Driver.js, Shepherd.js, React Joyride (open source); Appcues, Userflow, Chameleon, Pendo (hosted, let non-engineers edit). Whatever the tool: Esc closes, focus moves into the hint and returns to the trigger, nothing auto-advances on a timer, and reduced-motion is respected.

7. Prototype and iterate

• Walk the flow on a fresh account on desktop and a phone; note every hesitation.
• Five moderated sessions with target users reveal most blocking issues; watch for where they stop reading and start guessing.
• After launch, compare cohorts weekly: activation rate, median time to activation, day-7 retention, and step-level drop-off. Change one thing at a time.

Gotchas

• Asking “What’s your role?” and then showing everyone the same screens.
• Sample data that looks real and ends up in exports or invoices — label it and give a one-click “Clear sample data”.
• Onboarding that only works for the account owner; invited members see setup steps for a workspace that already exists.
• Measuring checklist completion instead of activation — users can tick boxes without getting value.
• Gating the entire app behind a mandatory wizard; users who know what they want get stuck. Always offer “Skip for now”.
• Re-showing the welcome flow after a cleared cookie or new device because state lived in the browser.

Output contract

**Activation moment:** first report viewed with real data (30-day retention 61% vs 18%)
**Baseline:** 23% of signups activate; median 2.4 days; biggest drop: connect-source step (54% leave)
**New path:** SSO signup → pick template (or sample data) → connect source (skippable) → first report
**Deferred:** company name, role, phone, plan choice, notifications
**Checklist (4):** Create account (done) · Connect a source · Build a report · Invite a teammate
**Invited-user path:** join → first report from shared source
**State & events:** OnboardingState on server; 5 events; behind flag onboarding_v2
**Success metric:** activation 23% → 35% within 7 days of signup; guardrail: D30 retention flat or up