---
name: onboarding
description: "Set a new Introspection project up from nothing: where the agent's code lives, how the team talks, and which productivity suite it uses, connecting what can be connected as it goes. Use when a project has no runtime yet and someone starts from Quickstart, or a person's own coding agent was pointed at Introspection's agents.md. build-brainstorm follows. Needs `introspection login`."
metadata:
  min-cli-version: "0.73.0"
---

# Onboarding

A new project needs three things before an agent is worth building: a home for the agent's code, a place the team talks to it, and the tools the team works in. Ask about each in turn, connect what the owner chooses, and hand over to build.

Every step reads what already exists first and asks only about what is missing, so running onboarding again picks up where it stopped, and "later" stores nothing: the next run asks again.

## Before you start

- **Make sure the CLI is here and current:** if `introspection --version` isn't found, install it with `npm i -g @introspection-ai/cli`; if it's older than this skill's `min-cli-version`, run `introspection upgrade`. Say in one line what you installed.
- **Make sure you're logged in:** `introspection whoami` exits 0 even when logged out, so read its `logged_in`, then prove the login with `introspection runtimes list --query "length(@)"`. On the platform you're already logged in. If `logged_in` is false or that call says the session is missing or expired, tell the owner in one line that you're opening a sign-in, then run `introspection login` with a bash timeout of 600 seconds: it opens the browser and returns once they've signed in. If no browser opens, give them the link and code it prints. Check again before going on, and stop if it still fails.
- **Say nothing about these checks when they pass,** on the platform above all, where the owner is always signed in: no "I checked your project" or "you're signed in". Speak only to report something you fixed or something missing, in one line, and otherwise open with the first step's question.
- **If the project already has an agent of its own** (`introspection runtimes list --query "length([?kind!='platform'])"` is more than 0), onboarding is done: say so in one line and go to the workflow the owner asked for. Every project has the platform's own runtimes, such as the Operator (`kind: platform`), so they don't count.

## How a step reaches the person

Every choice is a question with the question tool (`ask_user_question`), one decision per call, never a numbered list in your reply. Every connection is something the person does in their browser. Ask for it with `introspection_open` and `wait: true`, on its own in a turn, naming the target, never a link. The result is `Answer: connected`, `Answer: failed: <reason>`, or a decline.

<!-- prettier-ignore-start -->
| Host | The question tool | `introspection_open {target, wait: true}` becomes |
| --- | --- | --- |
| The Operator, hosted or `introspection operator` | `ask_user_question` | The tool itself. |
| Claude Code, Codex, any host without the tool | A question tool you can see in your tool list, if there is one; otherwise one short question with its options in your reply, and wait for the answer | Run the CLI command that waits, then read its exit: `introspection connectors authorize <connector> --subject user` for a connection, `introspection open --runtime <slug> --wait` for a page. An integration (GitHub, Slack): `introspection open --integrations <provider> --wait` when `introspection open --help` lists it, which opens the organization's integrations page on that provider and returns once it's connected (it fails when it isn't); otherwise send them to **Organization settings → Integrations** and ask them to say when they're done. A connector or sign-in has no command: tell the owner where to go in the dashboard and ask them to say when they're done. Then check it. |
<!-- prettier-ignore-end -->

**An answer is what the person did, not proof.** After `connected`, read the real state with the command each step names before saying it works. After a decline, record nothing and move on. After `failed`, say what the provider said in one line and offer to try again or move on.

## Steps

Take them in order, one at a time: a step's question, then its connection, then the next step's question. They aren't independent questions, so never ask them together in one turn: what the owner connects in one step can change the next.

1. `onboarding-repository`: where the agent's code lives.
2. `onboarding-collaboration`: where the team talks to it.
3. `onboarding-productivity`: the productivity suite the team uses (asked only; connecting it isn't available yet).

Tell the owner what you're doing in plain words ("Next, where your team talks"), never a skill's name.

## Done when

- Each step is connected or answered, or the owner said later.
- Say in two or three lines what is connected and what was left for later, then go straight on to build: read `build-brainstorm` and start it in the same turn with its first question, how to start the new agent (from scratch or from a template), with the question tool. Ask what the agent should do only after they choose from scratch. Don't stop to ask whether to continue.