TLDR: When onboarding a non-technical user to Claude Code, the entry point isn't a checklist. It's one prompt they paste — and the agent does the setup for them.

The Build

I was putting together an onboarding page for my coach, a coach setting up his first Claude Code stack (Claude Code, my AI-in-the-terminal assistant I use to build and run agents).

The goal: session prep, client brief summaries, follow-up drafts — all the repetitive stuff an agent can handle.

My coach is not technical. That's the whole point. I needed to get him from zero to a working agent without him ever needing a terminal.

My first design: a two-pane page with 11 numbered steps on the left. Run mkdir. Paste this into that file. Now this command. OAuth here. Browser cookie there.

What Broke

It was wrong from the start. I knew it the moment I shipped it.

The problem isn't the checklist idea — it's the context-switching. Shell. Browser. File editor. OAuth flow (which has ~8 distinct Cloud Console clicks on a good day). Each switch is another place a non-technical user can stall and feel dumb.

"Friction city. Stops working at step 3 when Google OAuth needs a screenshot." Exactly. Nothing else on the page saves them after that.

The Reframe

The feedback that changed everything: "Give a one shot copy prompt he can give to his agent and highlight it as the place to really get started, make sure his agent positions as helping someone non-technical get started."

So obvious once you hear it.

My coach doesn't need a checklist. My coach needs to paste one block of text and have the agent walk him through the rest. The user becomes a conversational participant instead of a terminal operator.

What I Built Instead

I replaced the entire left pane with a single card. Terracotta border. ★ START HERE pill in the corner. The heading: "One prompt. Paste it into your first session."

The prompt tells the agent to:

  • WebFetch the onboarding page and absorb the context itself
  • Create the workspace — mkdir, write CLAUDE.md, write the skill files via its own tool use
  • Walk through MCP installs (the third-party integrations) one at a time, waiting for the user to say "done" between each
  • Pause at known friction points — Google OAuth specifically — and offer to slow down and step through them
  • Run a self-test to confirm the setup actually worked
  • Suggest one immediate thing to try so the user doesn't sit at a blank prompt wondering what just happened

And the prompt positions the agent explicitly:

"I am NOT technical. Walk me through every step, do the work for me wherever you can, and ask before doing anything irreversible."

That framing is NOT optional. Without it, the agent assumes terminal competence and skips right past the hand-holding my coach actually needs.

The prompt is also safe to re-paste. The agent detects partial state — "I see ~/Coaching/CLAUDE.md exists but Loom isn't installed yet — picking up from there" — so if he has to stop halfway, he pastes again and keeps going. No starting over.

The 11-step checklist didn't disappear. It's still there as reference material — "if you want to see what's happening under the hood." It's just no longer the entry point.

Why This Matters to Me

I build these stacks for people who aren't builders. That's the whole value. If my onboarding feels like a developer README, I've already failed them.

One prompt. Agent does the work. User has a conversation.

That's the pattern I'm reaching for first, from now on.