How to use the User Onboarding Optimizer agent skill

What is an agent skill and what does this one make the agent do?

An agent skill is a folder containing a SKILL.md file with instructions, plus optional reference files, that an AI agent loads when a request matches the skill's description. Once this skill is installed, the agent treats user onboarding as a conversion and retention problem rather than a generic design question.

In practice, the agent asks about your product and what counts as a user's "aha moment", recommends the shortest path from signup to first real value, suggests checklists, empty states and first-run screens, and helps you choose an activation model such as freemium or free trial. It also explains how to find which early actions predict long-term retention, using cohort logic that avoids common analytics mistakes.

Install the onboarding skill

Download the ZIP file for the skill from the page you are reading, then choose one of these options.

The skill is packaged as a folder named onboarding containing SKILL.md, references/activation-models.md, references/experiments.md, references/minimum-path-to-value.md and evals/evals.json.

• Personal install: unzip the file into ~/.claude/skills/ so the skill is available across your projects.
• Project install: unzip the file into the .claude/skills/ folder inside a specific project so it applies only there.
• Claude apps: upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

Trigger the skill with natural requests

You do not need a special command. The skill's description lists phrases that route a request to it, so describe your problem in plain language. Phrases that match include "onboarding flow", "activation rate", "empty states", "onboarding checklist", "aha moment", "time to value", "first session experience", "users aren't activating" and "users sign up but don't use the product".

If you ask about signup or registration forms, the skill points you to a separate signup skill. For ongoing email sequences, it points to an emails skill.

• "Our users sign up but never create a project. How do I fix onboarding?"
• "Help me find the aha moment for our analytics app."
• "Design an onboarding checklist for a self-serve B2B tool with five setup steps."
• "Our activation rate is low. Where should I look first?"
• "Which activation model fits a complex product with a long setup: freemium or a free trial?"

What to provide so the output is useful

The skill begins by asking questions, and it checks for a product marketing context file (such as .agents/product-marketing.md or .claude/product-marketing.md) if one exists. The more you share up front, the less back-and-forth you need.

Useful inputs are the product type (B2B or B2C), the core value proposition, what action you believe signals that a user gets it, and where users drop off after signup. If you have usage data, include the signup and activity numbers you already track.

• Product type and core value proposition
• Your current guess at the aha moment
• Where in the post-signup experience users leave
• Any usage data you can share, such as signup cohorts and early actions

Find your aha moment with cohort logic

The skill's method for finding the aha moment is careful about timing. It defines signup as time zero, an early activation window and a separate retention outcome that comes after it. Actions used to predict retention must be recorded inside the early window, so a week-four return cannot also count as the predictor of week-four retention.

It also asks you to include all eligible signups with full follow-up, and to show recent cohorts separately rather than counting them as churned. Treat any high-correlation event as a hypothesis, check it on a later mature cohort, and then test whether an onboarding change actually improves retention. The skill notes that correlation alone does not prove that forcing an action causes retention.

• Example by product type: project management, create first project and add a team member.
• Example for analytics: install tracking and see first report.
• Example for a design tool: create first design and export or share.
• Example for a marketplace: complete first transaction.

Safety notes: scripts and network access

This skill does not run scripts and does not use the network, according to its listing. It requires nothing beyond the agent itself. Its outputs are recommendations and experiment plans, so you still need your own analytics data and your own tooling to measure results.

The skill references Amplitude's Compass documentation for aha-moment analysis. Those links are reference material for you to read; the skill itself does not fetch them.

• Runs scripts: no
• Uses network: no
• Requires: nothing listed

Tips for getting the most from the skill

Bring real numbers where you have them, and say how old each cohort is. Ask for experiment ideas from the reference list when you want to test changes, such as email verification timing, empty states versus dummy data, or pre-filled templates.

Keep the first session to one successful outcome. The skill's guidance favours interactive steps over tutorials and skippable guidance over forced tours.

• Pick an activation model before designing the flow, because the model shapes the whole path.
• Limit checklists to about 3 to 7 items, ordered by value, with a dismiss option.
• Design empty states as guided first actions, not dead ends.