Onboarding for the AI agent, not the human

Ask Claude Code to set up a typical SaaS for you. It opens a browser, finds a signup form it can't fill, scrapes the docs, picks the wrong install path from three options, copies a stale example config, edits a file in ~/.config/, prompts you to restart your editor — and then doesn't know what any of the tools it just registered are for.

Twenty minutes. A few thousand tokens. A half-working install.

The problem isn't the agent. The problem is that the onboarding flow was designed for a human reading a webpage. We rebuilt ours from scratch on the opposite assumption: an agent is the one running this, not a human. This post walks through the six concrete shifts that come out of that decision.

The whole flow is one command, not a page

The single most important change: there is no "go to this page and click sign up" step. The entire flow is one command:

npx @agentled/cli setup

The agent runs this in its own shell. Bash runs on the user's machine, so the browser opens on the user's machine — the agent never needs to render HTML or click anything. This sounds obvious in hindsight. It is not how most SaaS onboards.

Why it matters: every step that requires the agent to "look at" a UI is a token sink and a failure mode. Every step that's a shell command is a primitive the agent already knows. The human still has to do one thing — log in when the browser pops — but that's the only action the agent can't perform itself.

Tools without a playbook means a confused agent

The flow installs two things, not one:

The MCP server — the tools. create_workflow, add_step, upsert_knowledge_text, start_workflow, the rest.
The AgentLed skill — the playbook. Dry-run protocol, incremental authoring rules, valid step types, credit-efficient testing patterns.

This is the shift most platforms miss. Giving an agent tools without a playbook is like dropping a junior engineer into your codebase with API access and no README. They'll do something. It will be expensive and probably wrong.

The skill auto-routes to the right place per client: ~/.claude/skills/agentled/ for Claude Code or Claude Desktop, ~/.codex/instructions/agentled/ for Codex. Clients without a native skill surface (Cursor, Windsurf today) get skipped with a hint, MCP still wired up. The agent picks the skill up on its next session and now has opinions about how to use the tools — when to dry-run before publishing, which step types are valid for which use case, how to test incrementally without burning credits.

This is the difference between an agent that has 100+ integrations available and an agent that knows which one to reach for in your first prompt.

Scaffold a working folder, don't make the agent invent one

The flow creates agentled_<workspace-slug>/ in the current directory with documented subfolders:

agentled_<workspace-slug>/
  README.md
  worklog.md
  decisions/                 # YYYY-MM-DD-<slug>.md
  workflows/                 # local pipeline JSON drafts
  groups/                    # WorkflowGroup specs
  kg/                        # local mirrors of KG schemas and text drafts
  executions/                # debug bundles for failed runs
  drafts/                    # scratch space

One folder per workspace, so an agent juggling two workspaces never crosses streams.

Why it matters: agents will write artifacts somewhere. Without a scaffolded convention, they scatter JSON drafts and worklogs at the repo root, mix them with the actual codebase, and lose them on the next session. The folder is a contract — "this is your scratch space, here is the structure, the README explains the sync rule." The agent reads the README on session start and slots into the convention.

Bonus: per-workspace folders mean an agent that's been working on workspace A and gets asked about workspace B doesn't have to guess which decisions log applies. It looks at agentled_<active-workspace>/ and that's the source of truth.

A knowledge probe instead of a "describe your business" form

Step six of the flow reads knowledge.company.profile from the workspace knowledge graph. If it's set, it prints a one-line summary and moves on. If it's missing, it prompts the user once for company name, website, and use case, then writes the long-form profile back to the same key via upsert_knowledge_text.

This is the part most onboarding flows get wrong twice:

They skip the "tell us about your business" step entirely — and then every later workflow has to re-elicit it from the user, badly, in the middle of unrelated work.
Or they ask it as a signup form — and the answer dies in a "company settings" tab the agent can't reach.

Storing it as a known knowledge graph key means every workflow the agent ever builds for this workspace can read the same canonical context. ICP, tone, integrations the team cares about, target market — all there, structured, queryable. The next time the agent drafts an outreach sequence, it doesn't have to re-ask the user what their company does.

The probe is idempotent: it reads what the prompt writes, so the question never re-fires on subsequent runs. Re-running setup three times doesn't mean answering the same questionnaire three times.

Tell the agent about the restart, not the user

The last step of the flow prints something like: "Restart your MCP client to pick up this workspace." The agent reads that output, understands it, and surfaces it to the user explicitly: "You need to restart Claude Code (/mcp reconnect or new session) before the new tools show up."

The user doesn't have to notice MCP tools are missing and figure out why on their own.

Tiny thing. Huge UX delta. The default failure mode of every MCP install is "I ran the thing, why don't I see the tools?" — solved by telling the agent in plain stdout text and trusting it to relay.

Idempotent and version-checked, because the agent will re-run

Step one of the flow is a version check that warns if the CLI is outdated. The whole flow is idempotent — running it twice doesn't re-prompt for company info, doesn't clobber the MCP config, doesn't reset auth.

The agent can run it any time it suspects something is off. This matters because the agent often will re-run setup defensively — it's the cheapest debug step. A non-idempotent setup script punishes that instinct and trains the agent to avoid re-running, which is the opposite of what you want.

The pattern: every "a human is reading this" assumption gets replaced

Six shifts. One pattern across all of them: every assumption that "a human is reading this" gets replaced with "an agent is running this."

Single command, not a page.
Tools shipped with their own playbook.
A scratch folder with a README the agent reads on start.
Business context as a queryable key, not a settings tab.
Restart instructions in stdout, not a banner notification.
Idempotent, because the agent will retry.

None of these are AI features. They're surface-area changes. But the difference between an agent that gets your product in 30 seconds and one that gives up after burning $0.40 in tokens is exactly the gap between these six and a traditional signup wizard.

The user still has a job, just a smaller one

To be clear: the user is not gone. The user still logs in when the browser pops, and the user still describes their business in plain English the first time the knowledge probe fires.

That's the whole human surface area. Everything else — installing the CLI, wiring the MCP server into the right config file for the detected editor, scaffolding the workspace folder, writing the business profile into the knowledge graph, telling the user to restart — is the agent's job, because the agent is the one with shell access and a context window. The flow's job is to make it easy for the agent to do all of that without inventing anything.

Try it

Open Claude Code, Codex, or Cursor. Tell your agent:

Run npx @agentled/cli setup and then build me a workflow that scores
my last 50 inbound leads against our ICP.

That's the whole onboarding. The agent installs, authenticates, wires up MCP, learns its playbook, writes your company profile into the workspace knowledge graph, asks you for one test input, dry-runs the workflow, shows you the result, and iterates until the output is what you wanted. You log in once and describe the job. That's it.

The patterns described above — single command, tools-plus-playbook, scaffolded folder, knowledge probe, agent-relayed restart, idempotent re-run — are open conventions, not platform lock-in. The version we ship at AgentLed is one implementation. The point is the shape: when your user is an agent, your onboarding stops being a webpage and becomes a function the agent can call.

The shape we landed on lives in PR #37 if you want to read the change set, and the broader best-practices repo at github.com/Agentled/agentic-ops collects the patterns the skill installs alongside the tools.