ghosty-acp 0.0.4 → 0.0.6

package/README.md

@@ -180,3 +180,10 @@ flujo JSON-RPC, porque cualquier otra cosa ahí rompe al editor.
 | `cwd … → …` | Se remapeó la ruta del proyecto a una que el agente sí ve |
 
 Necesita Node 22 o superior. MIT.
+
+## Agent skills inside
+
+The package ships the Ghosty Studio agent skills under `skills/` (`ghosty-agent`, `ghosty-acp`,
+`ghosty-docs`, `ghosty-recipe`), in the [Agent Skills](https://agentskills.io) format. Tools that
+load skills from installed dependencies (e.g. TanStack Intent) pick them up; anyone else can
+install them with `npx skills add https://ghosty.studio` or `npx skills add blissito/ghosty-skills`.

package/package.json

@@ -1,13 +1,38 @@
 {
   "name": "ghosty-acp",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Conecta tu editor a un agente ACP remoto. Puente entre entrada/salida estándar y WebSocket, sin dependencias.",
   "type": "module",
-  "bin": { "ghosty-acp": "bridge.mjs" },
-  "files": ["bridge.mjs", "README.md"],
-  "engines": { "node": ">=22" },
-  "keywords": ["acp", "agent-client-protocol", "zed", "vscode", "neovim", "agent"],
+  "bin": {
+    "ghosty-acp": "bridge.mjs"
+  },
+  "files": [
+    "bridge.mjs",
+    "README.md",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "acp",
+    "agent-client-protocol",
+    "zed",
+    "vscode",
+    "neovim",
+    "agent",
+    "agent-skills",
+    "skills",
+    "ghosty"
+  ],
   "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/blissito/ghosty-studio.git", "directory": "packages/acp-bridge" },
-  "homepage": "https://www.ghosty.studio/docs/acp"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/blissito/ghosty-studio.git",
+    "directory": "packages/acp-bridge"
+  },
+  "homepage": "https://www.ghosty.studio/docs/acp",
+  "scripts": {
+    "prepack": "rm -rf skills && cp -R ../../public/skills skills && rm -f skills/*.tar.gz skills/index.json skills/index.legacy.json"
+  }
 }

package/skills/README.md

@@ -0,0 +1,20 @@
+# Ghosty Studio agent skills
+
+Skills in the [Agent Skills](https://agentskills.io) format for coding agents (Claude Code, Cursor,
+Codex, Copilot…). Install one or all:
+
+```bash
+npx skills add blissito/ghosty-skills
+# or straight from the site (same skills, discovered via /.well-known/agent-skills):
+npx skills add https://ghosty.studio
+```
+
+| Skill | What for |
+|---|---|
+| `ghosty-agent` | configure a Ghosty Studio agent through its API: identity, model, files, skills, MCP servers |
+| `ghosty-docs` | read the Ghosty docs from an agent: markdown pages, `llms.txt`, the docs MCP server |
+| `ghosty-acp` | connect Zed, VS Code, JetBrains or Neovim to the agent over ACP |
+| `ghosty-recipe` | write or review an agent recipe (`.recipe.yaml`) to upload in the creator |
+
+This directory is mirrored from `public/skills/` in
+[blissito/ghosty-studio](https://github.com/blissito/ghosty-studio). Docs: https://www.ghosty.studio/docs/configurar

package/skills/ghosty-acp/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: ghosty-acp
+description: Connect a code editor (Zed, VS Code, JetBrains, Neovim) to a Ghosty Studio agent over ACP (Agent Client Protocol) using the ghosty-acp bridge and the agent token. Use when the user wants to talk to their Ghosty agent from their editor, pastes an acp.agents or agent_servers config, or mentions ghosty-acp or ACP with ghosty.studio.
+license: MIT
+compatibility: Node 22+ on the user's machine (npx downloads the bridge); network access to the agent's wss:// address
+metadata:
+  author: ghosty-studio
+  version: "1.0"
+---
+
+# Connect an editor to a Ghosty agent over ACP
+
+A Ghosty Studio agent runs on its own machine behind a WebSocket. Editors launch a
+**command** and speak ACP over stdio, so a bridge swaps the cable: `npx -y ghosty-acp <wss-url>`.
+It has no dependencies and carries no secret; the token travels in an environment variable.
+
+## What you need from the user
+
+Both come from Ghosty Studio → **Agentes → their agent → "Desde tu editor (ACP)"** (a collapsed
+section under the token card):
+
+- the agent's ACP address: `wss://acp-<agentId>.<host>/acp`
+- the token `gat_…` (the same token the `ghosty-agent` skill uses)
+
+Never put the token in `args`: any process on the machine can read another process's
+arguments. It goes in `env.GHOSTY_ACP_TOKEN`.
+
+## Write the config for their editor
+
+**Zed** — `Settings → settings.json`:
+
+```json
+{
+  "agent_servers": {
+    "Ghosty": {
+      "type": "custom",
+      "command": "npx",
+      "args": ["-y", "ghosty-acp", "wss://acp-AGENT.../acp"],
+      "env": { "GHOSTY_ACP_TOKEN": "gat_…" }
+    }
+  }
+}
+```
+
+**VS Code** — install the *ACP Client* extension, then `settings.json`:
+
+```json
+{
+  "acp.agents": {
+    "Ghosty": {
+      "command": "npx",
+      "args": ["-y", "ghosty-acp", "wss://acp-AGENT.../acp"],
+      "env": { "GHOSTY_ACP_TOKEN": "gat_…" }
+    }
+  }
+}
+```
+
+Do not use VS Code's "Add Agent" wizard: it asks for command and args only, never the env
+var, and the agent ends up without its key.
+
+**JetBrains / Neovim** use the same triple (command, args, env) in their own ACP client
+settings. `GHOSTY_ACP_CWD` optionally sets the remote working directory.
+
+## When it does not connect
+
+| Symptom | Meaning | Do |
+|---|---|---|
+| `rejected (1006)` right away | token mismatch (rotated?) | ask the user to copy the block again from the panel |
+| slow first start (5–15 s) | the agent's machine was asleep; the first connection wakes it | wait, do not change anything |
+| `preview host not found` | the machine was recycled; the platform recreates it on demand | retry once after ~5 s |
+| `already serving N conversations` | every open session takes a slot | close a session in another client |
+
+## Rules
+
+- Node 22+ is required for `npx -y ghosty-acp`; check `node -v` if it fails to start.
+- Read `ghosty-acp` in the user's editor config as the bridge, not as this skill.
+- Never print the token back or commit the settings file with it inside.

package/skills/ghosty-agent/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: ghosty-agent
+description: Configure a Ghosty Studio agent (identity/system prompt, model, knowledge files in its machine, skills, custom MCP servers) through its REST API using the agent token. Use when the user asks to set up, tune, teach, or connect their Ghosty agent, or mentions ghosty.studio.
+license: MIT
+compatibility: Needs curl or any HTTP client and network access to https://www.ghosty.studio
+metadata:
+  author: ghosty-studio
+  version: "1.2"
+---
+
+# Configure a Ghosty Studio agent
+
+A Ghosty Studio agent runs on its own isolated machine (disk, terminal, memory). You configure it
+over HTTPS with **its own token**; nothing runs on the user's computer.
+
+## Setup (once)
+
+1. Ask the user for the agent id and token. Both are in Ghosty Studio → **Agentes → their agent →
+   Conexión con tu editor → Generar token** (token looks like `gat_…`; id is in the page URL
+   `/app/agents/<id>`).
+2. Keep them in env vars, never in command arguments or committed files:
+
+```bash
+export GHOSTY_AGENT_ID="<id>"
+export GHOSTY_AGENT_TOKEN="gat_…"
+```
+
+Base URL: `https://www.ghosty.studio/api/v2/agents/$GHOSTY_AGENT_ID`. Every call:
+`-H "Authorization: Bearer $GHOSTY_AGENT_TOKEN"`. Wrong token or id → `404` (do not retry).
+
+## Know the engine first
+
+`GET …?fields=name,engine,model,hasMachine,prompt` before anything else. `hasMachine` decides
+what applies:
+
+| `hasMachine` | Engines | You can | Identity (`prompt`) takes effect |
+|---|---|---|---|
+| `true` | Ghosty · Lite, Goose | everything: files, skills, MCP, `restart`, `try` | on the next conversation, or right away with `POST …/restart` |
+| `false` | Claude, Codex, DeepSeek | `GET`, `PATCH` (name, model, prompt, webSearch, channels) and `try` | on the next conversation; **never call `restart`** (it answers `409`) |
+
+The `PATCH` response carries a `nota` saying which case you are in. Files, skills and MCP on a
+machine-less engine answer `409 agente_sin_maquina`: tell the user and stop.
+
+## What you can do
+
+| User asks | Do |
+|---|---|
+| "set its identity / persona / system prompt" | write it with `references/identity.md`, `PATCH` with `{"prompt": "..."}`, then `restart` only if `hasMachine` |
+| "change the model" | `GET` first (lists `models`), then `PATCH {"model": "<id>"}` (restarts by itself) |
+| "give it these files / documents / knowledge" | `PUT …/files/<name>` with raw bytes, one call per file |
+| "install / teach it a skill" | `PUT …/skills/<slug>` with the SKILL.md markdown (+ assets), then `POST …/restart` |
+| "connect it to this MCP server" | `PUT …/mcp` with the full list of servers (it replaces; restarts by itself) |
+| "what does it have?" | `GET …?full=1` → prompt, model, files, skills, mcp (`?fields=` to read just some) |
+| "does it work? / test it" | `POST …/try {"text": "…"}` → the agent's answer (see Verify) |
+
+Read `references/api.md` for exact request/response shapes before calling.
+
+## Rules
+
+- **Read before write.** `GET` first; `PATCH` only the fields the user asked to change.
+- **Write the prompt in the user's language** and in second person ("Eres…", "You are…"), with
+  the house structure in `references/identity.md` (who it is, how it talks, what it does, what
+  it never does, when it asks). Keep it under ~3,000 characters: it is prepended to every
+  conversation. Do not state the model: the platform injects it every turn.
+- **Skills follow the Agent Skills format**: a `SKILL.md` with YAML frontmatter `name` and
+  `description`, body in markdown. Slug = lowercase, digits and hyphens.
+- **MCP `PUT` replaces the whole list.** `GET …/mcp` first and send back the existing servers plus
+  the new one. Only `https://` URLs for HTTP servers; stdio servers need the binary to exist in the
+  agent's machine (Node and Python are there).
+- **Engines without their own machine** (Claude, DeepSeek, Codex) accept `GET`/`PATCH` (identity, model) only; files, skills, MCP and restart answer `409 agente_sin_maquina`. Tell the user and stop; do not retry.
+- **Restart is not free**: it cuts a turn in progress. Batch changes, restart once at the end.
+- Files go to the agent's working directory; tell the user the agent can `ls` them. Max 10 MB each.
+- Never print the token back to the user or into logs.
+
+## Verify
+
+Never end on "it should work now". After the changes, `POST …/try` with a message that exercises
+exactly what changed, read the answer and tell the user whether it matches:
+
+| Changed | Ask |
+|---|---|
+| identity | `¿Quién eres y qué haces?` → the name and role you wrote |
+| files | `¿Qué archivos tienes en tu workspace?` → lists them |
+| a skill | a request the skill covers → it follows the skill's steps |
+| an MCP server | one action that needs that server → it calls it |
+| model | `¿Qué modelo eres?` → the label from `models` |
+
+```bash
+curl -s -X POST "$B/try" -H "Authorization: Bearer $GHOSTY_AGENT_TOKEN" \
+  -H "Content-Type: application/json" -d '{"text":"¿Quién eres y qué haces?","reset":true}'
+```
+
+`reset: true` starts from a clean memory; use `session` to keep several test threads apart. A
+machine that was asleep takes 5–15 s on the first call. Then tell the user in one line what
+changed and what the agent answered.

package/skills/ghosty-agent/references/api.md

@@ -0,0 +1,74 @@
+# Ghosty Studio — agent configuration API
+
+Base: `https://www.ghosty.studio/api/v2/agents/{id}` · Auth: `Authorization: Bearer gat_…`
+(agent token) or an owner OAuth2 bearer with `agents:write`. JSON unless noted.
+Full spec: https://www.ghosty.studio/openapi.yaml · Docs: https://www.ghosty.studio/docs/configurar
+
+## GET /
+Returns `{ id, name, engine, hasMachine, model, models: [{id,label}], prompt, channels, webSearch, mcp }`.
+`hasMachine` (bool) says whether files/skills/MCP/restart exist for this engine.
+Add `?full=1` to also get `files: [{path,size}]` and `skills: [{slug,description,files}]`
+(wakes the machine if asleep). Add `?fields=prompt,model` to get only those keys (`id` always).
+
+```bash
+curl -s "$B" -H "Authorization: Bearer $GHOSTY_AGENT_TOKEN"
+```
+
+## PATCH /
+Body: any of `{ "name", "model", "prompt", "webSearch": bool, "channels": { "teams": bool } }`.
+Response: the same as GET plus `aplicado: ["set-prompt", …]` and, after a `prompt` change, `nota`
+telling whether a `restart` applies (machine) or the identity simply enters on the next
+conversation (no machine). `model` restarts the agent.
+
+```bash
+curl -s -X PATCH "$B" -H "Authorization: Bearer $GHOSTY_AGENT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"prompt":"Eres Nora, asistente de la clínica Dental Sur. Contestas en español, corto, y nunca das diagnósticos."}'
+```
+
+## PUT /files/{path}  ·  DELETE /files/{path}  ·  GET /files[/dir]
+Raw bytes in the body (no multipart, no base64). Max 10 MB. `path` is relative, no `..`.
+
+```bash
+curl -s -X PUT "$B/files/precios-2026.pdf" -H "Authorization: Bearer $GHOSTY_AGENT_TOKEN" \
+  -H "Content-Type: application/pdf" --data-binary @precios-2026.pdf
+```
+→ `{ path, bytes, en: "/data/work/precios-2026.pdf" }`
+
+## PUT /skills/{slug}  ·  DELETE /skills/{slug}  ·  GET /skills
+Body: `{ "markdown": "<SKILL.md content>", "assets": [{ "name": "scripts/x.py", "contentBase64": "…" }] }`.
+Max 25 MB total. Then `POST /restart` so the agent loads it.
+
+```bash
+jq -n --rawfile md SKILL.md '{markdown:$md}' | \
+curl -s -X PUT "$B/skills/cotizaciones" -H "Authorization: Bearer $GHOSTY_AGENT_TOKEN" \
+  -H "Content-Type: application/json" -d @-
+```
+
+## GET /mcp  ·  PUT /mcp
+Body: `{ "servers": [ …full list… ] }`. Each server is one of:
+- `{ "name": "notion", "type": "http", "url": "https://mcp.notion.com/mcp", "headers": { "Authorization": "Bearer …" } }`
+- `{ "name": "fs", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data/work"], "env": {} }`
+
+Names: `a-z 0-9 - _`, max 20 servers. The agent restarts automatically.
+
+## POST /restart
+→ `{ reiniciado: true }`. Cuts a running turn; disk survives. Only with `hasMachine: true`;
+otherwise `409 agente_sin_maquina`.
+
+## POST /try
+Body: `{ "text": "…", "session"?: "a-z0-9_-", "reset"?: bool }`. One full turn to text, no stream,
+up to 180 s. `session` (default `default`) keeps separate memories; `reset: true` forgets that
+session first (with no `text` it only forgets). One turn at a time per session (`409 turno_en_curso`).
+Works on every engine; consumes balance like any turn.
+
+```bash
+curl -s -X POST "$B/try" -H "Authorization: Bearer $GHOSTY_AGENT_TOKEN" \
+  -H "Content-Type: application/json" -d '{"text":"¿Quién eres?","reset":true}'
+```
+→ `{ "text": "Soy Ghosty…", "error": null, "session": "default" }` · `502` if the turn failed with no text.
+
+## Errors
+`400` invalid body (message in `error`) · `404` unknown id/token · `405` wrong method ·
+`409 agente_sin_maquina` files, skills, MCP and restart need an engine with its own machine (Ghosty · Lite or Goose); `GET`/`PATCH` work on every engine ·
+`413` too big · `502` saved but the machine did not take it (retry `POST /restart`).

package/skills/ghosty-agent/references/identity.md

@@ -0,0 +1,86 @@
+# Writing an agent identity (the `prompt`)
+
+The identity is prepended to every conversation. Second person, the user's language, under
+~3,000 characters. Use these headings in this order; drop one only if it has nothing to say.
+
+```
+Eres <Nombre>, <qué es y para quién>. Si te preguntan quién eres, dices exactamente: «Soy <Nombre>».
+
+## Quién eres
+- <qué es, dónde vive, quién lo configura; cómo se ve si tiene imagen oficial>
+
+## Cómo hablas
+<idioma y registro; corto o largo; qué entrega y cómo>
+
+## Qué sabes hacer
+- <3–6 tareas concretas>
+
+## Qué NO haces
+- <2–4 límites duros>
+
+## Cuándo preguntas
+Sólo cuando la respuesta cambia el resultado. Si hay una lectura razonable, la tomas y la dices en una línea.
+
+## Formato            (only for agents that answer in Ghosty Teams)
+Markdown ligero (negritas, listas, un título si el texto es largo). Lo largo va como documento; en el chat quedan tres líneas y el enlace.
+```
+
+Rules:
+
+- **Do not mention the model.** The platform injects "[TU MODELO: …]" every turn; a hard-coded
+  model name goes stale and contradicts it.
+- **Self-reference is part of the identity.** Name, what it is, where it runs and who talks to
+  it. Without it the agent guesses ("soy un asistente de IA").
+- **No secrets, no tokens, no phone numbers** in the prompt.
+- Convert what the user already has (a job description, an old system prompt) instead of
+  inventing; ask only for what changes the result.
+
+## Example: Ghosty (the house agent)
+
+```
+Eres Ghosty, el agente de Ghosty Studio, y en este equipo trabajas dentro de Ghosty Teams. Si te preguntan quién eres, dices exactamente: «Soy Ghosty».
+
+## Quién eres
+- Ghosty es un fantasma redondito color lavanda, con lentes redondos grises y ojos grandes y negros. Ésa es tu imagen oficial (https://formmy.app/logo.png); no la describas de otra forma ni inventes otra apariencia.
+- Corres en tu propia máquina, con memoria y herramientas propias, y te configuran desde ghosty.studio (Studio); el equipo te habla desde Teams, el chat de ghosty.studio o WhatsApp.
+- Tu modelo te lo dice el sistema en cada turno; no lo deduzcas de tu entrenamiento.
+
+## Cómo hablas
+Español de México, directo y corto. Entregas el resultado, no un plan para hacerlo. Si algo es largo, lo entregas como documento y en el chat dejas tres líneas.
+
+## Qué sabes hacer
+- Leer los adjuntos del hilo y trabajar sobre ellos.
+- Redactar, resumir, comparar, preparar correos y organizar tareas.
+- Buscar en internet cuando la respuesta depende de algo actual.
+
+## Qué NO haces
+- No inventas datos que no estén en el hilo, en los archivos o en tu búsqueda.
+- No mandas nada fuera del equipo sin que te lo pidan explícitamente.
+
+## Cuándo preguntas
+Sólo cuando la respuesta cambia el resultado. Si hay una lectura razonable, la tomas y la dices en una línea.
+```
+
+## Example: a business agent
+
+```
+Eres Nora, asistente de recepción de la clínica Dental Sur. Si te preguntan quién eres, dices exactamente: «Soy Nora, de Dental Sur».
+
+## Quién eres
+- Atiendes a pacientes por WhatsApp y en el sitio de la clínica. Te configura el equipo de la clínica desde Ghosty Studio.
+
+## Cómo hablas
+Español de México, cálido y corto. Una pregunta a la vez.
+
+## Qué sabes hacer
+- Agendar, mover y cancelar citas.
+- Explicar precios con la lista `precios-2026.txt` de tu workspace.
+- Dar horarios, dirección y formas de pago.
+
+## Qué NO haces
+- No das diagnósticos ni recetas; ante un dolor fuerte, pides que llamen a la clínica.
+- No prometes descuentos que no estén en la lista.
+
+## Cuándo preguntas
+Sólo cuando la respuesta cambia el resultado (fecha, nombre del paciente).
+```

package/skills/ghosty-docs/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: ghosty-docs
+description: Read the Ghosty Studio documentation from an agent without scraping — every page as raw markdown, llms.txt, the docs MCP server (search_docs, read_doc, list_docs, openapi) and the OpenAPI spec. Use when the user asks how something works in Ghosty Studio, Ghosty Teams or ghosty.studio, or before calling its API.
+license: MIT
+compatibility: Network access to https://www.ghosty.studio
+metadata:
+  author: ghosty-studio
+  version: "1.0"
+---
+
+# Read the Ghosty Studio docs
+
+Ghosty Studio publishes its documentation for agents first. Never scrape the HTML: every
+page has a machine-readable twin.
+
+## Pick the cheapest source
+
+| Need | Fetch |
+|---|---|
+| The map of every page (title + URL) | `https://www.ghosty.studio/llms.txt` |
+| Everything at once (large) | `https://www.ghosty.studio/llms-full.txt` |
+| One page as markdown | append `.md` to its URL: `https://www.ghosty.studio/docs/configurar.md` (English: `/en/docs/configure.md`) |
+| A page when you only have the HTML URL | `GET` it with `Accept: text/markdown` — the server negotiates and returns markdown |
+| The public API contract | `https://www.ghosty.studio/openapi.yaml` (OpenAPI 3.1) |
+
+Spanish is the source language (`/docs/...`); English lives under `/en/docs/...`. Both are
+kept in sync; prefer the user's language.
+
+## Use the MCP server when you can
+
+`https://www.ghosty.studio/mcp/docs` is a Streamable HTTP MCP server, no auth, JSON-RPC over
+`POST`. Tools:
+
+- `search_docs { query, locale? }` — lexical search, up to 8 pages with slug and snippet. Call this first.
+- `read_doc { slug, locale? }` — a whole page as markdown (slug like `api/autenticacion`).
+- `list_docs { locale? }` — all pages grouped by section.
+- `openapi {}` — the OpenAPI YAML.
+
+Claude Code: `claude mcp add --transport http ghosty-docs https://www.ghosty.studio/mcp/docs`.
+
+Without MCP, the same tools in plain HTTP:
+
+```bash
+curl -s https://www.ghosty.studio/mcp/docs -H 'Content-Type: application/json' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_docs","arguments":{"query":"whatsapp"}}}'
+```
+
+## Rules
+
+- Search, then read one page. Do not read `llms-full.txt` for a single question.
+- Quote the page URL you used when you answer; the user may want to open it.
+- JSON field names in the API (`agentes`, `enCola`, `reemplazoAnterior`…) are the contract and
+  are the same in both languages: do not translate them.
+- To *change* an agent (identity, files, skills, MCPs) use the `ghosty-agent` skill, which has
+  the token flow. This skill is read-only.

package/skills/ghosty-recipe/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: ghosty-recipe
+description: Write, review or convert a Ghosty Studio agent recipe (the portable .recipe.yaml with title, instructions, model and channels) so it can be uploaded in "Nuevo agente → Plantilla". Use when the user wants to create a Ghosty agent from a spec, turn a persona or job description into an agent, export/share an agent, or mentions a Ghosty recipe or recipe.yaml.
+license: MIT
+compatibility: No network needed to write a recipe; uploading it happens in the Ghosty Studio panel
+metadata:
+  author: ghosty-studio
+  version: "1.0"
+---
+
+# Ghosty agent recipes
+
+A recipe is a YAML file that fully describes an agent **without secrets**: who it is, how it
+talks, which model, which channels. It is what Ghosty Studio exports from an agent
+(`/app/agents/<id>/recipe.yaml`) and what "Nuevo agente → Plantilla → sube una receta"
+imports. The format is Goose-compatible plus an `x-ghosty` block.
+
+## Write one
+
+```yaml
+version: "1.0.0"
+title: Nora, recepción de Dental Sur           # ≤ 60 chars, shown as the agent's name
+description: Agenda citas y resuelve dudas de la clínica por WhatsApp.   # ≤ 200 chars, one line
+instructions: |
+  Eres Nora, asistente de la clínica Dental Sur.
+
+  ## Cómo hablas
+  Español de México, corto, sin diagnósticos.
+
+  ## Qué sabes hacer
+  - Agendar, mover y cancelar citas.
+  - Explicar precios de la lista que tienes en tu workspace.
+
+  ## Qué NO haces
+  - No das diagnósticos ni recetas.
+
+  ## Cuándo preguntas
+  Sólo cuando la respuesta cambia el resultado.
+settings:
+  goose_model: claude-sonnet-5
+x-ghosty:
+  engine: ghosty-lite
+  channels: { teams: true, whatsapp: true }
+```
+
+Field-by-field rules are in `references/schema.md`. Read it before validating a recipe.
+
+## Rules
+
+- **`title` is required**; everything else is optional but a recipe without `instructions` is
+  useless. Write instructions in the user's language and in second person.
+- **Never a colon followed by a space inside `description`** unless the value is quoted
+  (`description: "Ventas: WhatsApp"`): unquoted it is a YAML parse error and the whole
+  recipe is skipped.
+- Structure `instructions` with the four headings the house templates use: *Cómo hablas*,
+  *Qué sabes hacer*, *Qué NO haces*, *Cuándo preguntas* (plus *Formato* for Teams agents).
+  Keep it under ~3,000 characters: it is prepended to every conversation.
+- Engines: `ghosty-lite` or `goose` when the agent needs its own machine (files, skills,
+  MCPs); `claude`, `codex`, `deepseek` for prompt-only agents. Models must be one the engine
+  offers (`claude-sonnet-5`, `claude-opus-5`, `claude-haiku-4-5-20251001`…); when unsure,
+  omit `settings` and let the panel pick.
+- No tokens, keys, phone numbers or URLs with credentials in a recipe: it is meant to be
+  pasted in an email.
+- Prefer converting what the user already has (a job description, an old system prompt)
+  over inventing; ask only for what changes the result.
+
+## Deliver
+
+Give the YAML in a fenced block and tell the user: save it as `<name>.recipe.yaml`, then in
+Ghosty Studio → **Agentes → Nuevo agente → Plantilla → sube una receta**. To tune it after
+creation, use the `ghosty-agent` skill (needs the agent token).

package/skills/ghosty-recipe/references/schema.md

@@ -0,0 +1,30 @@
+# Recipe schema (v1.0.0)
+
+Source of truth: `parseRecipe` in Ghosty Studio. Unknown keys are ignored, never rejected.
+
+| Key | Type | Required | Notes |
+|---|---|---|---|
+| `version` | string | no | defaults to `"1.0.0"` |
+| `title` | string | **yes** | trimmed, cut at 60 chars; becomes the agent's name |
+| `description` | string | no | trimmed, cut at 200 chars; one line, quote it if it contains `: ` |
+| `instructions` | string | no | the system prompt; use a block scalar (`|`) |
+| `settings.goose_provider` | string | no | Goose-compatible; usually omitted |
+| `settings.goose_model` | string | no | model id; must exist for the chosen engine |
+| `extensions` | list | no | Goose extensions; kept as-is, Ghosty ignores them today |
+| `x-ghosty.engine` | string | no | `ghosty-lite` · `goose` · `claude` · `codex` · `deepseek` |
+| `x-ghosty.model` | string \| null | no | same as `settings.goose_model`; the panel reads either |
+| `x-ghosty.channels` | object | no | `{ teams?: bool, web?: bool, whatsapp?: bool }`; default `{ teams: true }` |
+| `x-ghosty.creatorVersion` | string | no | written by exports; do not set by hand |
+
+## Validation checklist
+
+1. Parses as YAML (no unquoted `: ` in scalars, consistent indentation, block scalar for `instructions`).
+2. `title` present and non-empty.
+3. `instructions` in second person, in the user's language, with the four headings.
+4. No secrets.
+5. If `settings.goose_model` is set, it is a real model id for that engine.
+
+## Exporting an existing agent
+
+`GET https://www.ghosty.studio/app/agents/<id>/recipe.yaml` (logged-in browser) downloads
+`<name>.recipe.yaml` with the same shape, secrets stripped.