agentleFS
botirkhaltaevbotirkhaltaev/botir-skills/skills/onboarding-ux/SKILL.md

onboarding-ux

Skill4 starsChanged 3 months agoApache-2.0View on GitHub

Design first-time experiences that activate users. Covers progressive disclosure, activation milestones, persona-based onboarding, empty states, checklists, tooltips, and measuring onboarding success. Use when designing first-time user experiences, improving activation rates, or reducing early churn. Triggers on: "onboarding", "first time user experience", "FTUE", "user activation", "progressive disclosure", "empty state", "product tour", "user checklist".

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 6 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Ask one segmentation question, route to different experiences.

    line 47
  2. Distinctive:

    Ask after signup, not before

    line 53
  3. Distinctive:

    Always show how to dismiss

    line 71
  4. Distinctive:

    Never show the same tooltip twice

    line 72
  5. Distinctive:

    Rule: Don't show everything on Day 1.

    line 79
  6. Distinctive:

    Rule: Every empty screen a new user might see needs a clear next action.

    line 90

≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Onboarding UX

Onboarding is the bridge between signup and value. Poor onboarding is the single largest driver of early churn.

"The shorter the path from sign-up to 'I see why this matters,' the higher your activation rate." — Samuel Hulick

The Activation Framework

Define Your Activation Milestone

The single action or outcome that signals a user has found value. Examples:

  • Slack: sent first message
  • Dropbox: uploaded first file
  • Canva: created first design
  • Airbnb: completed first booking

Rule: Build backward from this milestone. Strip everything that doesn't advance the user toward it.

The 3-Phase Onboarding Model

PhaseWhenGoalPatterns
Welcome & SegmentFirst 30 secondsSet direction, personalizeWelcome message, persona survey, branched paths
Guided ActivationFirst sessionReach activation milestoneChecklists, tooltips, product tours, empty states
Progressive DiscoveryDays 2-30Introduce advanced featuresContextual tips, feature announcements, re-engagement

Onboarding Patterns

Pattern: Welcome Message

A simple greeting that sets direction. Not a feature tour.

Good: "Welcome to Acme. Let's connect your calendar so you can start saving time." Bad: "Welcome! Here are 12 features you can explore."

Pattern: Persona-Based Branching

Ask one segmentation question, route to different experiences.

Example: ConvertKit asks: "Are you migrating from another platform or starting fresh?" → different paths.

Rules:

  • 2-5 options max
  • Ask after signup, not before
  • Make it feel like personalization, not a survey

Pattern: Checklist

A list of setup tasks with progress indicator.

Best practices:

  • 3-5 items max (more = overwhelming)
  • Mix easy and medium tasks (builds momentum)
  • Show progress visually (Zeigarnik effect: incomplete tasks create pull)
  • First item should be trivial to complete

Pattern: Contextual Tooltips

Highlight features when users first encounter them.

Rules:

  • One tooltip per new screen
  • Point to one element, not the whole UI
  • Always show how to dismiss
  • Never show the same tooltip twice

Pattern: Progressive Disclosure

Introduce features as they become relevant across multiple sessions.

Example: Grammarly starts with grammar checking, introduces tone detection after a few sessions, then style guides.

Rule: Don't show everything on Day 1. Stage across the first week.

Pattern: Empty States

Turn blank screens into starting lines.

TypeApproach
First-useInstruction + CTA: "Create your first project"
User-clearedConfirmation + undo: "You deleted all items. Undo?"
No resultsSuggestions + reset: "No results. Try: broader terms, fewer filters"

Rule: Every empty screen a new user might see needs a clear next action.

Measurement

Key Metrics

MetricWhat It MeasuresTarget
Activation rate% reaching activation milestone>37.5% (2025 SaaS median)
Time to first valueMinutes from signup to activationAs low as possible
Tour completion rate% finishing onboarding flowContext-dependent
Session 2 return rate% who come back>40%
Day 7 retention% active after 7 daysBenchmark against median

Diagnostic Signals

SignalProblemFix
High tour completion, low activationTour disconnected from valueConnect tour steps to activation actions
Activation varies by segmentOne-size-fits-all flowAdd persona-based branching
Session 2 return <40%No re-engagement planAdd behavioral triggers for days 2-3
>5 tour steps, completion <50%Flow too longCut to 5 steps max

Common Mistakes

  • Front-loading everything — showing all features on Day 1
  • Mandatory tours — users want to explore, not be briefed
  • Measuring completion, not activation — a completed tour is not success
  • No skip option — some users don't need onboarding
  • One flow for all users — different segments need different paths

Reference Map

  • references/activation-milestone.md — defining activation, metrics, diagnostic matrix
  • references/pattern-selection.md — checklist vs tour vs empty-state decision tree

Related Skills

  • For empty / error / recovery states → use error-empty-states
  • For interaction pattern context → use interaction-design-patterns
  • For progressive disclosure principles → use information-architecture
  • For form-heavy activation → use form-ux
  • For UX writing in onboarding → use ux-writing-content-design

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.