What is the onboarding-ux skill?
The onboarding-ux skill is a SKILL.md in the dev-tools plugin of jezweb's skills repository. It has the agent browse a web app as a new user, find empty screens and unexplained features, write an audit report, then generate the components and copy that fix them.
A new user logs in and meets an empty table, a sidebar of unfamiliar labels and no hint where to start. The onboarding-ux skill, part of the dev-tools plugin in jezweb's skills repository, exists to find those moments and fix them.
It works in two phases. First the agent browses the app as a newcomer and writes an audit. Then it generates the actual copy and code for the gaps it found, matching the component patterns already in the project.
What the audit checks
- Empty states: what a zero-data page shows, whether a clear action such as Add your first client is offered, and whether the page explains the feature.
- First impression: whether a new user can tell within 10 seconds what the app does and which action to take first.
- Feature discoverability: whether features, filters, bulk actions, shortcuts and settings can be found and understood.
- Contextual help: missing field help, jargon, unexplained destructive actions and error messages that do not say how to fix the mistake.
What it generates
- Empty state components with a title, a one sentence description and a next action.
- A dismissable welcome banner for apps with 3 to 5 features, or a getting-started checklist for apps with 6 or more.
- A react-joyride tour configuration, with the data-tour attributes to add to existing components.
- Tooltip copy, one-time contextual hints, realistic seed data and help page content written from the app itself.
Who the onboarding-ux skill is for
Best for
- Web apps that work but leave new users facing blank screens, such as client lists, dashboards and settings pages.
- Developers who want finished copy and React components instead of a list of advice.
- Projects already using shadcn/ui, since the skill matches it when present.
Not for
- Native mobile apps. The audit drives a browser, so the app needs a URL.
- Setups with no browser tool. It detects Chrome MCP, Playwright MCP or playwright-cli, and needs one of them.
- Visual critique of finished screens. For that, see critique or kwp-design-critique.
Use it with UiChemy
This skill targets the app behind a login, not the public site around it. UiChemy covers that site: build marketing pages from Figma with Figma to WordPress or refine them in Composer, and Get Started there. For conversion on those pages, see page-cro.
How to install Onboarding UX Skill: Audit and Fix New User Flows
/plugin marketplace add jezweb/claude-skillsAdd the marketplace
Run
/plugin marketplace add jezweb/claude-skillsonce. This is the README's Quick Start.Install dev-tools
Run
/plugin install dev-tools@jezweb-skills. The onboarding-ux skill sits in that plugin beside ux-audit and other tools. The frontmatter lists compatibility as claude-code-only, so these steps assume Claude Code.Give it a browser
Make sure Chrome MCP, Playwright MCP or playwright-cli is available, since the audit phase browses the running app.
Ask for an audit
Use a trigger phrase from the skill description, such as onboarding, empty states, feature tour or new user experience, and point the agent at your app.
Check that it loaded
Ask for an onboarding audit of a running app. The agent should browse the pages and write audit.md under .jez/artifacts/onboarding/ before generating components.
Key features
- Browse as a new userThe agent walks every page like a brand new account, using a detected browser tool, and prefers a deployed URL over localhost when one exists.
- Empty state auditEach zero-data page is checked for helpful copy, a clear action and an explanation of the feature, not an empty table that repeats the populated layout.
- First impression checkAsks whether the dashboard shows something useful, whether the first action is obvious, and how many menu items compete for attention.
- Discoverability and help gapsLooks for buried features, hidden shortcuts, jargon labels, missing field help and consequences that are not explained before destructive actions.
- Audit reportWrites a report to .jez/artifacts/onboarding/audit.md with a first impression score from 1 to 5, empty states found, missing guidance and the top five quick wins.
- Welcome banner or checklistChooses a dismissable banner for simple apps and a progress checklist for complex ones, each as ready React code.
- Feature tourGenerates react-joyride steps and the data-tour attributes. The skill advises a maximum of 5 steps because longer tours annoy people.
- Tooltips and hintsProduces a map of field names to tooltip text, plus one-time hints that remember their dismissal in localStorage.
- Seed data that teachesWrites sample records in each state, such as draft, active, completed and archived, with realistic names instead of Test Client.
- Help page contentDrafts FAQ answers from the real app, with numbered steps for tasks like adding a client, ready to feed a user guide.
Frequently asked questions
What is the onboarding-ux skill?
It is a skill from the jezweb skills repository that audits a web app for onboarding gaps and then builds the fixes. It covers empty states, first-run welcome content, feature tours, tooltips, contextual hints, seed data and help page content, written to match your project.
How do I install the onboarding-ux skill?
Run /plugin marketplace add jezweb/claude-skills, then /plugin install dev-tools@jezweb-skills. The onboarding-ux skill is one of the skills inside the dev-tools plugin. After that it triggers from phrases such as onboarding, empty states or make the app welcoming.
Which AI coding agents can use the onboarding-ux skill?
The SKILL.md frontmatter declares compatibility as claude-code-only, and the repository describes itself as skills for Claude Code. Other agents are not documented, so treat it as a Claude Code skill and test carefully before relying on it elsewhere.
What does the onboarding-ux skill need to run?
A browser tool. The skill says to detect Chrome MCP, Playwright MCP or playwright-cli, and to prefer a deployed or live URL over localhost. It also reads your codebase so generated components follow the patterns and component library already in use.
Where does the onboarding-ux skill save its output?
Everything goes to .jez/artifacts/onboarding/. That folder gets audit.md, empty-states.tsx, welcome-banner.tsx, tour-steps.ts, tooltip-content.ts, contextual-hints.tsx, seed-data.ts and help-content.md, plus an onboarding checklist file for complex apps. The agent then says where to integrate each file.
How is onboarding-ux different from ux-audit?
The SKILL.md says the two pair up: ux-audit finds problems and onboarding-ux builds the solutions. Running a thorough ux-audit first gives this skill its findings as input, though onboarding-ux also runs its own audit phase. For wider UX thinking, see ux-design.
Does the skill fix problems in the live app?
It generates files in .jez/artifacts/onboarding/ and tells you where each one belongs, with instructions like adding a component to the clients page when the list is empty. You or the agent then wire them in. Use frontend-visual-qa afterward to check the result.
How many steps should a feature tour have?
The skill's tips say a tour should be no longer than 5 steps, and that contextual hints should be dismissable and shown only once. It also says empty states are the highest impact change, so it recommends doing those first.