Onboarding a new person

Quick start ends with a reachable cockpit and a person who has never used one. This page covers what happens next, which is not an operator procedure: the agent runs the walk-through itself, out of a shipped skill, in its own chat.

The skill is onboarding, shipped in the deb at /usr/share/agentctl/skills/onboarding/SKILL.md and symlinked into the agent's ~/.claude/skills/ (~/.pi/agent/skills/ on pi). This page describes what that file makes the agent do. The file is the authority; if the two disagree, read the file.

It is on by default

onboarding is in the per-agent default skill set, so a freshly provisioned agent has it without anyone asking. That is deliberate: the skill's value is highest on an agent nobody has configured yet, and opt-in reached only the owners who already knew it existed.

For an agent provisioned before it was defaulted, or one whose skill list was trimmed:

sudo agentctl agents skills add onboarding <agent>   # or * for the whole fleet
agentctl skills <agent>                              # confirm the symlink landed

skills add wires the symlink and records the activation in the same call — no apply needed. It resolves the repo overlay before the shipped payload, so a host that wants a different walk-through puts its own skills/onboarding/ in /opt/agentctl and the symlink follows it there instead of into /usr/share.

Three ways it starts

• The user types /onboarding. The cockpit's chat tab exposes every activated skill as a slash command, so this is the discoverable route and the one the skill tells them about when it finishes.
• The agent recognises the situation. A skill's name and description sit in context on every turn, and this one's description names the openings: a first session, "what can you do", "where do I start", "give me a tour", "I don't know what to ask for", "can you train me". No operator action, no slash command.
• The agent notices a stale user. The skill's own trigger list includes a user who has only ever asked for summaries and never delegated anything — see When the user is not new.

Before it runs anything

Three checks, in order, and the first is the resumability one:

1. Look for a previous run — zk list --match "onboarding progress", or ~/workspace/onboarding/progress.md directly. A session starts with no memory of prior conversations, so this note is the only continuity. If it says stages 1–4 are done, the agent says so and picks up at 5. If a stage-0 profile already exists, it is read, not re-collected.
2. Run the intake (stage 0) if it has not been run.
3. Ask how far they want to go now, and respect the answer.

The progress note is created at the start and updated at the end of every stage. It holds stages done, which real terms have already been taught (so none is explained twice), and what to pick up next.

Stage 0 — the intake

The skill calls this the highest-value stage in it, and forbids both skipping it and compressing it into one question. Everything after it is better or worse depending on how well it went.

The default route is a voice dump: the user presses the microphone and talks for two or three minutes about their role, their week, their systems, what they wish they did not do by hand, and how they want to be communicated with. The agent transcribes it, mirrors back a structured summary, then runs one short round on only the gaps and names them as gaps. Someone who would rather type gets a question route instead — never both.

Either route is run in rounds, not as a script. A round is everything usefully askable given what is already known; the next round is whatever that unlocked; it ends when a round would produce nothing new. Vague answers get pushed on. A user who is unsure how their own process is decided is treated as information, not as a gap — it usually means the process is worth watching once, live.

The coverage target across rounds:

role and accountability	what actually lands on them, who depends on their output
recurring work by cadence	daily/weekly/monthly/quarterly, plus what eats the most time and what they most dislike — the second predicts the best first automation better than the first
tools	which systems they live in, which is the source of truth, and which two they cross-check by hand — that answer is likely both their first mini-app and their first missing connector
one process end to end	input, steps, approver, output format, destination, deadline, what usually goes wrong, and what "done and correct" means
data and sensitivity	where the real files are, naming conventions, what is confidential or regulated, what must never be sent or changed without approval
how to work with them	conversation language and output language (often different), register, length, the ask-versus-act line, whether to show the working
their writing voice	two or three things they actually wrote — pasted, not described, because people describe their own style badly and then reject drafts that match the description

Where the answers go

Written immediately at the end of stage 0, not at the end of the walk-through, so a dropped session does not lose them. The split is the rubric in /usr/share/agentctl/docs/steering-model.md — the same one the housekeeper enforces:

• CLAUDE.md — loaded in full every turn, so only invariants: who the owner is, conversation and output language, register and length, the ask-versus-act line, and the hard rules about what must never be sent, changed or leave a given system. A handful of lines. Past that it belongs in memory.
• Memory — the learned context needed only sometimes, one fact per file with a findable description: tools and which is the source of truth, the two hand-checked systems, cadences, their definition of "done and correct", writing-voice notes.
• ~/workspace/onboarding/profile.md — the bulk that should not sit in context: the full process walk-through, the pasted writing samples, data locations, the systems inventory.

The agent then tells them plainly that this was written down, that it survives the conversation, and that any of it can be changed — someone who knows a profile is editable corrects it instead of working around it. Preferences apply from the next message, not from the next session.

The intake closes by asking which process they want help with first, and mapping their answer onto the stages ahead. If they have no answer, the two candidates the intake already produced are offered: the thing they most dislike doing, and the two systems they cross-check by hand.

The stages

One stage per turn, then stop and wait. Every stage asks for the user's real example before demonstrating anything, and ends with something that exists after the conversation closes.

	what the user does	word taught
1 — the interface	types / and reads the skill list out loud; is shown the message box, the file panel, the microphone, the session bar and the apps button	—
2 — delegate, don't ask	delegates one real thing end to end, and says back in their own words how that differs from asking for a summary	—
3 — the workspace	creates the folder and the what-this-is note for their key process, in their team's naming convention	—
4 — turn a repeat into a skill	builds a skill for the thing they most dislike doing, then watches it run from /	skill
5 — put it on a schedule	schedules the stage-4 skill and confirms in plain words what will happen and when	—
6 — mini-apps	opens a shipped app, then describes the panel over the two systems they cross-check by hand	mini-app
6.5 — connecting a system	logs into their own account live, or names a shared system as a connector request; then says which of the two kinds it was and why that changes what happens next	connector (and "MCP", once, in passing)
7 — several strands at once	names something wide from their own job, and predicts correctly that work in another session is not in this one	session
8 — make the work verifiable	asks the agent to justify one specific number or claim from an earlier stage	—
9 — memory	asks "what do you know about me?", corrects it, watches the correction take effect	memory

Stage 1 is followed by a one-paragraph map of the five things the platform does, said once as a signpost. Nothing in it needs remembering; each stage re-establishes its own piece.

Two stages carry an explicit warning against softening them. Stage 4 insists the skill is actually run, because a skill nobody has watched fire is a promise rather than a tool. Stage 8 is not skippable at all: a user who cannot tell good output from confident-looking wrong output will eventually get burned, stop trusting the platform and go back to doing the work by hand. It teaches asking for the source rather than the conclusion, asking what was uncertain, preferring work that flags what it could not match, and asserting the stage-0 definition of "done and correct" on anything recurring.

Why the words are taught at all

The skill's rule is: explain in plain language always, never define a term before the user has felt the thing it names, then give them the real word in one sentence tied to what just happened. One grounded sentence per concept is the whole technique; a glossary lecture is the failure mode it is written against.

The reason it bothers is a routing decision the user has to make on their own, later. A skill and a mini-app live in their own workspace and are built inside a normal conversation with nobody else involved. A connector to their own account — their mail, their calendar, their own Google or Microsoft login — is also self-serve: the agent wires it, sends the authorization link, and proves it with one real read. A connector to a shared or third-party system is not: it needs credentials, access and a decision about what the system may touch, from an administrator, and it can take a while. A user who cannot tell those apart either waits weeks for something that was theirs to build, or asks a colleague for a security change as if it were a five-minute favour.

Session is taught for a narrower reason: diagnosing "it forgot" and "where did that go". Work in another lane genuinely is not in this conversation's context, and a user who has the word asks "check the other session" instead of concluding the platform is unreliable.

A missing connector found mid-task is handled on the spot, on whatever stage it happens — named as a connector, sorted into own-account or shared, written into the profile note as an open request, and then reused as the live example when stage 6.5 arrives.

Resuming

/onboarding picks up where it stopped, and the closing tells the user so, which is what makes an unfinished walk-through something other than a dead end. The mechanism is entirely the progress note at ~/workspace/onboarding/progress.md plus the profile at ~/workspace/onboarding/profile.md: nothing about resumption lives in session state, because none of it would survive.

The closing also tops up all three stage-0 surfaces with what the later stages taught — a preference that only surfaced once they saw real output, a constraint remembered mid-way — under the same split, leaves three concrete next actions named from the user's own work, and leaves one sentence: if something does not do what you want, it is either not built yet (ask for a skill or an app) or a system the agent cannot reach yet (ask for a connector).

When the user is not new

The skill declines to run the full tour on two profiles:

• Months in, but only ever asks for summaries. Stages 2, 4 and 8, and nothing else. The signal is a history of questions with no delegated work, no skills of their own and no schedule.
• Delegates well, keeps hitting one system. Stage 6.5 alone. The signal is a session opening with "why can't you just…" pointed at an outside system.