Audit and generate in-app user guidance — onboarding flows, empty states, tooltips, feature tours, contextual help, defaults, and inline hints. Browses the app to find where new users would get stuck, then produces the actual content and code to fix it. Pairs with ux-audit:
Installs just this skill. Get the whole plugin for auto-invocation.
⚡ How it fires
How this skill gets triggered: by you, by Claude, or both.
Fires itselfClaude auto-loads it when your prompt matches the work.
You can call itInvoke it directly when you want it.
Slash command/onboarding-ux
👁️ Context preview
The summary Claude sees to decide when to auto-load this skill.
Audit and generate in-app user guidance — onboarding flows, empty states, tooltips, feature tours, contextual help, defaults, and inline hints. Browses the app to find where new users would get stuck, then produces the actual content and code to fix it. Pairs with ux-audit:
📊 Stats
Stars940
Forks96
LanguagePython
LicenseMIT
📦 Ships with jezweb-skills
</> SKILL.md
onboarding-ux.SKILL.md
---name: onboarding-ux
description: "Audit and generate in-app user guidance — onboarding flows, empty states, tooltips, feature tours, contextual help, defaults, and inline hints. Browses the app to find where new users would get stuck, then produces the actual content and code to fix it. Pairs with ux-audit: audit finds problems, this skill builds the solutions. Triggers: 'onboarding', 'help content', 'empty states', 'user guidance', 'first run experience', 'feature tour', 'app is confusing', 'new user experience', 'make the app welcoming'."
compatibility: claude-code-only
---# Onboarding UX
Audit a web app for onboarding gaps, then generate the in-app guidance to fix them. The goal: a new user should never stare at a blank screen wondering what to do.
## The Problem This Solves
You've built the features. They work. But when a new user logs in for the first time, they see:
- Empty tables with column headers and nothing else
- Sidebars full of labels that mean nothing to them yet
- No indication of where to start or what the app is for
- Features they don't know exist because nothing points to them
This skill finds those gaps and produces the content and code to fill them.
## Browser Tool Detection
Same as ux-audit — detect Chrome MCP, Playwright MCP, or playwright-cli. See ux-audit's browser-tools.md reference if needed.
## URL Resolution
Same as ux-audit — prefer deployed/live URL over localhost. Check wrangler.jsonc, CLAUDE.md, or running dev server.
## Workflow
### Phase 1: Audit — Find the Gaps
Browse the app as a brand new user. On every page, evaluate:
#### Empty States
Navigate to every list/table/collection page. For each:
| Check | Good | Bad |
|-------|------|-----|
| What does a zero-data page show? | "No clients yet. Add your first client to get started." + CTA button | Empty table with column headers, or blank white space |
| Is there a clear action? | Button: "Add your first [thing]" | Nothing — user has to find the action in the nav or a menu |
| Does it explain the feature? | "Clients are the people and businesses you work with. Add one to start tracking your relationships." | Just an empty container |
| Is the empty state designed? | Illustration or icon, helpful copy, prominent CTA | Identical to the populated state minus the data |
#### First Impression
Log in as a new user (or clear state to simulate). Evaluate:
| Check | What to look for |
|-------|-----------------|
| **Landing page** | Does the dashboard/home show something useful or is it empty? |
| **Orientation** | Within 10 seconds, do I know what this app does and where to start? |
| **First action** | Is the #1 thing I should do obvious and prominent? |
| **Cognitive load** | How many menu items, buttons, and options compete for attention? |
| **Welcome content** | Is there a welcome message, tour, or getting-started guide? Or just the raw app? |
#### Feature Discoverability
For each feature in the app:
| Check | What to look for |
|-------|-----------------|
| **Can I find it?** | Is it visible in the nav, or buried in a menu/submenu? |
| **Do I know what it does?** | Does the label explain it, or do I need to click to find out? |
| **Keyboard shortcuts** | Are there shortcuts? Are they discoverable (tooltip, help panel)? |
| **Advanced features** | Filters, bulk actions, search — are these visible or hidden? |
| **Settings and configuration** | Can I find the settings? Do I know what each setting does? |
#### Contextual Help Gaps
On each page:
| Check | What to look for |
|-------|-----------------|
| **Form fields** | Do complex fields have help text or tooltips? |
| **Jargon** | Any labels that a non-expert wouldn't understand? |
| **Consequences** | Do destructive or irreversible actions explain what will happen? |
| **Validation** | When I make a mistake, does the error message tell me how to fix it? |
#### Produce an Audit Report
Write to `.jez/artifacts/onboarding/audit.md`:
```markdown
# Onboarding Audit: [App Name]
**Date**: YYYY-MM-DD
**URL**: [app url]
## First Impression Score
[1-5] — Can a new user figure out what to do within 30 seconds?
## Empty States Found
| Page | Current state | Recommendation |
|------|--------------|----------------|
| /clients | Empty table, no guidance | Add empty state with CTA |
## Missing Guidance
| Location | Gap | Priority |
|----------|-----|----------|
| Dashboard | No welcome or getting started | High |
| Settings | No descriptions on settings | Medium |
## Feature Discovery Issues
| Feature | Problem | Fix |
|---------|---------|-----|
| Keyboard shortcuts | No way to discover them | Add help panel |
## Quick Wins
[Top 5 changes that would have the biggest impact on new user experience]
```
---
### Phase 2: Generate — Build the Solutions
After the audit, generate the actual content and code. Read the project's codebase to match the existing tech stack and component patterns.
#### 1. Empty State Components
For each empty state identified in the audit, generate a component:
```tsx
// Pattern — adapt to the project's component library
function EmptyState({ icon, title, description, actionLabel, onAction }) {
├── contextual-hints.tsx # Inline hint component + content
├── seed-data.ts # Onboarding seed records
└── help-content.md # FAQ / help page content
```
Tell the user which files were generated and where to integrate them. Provide specific instructions for each: "Add this component to your /clients page when the client list is empty."
## Tips
- Read the project's existing component patterns before generating — match the style, don't introduce new patterns
- Use shadcn/ui components if the project uses them
- Write copy as if you're a helpful colleague, not a manual
- Empty states are the single highest-impact change — do those first
- Feature tours are annoying if they're too long — max 5 steps
- Contextual hints should be dismissable and only shown once
- Sample data should look real — use realistic Australian names, domains, and details
- The help page content can be generated from the "explain it to a colleague" output of ux-audit
## Pairing With Other Skills
| If you also run... | This skill adds... |
|--------------------|--------------------|
| `ux-audit` (thorough) | Uses the audit findings as input — fixes the problems found |
| `db-seed` | Generates onboarding-quality seed data instead of generic test data |
| `app-docs` | The help page content can feed into the user guide |
| `product-showcase` | Empty states and welcome flow make demo screenshots look better |
