@vatio-ai/skills 0.0.0-stage → 1.3.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,11 @@
+{
+  "name": "vatio",
+  "owner": { "name": "Vatio", "url": "https://vatio.ai" },
+  "plugins": [
+    {
+      "name": "vatio",
+      "source": "./",
+      "description": "Build a Vatio agent from your coding agent, then fix what supervisors flag and prove it with evals."
+    }
+  ]
+}

package/.claude-plugin/plugin.json

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

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Urcalab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,52 @@
-# Temporary Holding Version
+# Vatio skills
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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 |
+
+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
+`vatio docs` or `vatio flags`, so they are never out of date.
+
+## Install
+
+Any coding agent, from the root of your project:
+
+```
+npx @vatio-ai/skills
+```
+
+It copies both skills into `.agents/skills/` (Codex, Cursor, Gemini CLI,
+GitHub Copilot, OpenCode and others) and `.claude/skills/` (Claude Code). Run
+it again to update them.
+
+Or in Claude Code, as a plugin:
+
+```
+/plugin marketplace add vatio-ai/skills
+/plugin install vatio@vatio
+```
+
+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.
+
+`vatio init` also writes a pointer to `vatio flags` into the workspace's
+`AGENTS.md`, which most coding agents read without installing anything.
+
+## Docs
+
+[Improve your agent from flags](https://vatio.ai/docs/improve) ·
+[CLI](https://vatio.ai/docs/cli/) · [Changelog](https://vatio.ai/docs/changelog)
+
+## Issues
+
+Bugs and ideas go to [issues](https://github.com/vatio-ai/skills/issues).
+This repository is a read-only mirror of the skills as they ship inside
+Vatio, so a pull request cannot be merged here: open an issue describing the
+change instead.
+
+MIT licensed.

package/bin/install.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+// npx @vatio-ai/skills -- copies the Vatio skills into the project the command
+// runs in, for every coding agent at once:
+//   .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 { 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.`;
+
+const args = process.argv.slice(2);
+let root = process.cwd();
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if (arg === "-h" || arg === "--help") {
+    console.log(usage);
+    process.exit(0);
+  } else if (arg === "--dir" && args[i + 1]) {
+    root = args[++i];
+  } else {
+    console.error(`Unknown argument: ${arg}\n\n${usage}`);
+    process.exit(1);
+  }
+}
+
+if (!existsSync(root)) {
+  console.error(`No such directory: ${root}`);
+  process.exit(1);
+}
+
+const source = join(dirname(fileURLToPath(import.meta.url)), "..", "skills");
+const skills = readdirSync(source, { withFileTypes: true })
+  .filter((entry) => entry.isDirectory())
+  .map((entry) => entry.name);
+
+for (const target of [".agents/skills", ".claude/skills"]) {
+  for (const skill of skills) {
+    const dest = join(root, target, skill);
+    cpSync(join(source, skill), dest, { recursive: true, force: true });
+    console.log(`  ${relative(process.cwd(), join(dest, "SKILL.md")) || dest}`);
+  }
+}
+
+console.log(`
+Ask your coding agent to build or improve a Vatio agent and it will use them.
+Docs: https://vatio.ai/docs/integrations/claude-code`);

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@vatio-ai/skills",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.3.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",
+    "agent-skills",
+    "skills",
+    "claude-code",
+    "codex",
+    "cursor",
+    "ai-agent"
+  ],
+  "homepage": "https://vatio.ai/docs/integrations/claude-code",
+  "bugs": "https://github.com/vatio-ai/skills/issues",
+  "license": "MIT",
+  "author": "Vatio",
+  "type": "module",
+  "bin": {
+    "vatio-skills": "bin/install.mjs"
+  },
+  "files": [
+    "bin/install.mjs",
+    "skills/",
+    ".claude-plugin/",
+    "README.md",
+    "LICENSE.txt"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vatio-ai/skills"
+  }
+}

package/skills/vatio-improve/SKILL.md

@@ -0,0 +1,46 @@
+---
+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.
+---
+
+# Improve a Vatio agent from its flags
+
+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:
+
+```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
+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.
+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 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.
+5. If the digest, an error or the docs left you guessing, say so:
+   `vatio feedback "what you were doing and what was missing"`.
+
+`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
+`npx @vatio-ai/cli` in its place; if it says to log in, run `vatio login`: it
+opens the browser on the developer's machine (if it doesn't, give them the
+link it prints), and they sign in and check the code matches. If it times
+out, run it again after they have signed in.

package/skills/vatio-new/SKILL.md

@@ -0,0 +1,41 @@
+---
+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.