Onboarding a new person¶
Quick start ends with a reachable cockpit and a person who has
never used one. From there the agent runs the walk-through itself, in its own chat, out of the
shipped onboarding skill. The skill file is the authority; this page is the map.
| Shipped at | /usr/share/agentctl/skills/onboarding/SKILL.md |
| Overlay override | /opt/agentctl/skills/onboarding/ — resolved before the shipped payload |
| Symlinked into | ~/.claude/skills/ (claude) · ~/.pi/agent/skills/ (pi) |
| Activation | in the per-agent default skill set |
| Written for | people who do not write code |
Activating it on an agent that does not have it¶
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.
Three ways it starts¶
| trigger | shape |
|---|---|
/onboarding |
the cockpit's chat tab exposes every activated skill as a slash command |
| description match | a first session, "what can you do", "where do I start", "give me a tour", "can you train me" |
| stale-user signal | a user who only asks for summaries, never delegates, or accepts every first draft |
Before it runs a stage¶
- Look for a previous run —
zk list --match "onboarding progress"or~/workspace/onboarding/progress.md. Done stages are not repeated. - Run stage 0 if no profile exists; read the profile if one does.
- Ask how far the user wants to go now, and respect the answer.
The stages¶
One stage per turn, then stop. Each asks for the user's real example first and ends with something that exists after the conversation closes.
| stage | what the user does | term taught |
|---|---|---|
| 0 — intake | voice dump (default) or typed rounds: role, cadences, tools, one process end to end, data sensitivity, preferences, pasted writing samples | — |
| 1 — the interface | types / and reads the skill list; is shown the message box, file panel, microphone, session bar, apps button |
— |
| 2 — delegate, don't ask | delegates one real thing end to end, corrects the result, restates the difference | — |
| 3 — the workspace | creates the folder and the what-this-is note for their key process | — |
| 4 — turn a repeat into a skill | builds a skill for the thing they most dislike, runs it from /, changes one line, runs it again |
skill |
| 5 — put it on a schedule | schedules the stage-4 skill, then asks what is scheduled | — |
| 6 — mini-apps | opens a shipped app, then describes a panel over the two systems they cross-check by hand | mini-app |
| 6.5 — connecting a system | logs into their own account live, or files a shared system as a connector request | connector |
| 7 — several strands at once | routes three real pieces of last week's work across conversation / own session / schedule | session |
| 8 — make the work verifiable | asks the agent to justify one number, then adds a "done and correct" check to their stage-4 skill | — |
| 9 — memory | asks "what do you know about me?", corrects it, watches the correction take effect | memory |
| 10 — the loop | names one friction, then routes the most annoying manual step left in their week | — |
Stages are cuttable for time. Three habits are not: route (stage 7), verify (stage 8), escalate gaps into requests (stage 10).
Where stage 0's answers land¶
Written at the end of stage 0, under the rubric in
/usr/share/agentctl/docs/steering-model.md — the split the housekeeper enforces.
| surface | content |
|---|---|
CLAUDE.md |
invariants only: owner, conversation and output language, register, the ask-versus-act line, what must never be sent or changed |
| memory | tools and source of truth, the two hand-checked systems, cadences, their definition of "done and correct", writing voice |
~/workspace/onboarding/profile.md |
the process walk-through, pasted writing samples, data locations, systems inventory |
Resuming¶
Resumption lives on disk: ~/workspace/onboarding/progress.md (stages done, terms already
taught, what is next) plus profile.md. Nothing lives in session state. /onboarding picks
up where it stopped.
When the user is not new¶
| profile | stages run |
|---|---|
| months in, only ever asks for summaries | 2, 4, 8 |
| delegates well, keeps hitting one system | 6.5 only |
| delegates, has skills, treats every output as final | 8, 10 |
Full detail¶
/usr/share/agentctl/skills/onboarding/SKILL.md carries the intake script, the per-stage
wording, the missing-connector rule and the closing sequence.