1---
 2tagline: "Design first-run experiences, empty states, and paths to value."
 3---
 4
 5## When to use it
 6
 7`/onboard` is for the moments that decide whether a new user sticks around: the first screen, the empty state, the setup flow, the product tour, the "what do I do now" gap. Reach for it when activation is weak, when new users drop off before reaching value, or when your product has empty states that say "no items yet" and stop there.
 8
 9## How it works
10
11The skill starts from one question: what is the aha moment, and how fast can a new user get there. Every design decision points at that moment.
12
13It works across the surfaces that shape first impressions:
14
151. **First-run experience**: the moments immediately after sign-up. Should the user see a tour, a blank canvas, a filled example, or nothing at all. Pick the approach that matches the product.
162. **Empty states**: every zero-data screen gets oriented. Where am I, why is this empty, what do I do next, what will it look like once it is full.
173. **Setup and installation**: required configuration is minimized, defaults are smart, each step explains why it matters.
184. **Progressive disclosure**: advanced features stay out of the way until they are earned.
195. **Activation events**: the moment a user first experiences the core value is instrumented and celebrated, quietly.
20
21The skill resists two common failure modes: over-tutorialized onboarding where users click through a carousel before they can touch anything, and zero-onboarding where users are dropped into an empty app and expected to figure it out.
22
23## Try it
24
25```
26/onboard the editor
27```
28
29Typical output:
30
31- First-run: replaces empty editor with a filled example document the user can modify. Cancel button discards the example, edit replaces the content with the user's work.
32- Empty state on document list: "No documents yet. Create your first, or import from Notion, Google Docs, or Markdown."
33- Setup: reduced from 6 required fields to 1 (workspace name). Everything else has a smart default and can be edited later in settings.
34- Activation: the first time a user saves a document, a quiet toast says "Saved. Your work is in the cloud now." One-time, not repeated.
35
36## Pitfalls
37
38- **Adding a product tour as the default answer.** Most products do not need a tour. They need a better first screen. Tours are a crutch.
39- **Designing onboarding without defining the aha moment.** If you cannot say in one sentence what the user should feel in the first 60 seconds, go back to `/shape` first.
40- **Running onboard on a broken flow.** Fix the flow first. Onboarding cannot rescue a product where the core action is broken.