@vatio-ai/skills 1.4.0 → 1.6.0

package/.claude-plugin/marketplace.json

@@ -5,7 +5,7 @@
     {
       "name": "vatio",
       "source": "./",
-      "description": "Build a Vatio agent from your coding agent, then fix what supervisors flag and prove it with evals."
+      "description": "Build a Vatio agent from your coding agent, then fix what supervisors report and prove it with evals."
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "vatio",
-  "description": "Build a Vatio agent from your coding agent, then fix what supervisors flag and prove it with evals.",
-  "version": "1.4.0",
+  "description": "Build a Vatio agent from your coding agent, then fix what supervisors report and prove it with evals.",
+  "version": "1.6.0",
   "author": { "name": "Vatio", "url": "https://vatio.ai" },
   "homepage": "https://vatio.ai/docs",
   "repository": "https://github.com/vatio-ai/skills",

package/README.md

@@ -4,8 +4,9 @@ Skills for the coding agent working on your [Vatio](https://vatio.ai) agent.
 
 | Skill | What it does |
 |---|---|
-| `vatio-new` | Builds a customer-facing agent from scratch: asks the owner what it needs to know, writes `vatio.yml`, pushes it and hands over a link to try |
-| `vatio-improve` | Works through the replies your supervisors flagged in the inbox: reads `vatio flags`, fixes each cause on a branch, proves it with `vatio eval`, and opens a pull request |
+| `vatio-init` | The first one in a project: looks at what is already there (a `vatio.yml` anywhere in the repository, the app's code) and recommends from it. With no agent yet, builds one: asks the owner what the code does not answer, writes `vatio.yml`, pushes it and hands over a link to try. With one, gets a developer who joined the project up to speed |
+| `vatio-improve` | Takes every reply your supervisors reported in the inbox in one session: reads `vatio flags`, fixes each cause, `vatio push`, proves it with `vatio eval` (in the background in Claude Code) and publishes with `vatio publish` |
+| `vatio-share-session` | Sends the Claude Code session to the Vatio team when you ask it to, or offers to when the other two finish (send it, not now, or don't ask again), after showing you what goes (images left out, anything that looks like a secret redacted), with your feedback if you want to add some |
 
 The skills are short on purpose. They tell your coding agent when to reach for
 the Vatio CLI; the instructions themselves come from the platform when it runs
@@ -19,7 +20,7 @@ Any coding agent, from the root of your project:
 npx @vatio-ai/skills
 ```
 
-It copies both skills into `.agents/skills/` (Codex, Cursor, Gemini CLI,
+It copies the skills into `.agents/skills/` (Codex, Cursor, Gemini CLI,
 GitHub Copilot, OpenCode and others) and `.claude/skills/` (Claude Code). Run
 it again to update them.
 
@@ -38,8 +39,9 @@ Or in Claude Code, as a plugin:
 ```
 
 Your agent then uses them on its own when you ask it to build, improve or fix
-a Vatio agent, or you can call them by name: `/vatio-new` and `/vatio-improve`,
-or `/vatio:vatio-new` and `/vatio:vatio-improve` from the plugin.
+a Vatio agent, or to send the session to Vatio, or you can call them by name:
+`/vatio-init`, `/vatio-improve` and `/vatio-share-session`, or
+`/vatio:vatio-init` and so on from the plugin.
 
 `vatio init` also writes a pointer to `vatio flags` into the workspace's
 `AGENTS.md`, which most coding agents read without installing anything.

package/bin/install.mjs

@@ -4,14 +4,15 @@
 //   .agents/skills/   Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, Cline, Amp
 //   .claude/skills/   Claude Code, which does not read .agents/
 // Running it again overwrites the copies with this version's.
-import { cpSync, existsSync, readdirSync } from "node:fs";
+import { cpSync, existsSync, readFileSync, readdirSync, rmSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const usage = `usage: npx @vatio-ai/skills [--dir PATH]
 
-Copies the Vatio skills (vatio-new, vatio-improve) into PATH/.agents/skills and
-PATH/.claude/skills. PATH defaults to the current directory.`;
+Copies the Vatio skills (vatio-init, vatio-improve, vatio-share-session) into
+PATH/.agents/skills and PATH/.claude/skills. PATH defaults to the current
+directory.`;
 
 const args = process.argv.slice(2);
 let root = process.cwd();
@@ -34,6 +35,9 @@ if (!existsSync(root)) {
 }
 
 const source = join(dirname(fileURLToPath(import.meta.url)), "..", "skills");
+// Skills this package used to ship under another name. Left in place, the old
+// copy would answer the same requests as the new one.
+const RENAMED = { "vatio-new": "vatio-init" };
 const skills = readdirSync(source, { withFileTypes: true })
   .filter((entry) => entry.isDirectory())
   .map((entry) => entry.name);
@@ -44,6 +48,20 @@ for (const target of [".agents/skills", ".claude/skills"]) {
     cpSync(join(source, skill), dest, { recursive: true, force: true });
     console.log(`  ${relative(process.cwd(), join(dest, "SKILL.md")) || dest}`);
   }
+  for (const [old, current] of Object.entries(RENAMED)) {
+    const dest = join(root, target, old);
+    if (!installedByUs(dest, old)) continue;
+    rmSync(dest, { recursive: true, force: true });
+    console.log(`  removed ${relative(process.cwd(), dest) || dest} (now ${current})`);
+  }
+}
+
+function installedByUs(dir, name) {
+  try {
+    return readFileSync(join(dir, "SKILL.md"), "utf8").includes(`\nname: ${name}\n`);
+  } catch {
+    return false;
+  }
 }
 
 console.log(`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vatio-ai/skills",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Agent skills for building and improving a Vatio agent from your coding agent: Claude Code, Codex, Cursor, Gemini CLI, Copilot and any agent that reads SKILL.md",
   "keywords": [
     "vatio",

package/skills/vatio-improve/SKILL.md

@@ -1,46 +1,49 @@
 ---
 name: vatio-improve
-description: Improve a Vatio agent from what its supervisors flagged. Use when asked to improve, fix or debug a Vatio agent, to work through flagged replies or wrong answers in production, or when a GitHub issue labelled vatio-flags arrives. Works in any directory with a vatio.yml.
+description: Improve a Vatio agent from what its supervisors reported. Use when asked to improve, fix or debug a Vatio agent, to work through reported or flagged replies or wrong answers in production, or when the daily Vatio email says there are open reports. Works in any directory with a vatio.yml.
 ---
 
-# Improve a Vatio agent from its flags
+# Improve a Vatio agent from its reports
 
-Supervisors flag wrong replies in the Vatio inbox and write what should have
-happened: a different answer, an action, or a tool the agent should have used
-or does not have. Vatio keeps the instructions for working them on the
-platform, so they are never out of date here. Start by reading them:
+Supervisors report wrong replies in the Vatio inbox and write what it should
+have said: a different answer, an action, or a tool the agent should have
+used or does not have. One session takes every open report. Vatio keeps the
+instructions for working them on the platform, so they are never out of date
+here. Start by reading them:
 
 ```bash
 vatio flags
 ```
 
 Run it from the directory with the workspace's `vatio.yml` (or below it). It
-prints every open flag — the conversation, each tool call with what the
+prints every open report — the conversation, each tool call with what the
 backend answered, and the supervisor's note — with how to work them at the
 top. Follow those instructions; they take precedence over anything below.
 
 In short:
 
-1. Group the flags by cause, and fix each cause where it lives: `vatio.yml`,
-   a knowledge entry, a tool, or the backend a tool calls. `vatio tools --env
-   live` shows each tool's error rate, timeouts and latency across every
-   conversation, and the calls that failed with what the backend answered: a
-   failing tool rarely gets flagged, because the agent apologizes and moves
+1. Group the reports by cause, and fix each cause where it lives:
+   `vatio.yml`, a knowledge entry, a tool, or the developer's backend a tool
+   calls. `vatio tools --env live` shows each tool's error rate, timeouts and
+   latency, and the calls that failed with what the backend answered: a
+   failing tool rarely gets reported, because the agent apologizes and moves
    on. Fix those too.
-2. Work on a git branch. `vatio push` deploys it to the branch's own
-   environment, never to live.
-3. Prove it with `vatio eval`: every flag made on live, or before the first publish, is an eval case, replayed against
-   the branch and judged. The report counts the open flags apart from the
-   regression cases. A fix is done when its flags pass and nothing that
-   passed on live now fails.
-4. Open a pull request with what you changed and the eval result. Name flags
-   by id (`F-7K2QX`), and report the open flags and the
-   regression cases as two counts, never one total. With no GitHub
-   repository connected, `vatio propose --env <branch> --title "…"
-   --summary-file why.md` instead: the workspace's owner accepts it from the
-   inbox, which publishes it. Never `vatio publish` it yourself.
+2. `vatio push`. It updates preview and runs no tests. No branch or
+   environment to set up: preview is the one.
+3. `vatio eval` tests every report against preview. It can take several
+   minutes, so in Claude Code start it with the Bash tool's
+   `run_in_background` and read its report when it finishes. Iterate (fix,
+   push, eval) until the reports pass and nothing that passes on live fails.
+   Name reports by id (`F-7K2QX`).
+4. Show the developer what passes now, and `vatio publish` once they agree:
+   it changes what visitors get. If it is refused, follow its message: it
+   says what to run. Never pass `--force` unless the developer explicitly
+   asks for it.
 5. If the digest, an error or the docs left you guessing, say so:
    `vatio feedback "what you were doing and what was missing"`.
+6. 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.
 
 `vatio docs` prints the whole contract (manifest, tools, knowledge, CLI) if
 the fix needs more than the digest says. If `vatio` is not installed, use

package/skills/vatio-init/SKILL.md

@@ -0,0 +1,80 @@
+---
+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 (for WhatsApp, Instagram, a website widget or an app) and gets it to the console's Test screen, 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.
+
+## 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).
+  3. `vatio diff`, `vatio push`, then try it with `vatio chat`, including a
+     conversation that should hand off.
+  4. Give them the link `vatio push` prints after `Try it:` (the console's
+     Test screen, with web chat, WhatsApp and Instagram) with what you
+     tried. 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;
+  - open reports in `vatio flags`: 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 console.
+- **A workspace slug but no `vatio.yml`.** Ask for the repository it lives
+  in: Vatio keeps what was deployed, not the files it came from. Do not
+  `vatio init` one instead.
+
+## 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.
+
+`vatio` is `npx @vatio-ai/cli` when it is not installed globally. 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.

package/skills/vatio-share-session/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: vatio-share-session
+description: Send this coding session to the Vatio team, so they can see where building or improving a Vatio agent got stuck. Use when the user asks to share, send or report this session (or "the conversation", "what we did") to Vatio, when the Vatio team asked them for it, when Vatio itself got in the way and they want the team to see exactly how, or when vatio-init or vatio-improve finish and say to offer it.
+---
+
+# Send this session to the Vatio team
+
+`vatio share-session` sends the Claude Code session you are running in: what
+the user asked, what you read and ran, and what came back. It leaves out
+images, replaces anything that looks like a key, token or password with
+`[REDACTED]`, and the home directory with `~`. Only the Vatio team reads it,
+to see where Vatio got in the way and fix it.
+
+It is sent in one of two ways: the user asked for it, or you offer it because
+`vatio-init` or `vatio-improve` just finished.
+
+1. **Only when you are offering it**, ask the CLI first:
+
+   ```bash
+   npx @vatio-ai/cli@latest share-session --should-ask
+   ```
+
+   If it prints `no`, stop here and do not mention it: the developer said not
+   to ask again, or was asked recently. If it prints `yes`, go on.
+
+2. Show the user what would go, without sending anything:
+
+   ```bash
+   npx @vatio-ai/cli@latest share-session --save /tmp/vatio-session.jsonl
+   ```
+
+   Tell them which session it is (the summary it prints), that it is the
+   whole conversation, and that the file is there if they want to read it.
+
+3. Ask whether to send it, once. It is their conversation: never send it on
+   your own, even when the task seems to call for it.
+
+   When you are offering it, ask with three answers (in Claude Code, as a
+   multiple-choice question), for example: "Do you want to send this session
+   to the Vatio team, so they can see where Vatio got in the way and improve
+   it?"
+
+   - **Send it**
+   - **Not now**: do nothing more. It will not be offered again for a week.
+   - **Don't ask again**: run
+     `npx @vatio-ai/cli@latest share-session --never`.
+
+   In the same question, suggest they add feedback: what got in the way, what
+   they expected Vatio to do, or anything else they want the team to know.
+   It is optional — the session is what matters, and it goes fine on its own.
+   A no is a fine answer: do not insist.
+
+4. If they say to send it, send it. With their feedback, in their words, as
+   they gave it:
+
+   ```bash
+   npx @vatio-ai/cli@latest share-session --yes "their feedback"
+   ```
+
+   Without it, just the session:
+
+   ```bash
+   npx @vatio-ai/cli@latest share-session --yes
+   ```
+
+   Never write feedback for them: a summary of the session in your words adds
+   nothing the session does not already say.
+
+   The first time it may ask to sign in: it opens the browser (if it doesn't,
+   give them the link it prints). Tell them it was sent and the number it
+   printed.
+
+Only Claude Code sessions can be sent. In any other coding agent, do not offer
+it; when the user asks, write what happened instead:
+`npx @vatio-ai/cli@latest feedback "…"`.

package/skills/vatio-new/SKILL.md

@@ -1,41 +0,0 @@
----
-name: vatio-new
-description: Build someone a customer-facing AI agent on Vatio and get it to the console's Test screen, where they can try it — for WhatsApp, Instagram, a website widget or an app. Use when asked to create, set up, start or ship a Vatio agent, a chatbot or a support/sales assistant on Vatio, or when the user pastes the prompt from vatio.ai.
----
-
-# Start a Vatio agent
-
-Vatio keeps the contract and the procedure on the platform, so they are never
-out of date here. Read them first:
-
-```bash
-npx @vatio-ai/cli docs
-```
-
-The section **For coding agents → Starting a new agent** is the procedure;
-follow it, it takes precedence over the summary below. The rest of that
-output is the contract for `vatio.yml`, tools, knowledge and the CLI.
-
-In short:
-
-1. If a `vatio.yml` exists at or above the current directory, work in that
-   workspace and keep its slug.
-2. Before writing anything, ask the owner briefly: what the business does,
-   what the agent must never say, when it must hand off to a person, and which
-   of their systems it should read from. Do not invent business facts.
-3. `vatio init SLUG` in the repository the agent belongs in, then write
-   `vatio.yml` (and `tools/` for their APIs).
-4. `vatio diff`, `vatio push`, then try it with `vatio chat` —
-   including a conversation that should hand off.
-5. Give them the link `vatio push` prints after `Try it:` — the console's
-   Test screen, with web chat, WhatsApp and Instagram — with what you tried.
-   Publish with `vatio publish` only when they ask.
-6. If an error or the docs left you guessing, say so before you finish:
-   `vatio feedback "what you were doing and what was missing"`.
-
-`vatio` is `npx @vatio-ai/cli` when it is not installed globally. The first
-`vatio push` 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.