---
name: vatio-init
description: The first Vatio skill in a project. Looks at what is already there — a vatio.yml anywhere in the repository, the workspace on the platform, the app's own code — and recommends from it, then either builds a customer-facing AI agent (in the app first, through its web widget or mobile SDK, and on WhatsApp or Instagram when asked) and gets it to Try the agent in the Vatio inbox, or gets a developer who joined a project that already has one up to speed. Use when asked to create, set up, start or ship a Vatio agent, a chatbot or a support/sales assistant on Vatio, to get started on or onboard onto a project that uses Vatio, or when the user pastes the prompt from vatio.ai.
---

# Start with Vatio in this project

Look before you create: the project may already have an agent. Vatio keeps
the contract and the procedures on the platform, so they are never out of
date here. Read them first:

```bash
npx @vatio-ai/cli docs
```

Under **For coding agents**, **Starting a new agent** and **Joining an
existing workspace** are the two procedures. Follow the one that fits; it
takes precedence over the summary below. The rest of that output is the
contract for `vatio.yml`, tools, knowledge and the CLI. To look something up
again later, `npx @vatio-ai/cli docs search TERM` prints the sections that
mention it, with their page, and `npx @vatio-ai/cli docs PAGE` one page
(`tools`, `knowledge`, `cli/deploy`), rather than reading it all twice.

## 1. Look at what is there

- **An agent.** Every `vatio.yml`, at or above the current directory and
  anywhere in the repository (`git ls-files '*vatio.yml'`). Its
  `workspace:` line names the workspace.
- **The app.** What the project does and for whom; the API an agent could
  call (routes, controllers, an OpenAPI file); how its users sign in; and the
  docs, FAQs or policies an agent could read as knowledge.
- **This machine.** `vatio doctor`: whether it is signed in, and which
  workspace this directory resolves to.

## 2. Say what you found, and recommend

Before changing anything, tell the user in a few lines what is there and what
you recommend, and ask them to confirm.

- **No `vatio.yml`: a new agent.** Propose what it could do from what you
  read: what it answers, which endpoints become tools, what becomes
  knowledge. Then follow **Starting a new agent**, in short:
  1. Ask the owner only what the code does not answer: what the business
     does, what the agent must never say, when it hands off to a person,
     which of their systems it should read from. Do not invent business
     facts.
  2. `vatio init SLUG` in the repository the agent belongs in, then write
     `vatio.yml` (and `tools/` for their APIs, with one that alerts their
     team when a person should take over: **Human in the loop** in the docs).
  3. `vatio diff`, `vatio push`, then try it with `vatio chat`, including a
     conversation that should hand off. A tool that needs the visitor's
     phone or a team role runs with `vatio chat --as-phone me` (or a
     customer phone); an `access: private` one with `--as-subject ID`. When visitors
     will send files (a PDF, a photo), send one with `vatio chat --file PATH
     "question"`: it says how much of a PDF the agent got.
  4. **Write down what it should do as tests.** For each question that
     matters, `vatio test add "what a visitor would ask" "what the answer has
     to do"`: it asks it on preview and says whether it passes now (add
     `--as-phone` or `--as-subject` as in `vatio chat`). Three or four is
     enough to start. This is
     the only thing that makes a later version's mistake visible: `vatio
     test` replays them on every push, and once the workspace is published
     `vatio publish` refuses a version that breaks one. A workspace with no
     tests publishes with nothing checked, which is how a fix for one
     question quietly breaks another.
  5. Give them the link `vatio push` prints after `Try it:` (the inbox
     with Try the agent open: web chat, WhatsApp and Instagram) with what you
     tried. Until someone outside their team talks to the agent the
     workspace is a draft: `vatio push` is the deploy, so there is nothing to
     publish yet and you need not explain preview and live. Every push says
     which of the two states the workspace is in; once it says visitors still
     get an older version, publish with `vatio publish` only when they ask.
- **A `vatio.yml`: the agent exists.** Never `vatio init` here: it writes a
  starter agent, and pushing that replaces the real one. Work from the
  directory of the `vatio.yml` and follow **Joining an existing workspace**:
  sign in with the address they were invited with, then
  `vatio diff --env live` and `vatio status`. Explain the agent from
  `vatio.yml` (what it is for, its tools, its knowledge, when it hands off)
  and recommend from what you see:
  - the folder differs from live: say so first, the repository may be behind;
  - `vatio status` lists changes made outside the files (from the Vatio MCP
    in Claude or ChatGPT): `vatio pull` writes them into `vatio.yml` and
    `tools/` before anything is pushed;
  - open reports in `vatio test list`: work them with the `vatio-improve` skill;
  - tool calls failing in `vatio tools`: the fix is in the backend they call;
  - `workspace_forbidden`: they are not in the workspace yet, and the owner
    invites them from **Team** in the inbox.
- **A workspace slug but no `vatio.yml`.** Ask for the repository it lives
  in. If it was built from the Vatio MCP in Claude or ChatGPT, it has none
  yet: `vatio init SLUG` in the repository it should live in, then, before
  any push, `vatio pull --force` to replace the starter agent with the one
  Vatio runs. Otherwise do not `vatio init` one instead.

## Claude Code permissions

In Claude Code, once the agent is pushed, check the project's
`.claude/settings.json` (in the folder Claude Code was opened in). If it has
no `Bash(vatio *)` rule, offer once to add the block in **Auto mode** on the
docs' Claude Code page: it lets you run `vatio` without the auto mode
classifier refusing it, and still asks the developer before `vatio publish`,
`vatio rollback`, `vatio secrets` and `vatio keys`. Add it only with their
yes, merged into what the file has, never replacing it, and add no other rule.
It matches `vatio`, so it needs the CLI installed:
`npm install -g @vatio-ai/cli`, also only with their yes. Run each `vatio`
command on its own, not in a pipe or after `cd … &&`, so the rule matches.
Never edit `~/.claude/settings.json`; for `vatio share-session` point them to
that same section.

## 3. Before you finish

1. If an error or the docs left you guessing, say so:
   `vatio feedback "what you were doing and what was missing"`.
2. Last, in Claude Code, offer to send this session to the Vatio team, as
   the `vatio-share-session` skill says. It starts with
   `vatio share-session --should-ask`: if that prints `no`, say nothing.

There are two ways to run the CLI, and the package name appears once in
either: `vatio ARGS` when it is installed globally, and
`npx @vatio-ai/cli@latest ARGS` when it is not. Pick one per command and
leave it whole — `npx @vatio-ai/cli @vatio-ai/cli push` is the commonest way
to get this wrong, and the CLI reads the second name as the command and
fails. The first
`vatio push` (or `vatio login`) signs the developer in: it opens the browser
on their machine (if it doesn't, give them the link it prints). Tell them to
sign in with email, Google or GitHub and check that the code on the page
matches the one the terminal printed. If the command times out waiting, run
it again after they have signed in: it picks up the same sign-in page.

A command you hand the developer to run themselves, because a permission
check refused it or it needs their own credentials, says
`npx @vatio-ai/cli@latest`, never `vatio`: the `vatio` installed on their
machine can be too old for Vatio to accept. When one command's output feeds
another (a key into a secrets store), take it with `--json` and chain with
`&&`, never through `grep`, so a failure stops there instead of passing on an
empty value. If Claude Code's auto mode refused a `vatio` command and the
project's `.claude/settings.json` has no `Bash(vatio *)` rule, also mention
**Auto mode** on the docs' Claude Code page.

A **secret** is not one of those commands, as long as you do not read it.
`vatio secrets set KEY --from-env` takes the value from their shell or the
`.env` beside the `vatio.yml` and sends it without printing it, so run that
yourself rather than stopping to ask. Ask them only for a value that is not
there yet, and never echo one back, put one in a file you write, or read a
`.env` to quote it.