ux-help-onboarding
Skill21 starsChanged 5 months agoMITView on GitHub
Onboarding and help UX: first-run flows, loading states, skeleton screens, tooltips, contextual help, and in-app support. Use when designing or reviewing first-run experiences, feature discovery flows, contextual help, loading indicators, or in-app support.
In this repository17 other files it gives its agents.
- ux-accessibilitySkill
- ux-ai-automationSkill
- ux-contentSkill
- ux-error-handlingSkill
- ux-formsSkill
- ux-generalSkill
- ux-information-architectureSkill
- ux-navigationSkill
- ux-networkSkill
- ux-notificationsSkill
- ux-reviewSkill
- ux-safety-privacySkill
- ux-searchSkill
- ux-settingsSkill
- ux-user-accountSkill
- ux-utilitySkill
- ux-visual-designSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
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
- Distinctive: line 43
Use 2 to 3 generic rows rather than matching the exact final count of items.
- Distinctive: line 54
Use tooltips and coach marks at the right contextual moment rather than a long intro tutorial.
- Distinctive: line 82
When applying this checklist to a screen, flow, or codebase:
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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.
Files
Help and Onboarding UX
Onboarding sets the trajectory of a user's entire relationship with the app. A great first run converts. A confusing one churns. And once users are in, good help systems make them feel confident rather than lost.
Checklist
| Item | Guidance |
| 10-second comprehension | A first-time user understands the core value of the app within 10 seconds of first launch. |
| Loading indicator | Spinner or progress bar shown for anything taking longer than 400ms. |
| Skeleton screens | Used instead of spinners for content-heavy screens during loading. |
| Onboarding flow | Demonstrates value through experience, not a feature list. |
| Skip onboarding | A "Skip" option is visible on every onboarding step. |
| Contextual tooltip | Shown on first visit to a complex screen. One concept only. Easily dismissible. |
| In-app help center | Searchable help content within the app. Does not redirect to a website. |
Loading State Guidelines
| Duration | Recommended pattern |
| Under 400ms | No indicator needed — feels instant |
| 400ms to 3 seconds | Skeleton screen (content-shaped placeholder) |
| 3 to 10 seconds | Progress bar with an estimated time remaining |
| Over 10 seconds | Background task with a push notification on completion |
Skeleton screen design: Match the shape of the real content — rectangles for images, lines for text. Animate with a shimmer sweeping left to right. Use 2 to 3 generic rows rather than matching the exact final count of items.
Onboarding Patterns
Value-first: Show what the app does through demonstration before asking for anything. Delay sign-up until the user has experienced something meaningful. This consistently reduces early drop-off.
Progressive: Introduce features as users encounter them, not all at once. Use tooltips and coach marks at the right contextual moment rather than a long intro tutorial.
Blank slate: First-time empty screens actively invite the first action.
"Add your first task" beats an empty list with no direction. Full empty-state
standards live in ux-error-handling.
Permissions: Pre-permission screens explain why each permission matters before the system dialog appears. Request permissions in sequence and only when the feature that needs them is first used.
Onboarding Do and Don't
| Do | Don't |
| Show, don't tell | List feature bullet points |
| One concept per screen | Overwhelm with all features at once |
| Show progress ("2 of 4") | Give no sense of how long onboarding is |
| Keep Skip visible on every step | Force completion of all steps |
| Let users revisit onboarding in Settings | Assume one viewing is enough |
| Personalize on the first step | Ask for an account before showing value |
How to Review
When applying this checklist to a screen, flow, or codebase:
- Go through every checklist item and mark it Pass, Fail, or N/A — never skip items silently.
- Cite specific evidence for each finding: the screen, component, file, or line it applies to.
- Tag each failure with a severity: Blocker (breaks the experience), Major (hurts usability), or Minor (polish).
- End the review with the top 3 recommended fixes, ranked by user impact.
Related Skills
ux-content— onboarding copy and tooltip writingux-error-handling— canonical empty-state standardsux-safety-privacy— permission prompt timing during onboardingux-notifications— when to ask for notification permission
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
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.