SKILL.md Raw History Folder

name: write-zot-extension description: Help the user create a new zot extension (slash command, LLM tool, or guard) in any language.

Writing a zot extension

Use this skill when the user asks for help building a zot extension — a new slash command, a new tool the LLM can call, an audit hook, or a permission gate. Skim this whole skill first, then collaborate with the user on the specific extension they want.

What an extension is

A zot extension is an external executable that zot launches as a subprocess and talks to over its stdin/stdout in newline-delimited JSON. It can be written in any language that can read/write JSON lines from stdio: Go, TypeScript (via tsx), Python, Rust, shell with jq, anything. Crash isolation is automatic; one bad extension never takes down zot.

Three things an extension can do (any combination):

Slash commands — register /foo so the user can run it from the input. The handler returns a "prompt" (submitted to the agent), an "insert" (text dropped into the editor), a "display" (one-shot styled note in the chat), or a "noop".
Tools — register tools the LLM itself calls. Schema is JSON Schema; zot routes the model's tool_call to the extension's tool_result. Same lifecycle as built-in tools (read/write/edit/bash/skill).
Lifecycle hooks — subscribe to events (session_start, turn_start, tool_call, turn_end, assistant_message) for telemetry / audit / custom UI, or intercept tool calls before execution to refuse dangerous patterns.

On-disk layout

Each extension lives in its own directory:

~/Library/Application Support/zot/extensions/<name>/
├── extension.json    # manifest (required)
└── <executable>      # whatever exec points at

Or project-local: <project>/.zot/extensions/<name>/. Project-local wins on name conflict.

For ad-hoc use during development, skip the install step entirely and run zot --ext PATH (repeatable: -e PATH -e PATH).

Manifest

{
  "name": "weather",
  "version": "1.0.0",
  "exec": "./weather",
  "args": [],
  "language": "go",
  "description": "current weather lookups for any city",
  "enabled": true
}

Field rules:

name (required, unique) — id zot uses internally; matches the hello frame. Slash commands & tools live in the same name space as built-ins; conflicts are silently shadowed by built-ins.
exec (required) — the executable path. Resolution:
- absolute: as-is
- starts with ./ or ../: relative to the manifest's directory
- bare name (no separator): looked up via $PATH (e.g. node, python3, npx, tsx)
args — extra argv passed to exec (e.g. ["index.js"])
language — informational only ("go", "typescript", "python", etc.)
enabled — defaults to true; set false to keep installed but skip

Wire format

Newline-delimited JSON in both directions. Top-level type is the discriminator. Optional id correlates command/tool requests with their responses.

Required handshake

The very first frame the extension sends is hello:

{"type":"hello","name":"weather","version":"1.0.0",
 "capabilities":["commands","tools"]}

Capabilities are advisory; current values are commands, tools, events. Send all that apply.

zot replies with hello_ack:

{"type":"hello_ack","protocol_version":1,"zot_version":"0.0.x",
 "provider":"anthropic","model":"claude-opus-4-7","cwd":"/path/to/project"}

Registration (after hello_ack)

The canonical startup order is hello, wait for hello_ack, send registration frames in any order, then send a single ready sentinel so zot can finalize the agent's tool registry:

{"type":"register_command","name":"weather","description":"current weather"}
{"type":"register_tool","name":"weather","description":"Get current weather for a city.",
 "schema":{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}}
{"type":"subscribe","events":["tool_call"],"intercept":["tool_call"]}
{"type":"ready"}

If you don't send ready, zot's idle watchdog auto-treats you as ready after 250ms of no frames, but always send it explicitly when you can. Newer extensions on faster hosts shave that 250ms off.

Use hello_ack.cwd for the user's project directory. The extension process itself runs from the extension directory, so do not use os.Getwd() or process.cwd() when you need the project path.

Runtime frames

zot → extension:

{"type":"command_invoked","id":"abc","name":"weather","args":"berlin"}
{"type":"tool_call","id":"def","name":"weather","args":{"city":"Berlin"}}
{"type":"event","event":"turn_start","step":1}
{"type":"event_intercept","id":"ghi","event":"tool_call",
 "tool_name":"bash","tool_args":{"command":"rm -rf /tmp/foo"}}
{"type":"shutdown"}

extension → zot (replies + spontaneous notifications):

{"type":"command_response","id":"abc","action":"prompt",
 "prompt":"Show today's weather for Berlin in one line."}
{"type":"tool_result","id":"def","content":[{"type":"text","text":"Berlin: 16°C, fog"}]}
{"type":"event_intercept_response","id":"ghi","block":true,
 "reason":"refused: command matches the danger pattern \"rm -rf\""}
{"type":"notify","level":"info","message":"refreshed cache"}
{"type":"clear_notes"}
{"type":"shutdown_ack"}

notify notes are one-shot: they clear when the user sends their next prompt (and on esc / /clear). Send clear_notes to retract every note this extension pushed earlier (e.g. a transient approval prompt) without waiting for the next turn; other extensions' notes are kept.

command_response.action values:

"prompt" — submit prompt as a fresh user message
"insert" — drop insert into the editor at the cursor
"display" — append display to chat as a one-shot note (no model call, not in transcript)
"noop" — handled internally; zot doesn't change the UI

tool_result.content[] blocks: {"type":"text","text":"..."} or {"type":"image","mime_type":"image/png","data":"<base64>"}.

Per-tool timeout: 60s. Per-intercept timeout: 5s. Missing the intercept timeout is treated as "allow" so an unresponsive guard never stalls the agent.

Important rules

stdout is reserved for the protocol. Anything you print to stdout that isn't a JSON frame breaks the wire. The first stdout frame must be hello; do not send notify, logs, or registration frames before that handshake starts. Use stderr for logs / debug output (zot captures stderr to $ZOT_HOME/logs/ext-<name>.log).
One JSON object per line. No multi-line JSON. Always end every frame with \n.
Flush after writing. Most stdout writes are line-buffered when piped, which is fine, but explicitly flushing avoids surprise buffering on slow handlers.
Extension processes inherit the user's permissions. A bad extension can do anything the user can.

Recommended layout per language

Go (use the built-in SDK at packages/agent/ext)

package main

import (
    "encoding/json"
    "github.com/patriceckhart/zot/packages/agent/ext"
)

func main() {
    e := ext.New("weather", "1.0.0")

    e.Command("weather", "current weather for a city",
        func(args string) ext.Response {
            return ext.Prompt("Tell me the weather for " + args)
        })

    e.Tool("weather", "Get current weather for a city.",
        json.RawMessage(`{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}`),
        func(args json.RawMessage) ext.ToolResult {
            var in struct{ City string `json:"city"` }
            if err := json.Unmarshal(args, &in); err != nil {
                return ext.TextErrorResult("invalid args")
            }
            return ext.TextResult(in.City + ": sunny, 21°C (fake)")
        })

    // Optional: register project-specific commands after hello_ack.
    e.OnHello(func(host ext.HostInfo) {
        if host.CWD != "" {
            e.Command("cwd", "show the current project directory", func(args string) ext.Response {
                return ext.Display(host.CWD)
            })
        }
    })

    if err := e.Run(); err != nil {
        e.Logf("fatal: %v", err)
    }
}

Build: go build -o weather .

OnHello is optional. Use it when configuration or registrations need host metadata such as HostInfo.CWD, Provider, Model, ZotVersion, ExtensionDir, or DataDir. The SDK sends hello, waits for hello_ack, runs OnHello, announces registrations, then sends ready.

extension.json:

{"name":"weather","version":"1.0.0","exec":"./weather","language":"go","enabled":true}

TypeScript (no SDK; handles the protocol directly)

Run via tsx, which executes .ts files without a build step.

{"name":"scratchpad","version":"1.0.0","exec":"tsx","args":["index.ts"],"language":"typescript","enabled":true}

// index.ts (excerpt; see examples/extensions/scratchpad/index.ts for the full version)
import { createInterface } from "node:readline";
import { stderr, stdin, stdout } from "node:process";

function send(o: object) { stdout.write(JSON.stringify(o) + "\n"); }
function log(s: string) { stderr.write(`[scratchpad] ${s}\n`); }

send({ type: "hello", name: "scratchpad", version: "1.0.0",
       capabilities: ["commands", "tools"] });

const rl = createInterface({ input: stdin, crlfDelay: Infinity });
rl.on("line", (line) => {
  const f = JSON.parse(line);
  if (f.type === "hello_ack") {
    // f.cwd is the user's project directory.
    send({ type: "register_command", name: "note", description: "append a note" });
    send({ type: "register_tool", name: "read_notes",
           description: "Read the user's scratchpad notes.",
           schema: { type: "object", properties: {} } });
    send({ type: "ready" });
  } else if (f.type === "command_invoked" && f.name === "note") {
    send({ type: "command_response", id: f.id, action: "display",
           display: `noted: ${f.args}` });
  } else if (f.type === "tool_call" && f.name === "read_notes") {
    send({ type: "tool_result", id: f.id,
           content: [{ type: "text", text: "(notes go here)" }] });
  } else if (f.type === "shutdown") {
    send({ type: "shutdown_ack" });
    rl.close();
  }
});

tsx install: npm install -g tsx. Without global tsx, fall back to "exec":"npx","args":["--yes","tsx","index.ts"] (slower startup; npx checks the registry every launch).

Python

{"name":"hello-py","version":"1.0.0","exec":"./hello.py","language":"python","enabled":true}

#!/usr/bin/env python3
import json, sys

def emit(o): sys.stdout.write(json.dumps(o) + "\n"); sys.stdout.flush()

emit({"type": "hello", "name": "hello-py", "version": "1.0.0", "capabilities": ["commands"]})

for line in sys.stdin:
    msg = json.loads(line)
    if msg["type"] == "hello_ack":
        # msg["cwd"] is the user's project directory.
        emit({"type": "register_command", "name": "hellopy", "description": "say hi (python)"})
        emit({"type": "ready"})
    elif msg["type"] == "command_invoked":
        emit({"type": "command_response", "id": msg["id"],
              "action": "prompt", "prompt": "Say hi briefly."})
    elif msg["type"] == "shutdown":
        emit({"type": "shutdown_ack"})
        break

chmod +x hello.py.

Install / dev workflow

zot ext install ./weather       # copy into $ZOT_HOME/extensions/
zot --ext ./weather             # run from disk for one zot session (no install)
zot --ext .                     # cwd is the extension dir
zot ext list                    # show installed extensions
zot ext logs weather            # cat the extension's stderr
zot ext logs weather -f         # tail it
zot ext disable weather         # keep installed but skip on launch
zot ext enable weather
zot ext remove weather

For TS / Python extensions, no build step is needed — edit the source in place and relaunch zot.

For Go, run go build -o <name> . in the extension directory after edits, then zot ext install (which copies the manifest + binary) or zot --ext . to test from the working tree.

Manual debug

The extension is just a process. Drive it directly with shell pipes to see exactly what's happening on the wire:

{
  printf '%s\n' '{"type":"hello_ack","protocol_version":1,"zot_version":"x","provider":"a","model":"o","cwd":"/tmp"}'
  sleep 0.2
  printf '%s\n' '{"type":"command_invoked","id":"1","name":"weather","args":"Berlin"}'
  sleep 0.5
  printf '%s\n' '{"type":"shutdown"}'
} | ./weather

Compare what comes out of stdout to the expected wire format. If a frame doesn't match what zot expects, it's discarded silently and logged to ext-<name>.log.

Process to follow with the user

Ask what the extension should DO. One sentence.
Pick the right capability:
- "I want a slash command that triggers a prompt" → command only
- "I want the model to be able to do X" → tool
- "I want to gate / log every bash command" → event + intercept
Pick a language. Default to Go via packages/agent/ext for new extensions if the user has Go installed; TypeScript via tsx if they prefer JS-flavored ergonomics; Python for one-off scripts.
Write the extension dir (manifest + source).
For Go, build it. For TS / Python, mark the script executable.
Suggest zot --ext <path> for testing without committing to an install.
When happy, zot ext install <path>.

Don't try to write a full SDK or framework on top of the protocol unless the user asked for one — the wire format is small enough that a 30-line raw script is the right answer for most extensions.

source

1---
2name: write-zot-extension
3description: Help the user create a new zot extension (slash command, LLM tool, or guard) in any language.
4---
5
6# Writing a zot extension
7
8Use this skill when the user asks for help building a zot extension —
9a new slash command, a new tool the LLM can call, an audit hook, or
10a permission gate. Skim this whole skill first, then collaborate
11with the user on the specific extension they want.
12
13## What an extension is
14
15A zot extension is **an external executable** that zot launches as a
16subprocess and talks to over its stdin/stdout in newline-delimited
17JSON. It can be written in any language that can read/write JSON
18lines from stdio: Go, TypeScript (via tsx), Python, Rust, shell with
19jq, anything. Crash isolation is automatic; one bad extension never
20takes down zot.
21
22Three things an extension can do (any combination):
23
241. **Slash commands** — register `/foo` so the user can run it from
25   the input. The handler returns a "prompt" (submitted to the
26   agent), an "insert" (text dropped into the editor), a "display"
27   (one-shot styled note in the chat), or a "noop".
28
292. **Tools** — register tools the LLM itself calls. Schema is
30   JSON Schema; zot routes the model's `tool_call` to the
31   extension's `tool_result`. Same lifecycle as built-in tools
32   (read/write/edit/bash/skill).
33
343. **Lifecycle hooks** — subscribe to events
35   (session_start, turn_start, tool_call, turn_end,
36   assistant_message) for telemetry / audit / custom UI, or
37   intercept tool calls before execution to refuse dangerous
38   patterns.
39
40## On-disk layout
41
42Each extension lives in its own directory:
43
44```
45~/Library/Application Support/zot/extensions/<name>/
46├── extension.json    # manifest (required)
47└── <executable>      # whatever exec points at
48```
49
50Or project-local: `<project>/.zot/extensions/<name>/`. Project-local
51wins on name conflict.
52
53For ad-hoc use during development, skip the install step entirely
54and run `zot --ext PATH` (repeatable: `-e PATH -e PATH`).
55
56### Manifest
57
58```json
59{
60  "name": "weather",
61  "version": "1.0.0",
62  "exec": "./weather",
63  "args": [],
64  "language": "go",
65  "description": "current weather lookups for any city",
66  "enabled": true
67}
68```
69
70Field rules:
71- `name` (required, unique) — id zot uses internally; matches the
72  hello frame. Slash commands & tools live in the same name space
73  as built-ins; conflicts are silently shadowed by built-ins.
74- `exec` (required) — the executable path. Resolution:
75  - absolute: as-is
76  - starts with `./` or `../`: relative to the manifest's directory
77  - bare name (no separator): looked up via `$PATH` (e.g. `node`,
78    `python3`, `npx`, `tsx`)
79- `args` — extra argv passed to `exec` (e.g. `["index.js"]`)
80- `language` — informational only (`"go"`, `"typescript"`,
81  `"python"`, etc.)
82- `enabled` — defaults to true; set false to keep installed but skip
83
84## Wire format
85
86Newline-delimited JSON in both directions. Top-level `type` is the
87discriminator. Optional `id` correlates command/tool requests with
88their responses.
89
90### Required handshake
91
92The very first frame the extension sends is `hello`:
93
94```json
95{"type":"hello","name":"weather","version":"1.0.0",
96 "capabilities":["commands","tools"]}
97```
98
99Capabilities are advisory; current values are `commands`, `tools`,
100`events`. Send all that apply.
101
102zot replies with `hello_ack`:
103
104```json
105{"type":"hello_ack","protocol_version":1,"zot_version":"0.0.x",
106 "provider":"anthropic","model":"claude-opus-4-7","cwd":"/path/to/project"}
107```
108
109### Registration (after hello_ack)
110
111The canonical startup order is `hello`, wait for `hello_ack`, send
112registration frames in any order, then send a single `ready` sentinel
113so zot can finalize the agent's tool registry:
114
115```json
116{"type":"register_command","name":"weather","description":"current weather"}
117{"type":"register_tool","name":"weather","description":"Get current weather for a city.",
118 "schema":{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}}
119{"type":"subscribe","events":["tool_call"],"intercept":["tool_call"]}
120{"type":"ready"}
121```
122
123If you don't send `ready`, zot's idle watchdog auto-treats you as
124ready after 250ms of no frames, but always send it explicitly when
125you can. Newer extensions on faster hosts shave that 250ms off.
126
127Use `hello_ack.cwd` for the user's project directory. The extension
128process itself runs from the extension directory, so do not use
129`os.Getwd()` or `process.cwd()` when you need the project path.
130
131### Runtime frames
132
133**zot → extension:**
134
135```json
136{"type":"command_invoked","id":"abc","name":"weather","args":"berlin"}
137{"type":"tool_call","id":"def","name":"weather","args":{"city":"Berlin"}}
138{"type":"event","event":"turn_start","step":1}
139{"type":"event_intercept","id":"ghi","event":"tool_call",
140 "tool_name":"bash","tool_args":{"command":"rm -rf /tmp/foo"}}
141{"type":"shutdown"}
142```
143
144**extension → zot (replies + spontaneous notifications):**
145
146```json
147{"type":"command_response","id":"abc","action":"prompt",
148 "prompt":"Show today's weather for Berlin in one line."}
149{"type":"tool_result","id":"def","content":[{"type":"text","text":"Berlin: 16°C, fog"}]}
150{"type":"event_intercept_response","id":"ghi","block":true,
151 "reason":"refused: command matches the danger pattern \"rm -rf\""}
152{"type":"notify","level":"info","message":"refreshed cache"}
153{"type":"clear_notes"}
154{"type":"shutdown_ack"}
155```
156
157`notify` notes are one-shot: they clear when the user sends their next
158prompt (and on `esc` / `/clear`). Send `clear_notes` to retract every
159note this extension pushed earlier (e.g. a transient approval prompt)
160without waiting for the next turn; other extensions' notes are kept.
161
162`command_response.action` values:
163- `"prompt"` — submit `prompt` as a fresh user message
164- `"insert"` — drop `insert` into the editor at the cursor
165- `"display"` — append `display` to chat as a one-shot note (no
166  model call, not in transcript)
167- `"noop"` — handled internally; zot doesn't change the UI
168
169`tool_result.content[]` blocks: `{"type":"text","text":"..."}` or
170`{"type":"image","mime_type":"image/png","data":"<base64>"}`.
171
172Per-tool timeout: 60s. Per-intercept timeout: 5s. Missing the
173intercept timeout is treated as "allow" so an unresponsive guard
174never stalls the agent.
175
176## Important rules
177
178- **stdout is reserved for the protocol.** Anything you print to
179  stdout that isn't a JSON frame breaks the wire. The first stdout
180  frame must be `hello`; do not send `notify`, logs, or registration
181  frames before that handshake starts. Use stderr for logs / debug
182  output (zot captures stderr to `$ZOT_HOME/logs/ext-<name>.log`).
183- **One JSON object per line.** No multi-line JSON. Always end
184  every frame with `\n`.
185- **Flush after writing.** Most stdout writes are line-buffered when
186  piped, which is fine, but explicitly flushing avoids surprise
187  buffering on slow handlers.
188- Extension processes inherit the user's permissions. A bad
189  extension can do anything the user can.
190
191## Recommended layout per language
192
193### Go (use the built-in SDK at packages/agent/ext)
194
195```go
196package main
197
198import (
199    "encoding/json"
200    "github.com/patriceckhart/zot/packages/agent/ext"
201)
202
203func main() {
204    e := ext.New("weather", "1.0.0")
205
206    e.Command("weather", "current weather for a city",
207        func(args string) ext.Response {
208            return ext.Prompt("Tell me the weather for " + args)
209        })
210
211    e.Tool("weather", "Get current weather for a city.",
212        json.RawMessage(`{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}`),
213        func(args json.RawMessage) ext.ToolResult {
214            var in struct{ City string `json:"city"` }
215            if err := json.Unmarshal(args, &in); err != nil {
216                return ext.TextErrorResult("invalid args")
217            }
218            return ext.TextResult(in.City + ": sunny, 21°C (fake)")
219        })
220
221    // Optional: register project-specific commands after hello_ack.
222    e.OnHello(func(host ext.HostInfo) {
223        if host.CWD != "" {
224            e.Command("cwd", "show the current project directory", func(args string) ext.Response {
225                return ext.Display(host.CWD)
226            })
227        }
228    })
229
230    if err := e.Run(); err != nil {
231        e.Logf("fatal: %v", err)
232    }
233}
234```
235
236Build: `go build -o weather .`
237
238`OnHello` is optional. Use it when configuration or registrations need
239host metadata such as `HostInfo.CWD`, `Provider`, `Model`, `ZotVersion`,
240`ExtensionDir`, or `DataDir`. The SDK sends `hello`, waits for
241`hello_ack`, runs `OnHello`, announces registrations, then sends `ready`.
242
243`extension.json`:
244```json
245{"name":"weather","version":"1.0.0","exec":"./weather","language":"go","enabled":true}
246```
247
248### TypeScript (no SDK; handles the protocol directly)
249
250Run via `tsx`, which executes `.ts` files without a build step.
251
252```json
253{"name":"scratchpad","version":"1.0.0","exec":"tsx","args":["index.ts"],"language":"typescript","enabled":true}
254```
255
256```typescript
257// index.ts (excerpt; see examples/extensions/scratchpad/index.ts for the full version)
258import { createInterface } from "node:readline";
259import { stderr, stdin, stdout } from "node:process";
260
261function send(o: object) { stdout.write(JSON.stringify(o) + "\n"); }
262function log(s: string) { stderr.write(`[scratchpad] ${s}\n`); }
263
264send({ type: "hello", name: "scratchpad", version: "1.0.0",
265       capabilities: ["commands", "tools"] });
266
267const rl = createInterface({ input: stdin, crlfDelay: Infinity });
268rl.on("line", (line) => {
269  const f = JSON.parse(line);
270  if (f.type === "hello_ack") {
271    // f.cwd is the user's project directory.
272    send({ type: "register_command", name: "note", description: "append a note" });
273    send({ type: "register_tool", name: "read_notes",
274           description: "Read the user's scratchpad notes.",
275           schema: { type: "object", properties: {} } });
276    send({ type: "ready" });
277  } else if (f.type === "command_invoked" && f.name === "note") {
278    send({ type: "command_response", id: f.id, action: "display",
279           display: `noted: ${f.args}` });
280  } else if (f.type === "tool_call" && f.name === "read_notes") {
281    send({ type: "tool_result", id: f.id,
282           content: [{ type: "text", text: "(notes go here)" }] });
283  } else if (f.type === "shutdown") {
284    send({ type: "shutdown_ack" });
285    rl.close();
286  }
287});
288```
289
290`tsx` install: `npm install -g tsx`. Without global tsx, fall back
291to `"exec":"npx","args":["--yes","tsx","index.ts"]` (slower
292startup; npx checks the registry every launch).
293
294### Python
295
296```json
297{"name":"hello-py","version":"1.0.0","exec":"./hello.py","language":"python","enabled":true}
298```
299
300```python
301#!/usr/bin/env python3
302import json, sys
303
304def emit(o): sys.stdout.write(json.dumps(o) + "\n"); sys.stdout.flush()
305
306emit({"type": "hello", "name": "hello-py", "version": "1.0.0", "capabilities": ["commands"]})
307
308for line in sys.stdin:
309    msg = json.loads(line)
310    if msg["type"] == "hello_ack":
311        # msg["cwd"] is the user's project directory.
312        emit({"type": "register_command", "name": "hellopy", "description": "say hi (python)"})
313        emit({"type": "ready"})
314    elif msg["type"] == "command_invoked":
315        emit({"type": "command_response", "id": msg["id"],
316              "action": "prompt", "prompt": "Say hi briefly."})
317    elif msg["type"] == "shutdown":
318        emit({"type": "shutdown_ack"})
319        break
320```
321
322`chmod +x hello.py`.
323
324## Install / dev workflow
325
326```bash
327zot ext install ./weather       # copy into $ZOT_HOME/extensions/
328zot --ext ./weather             # run from disk for one zot session (no install)
329zot --ext .                     # cwd is the extension dir
330zot ext list                    # show installed extensions
331zot ext logs weather            # cat the extension's stderr
332zot ext logs weather -f         # tail it
333zot ext disable weather         # keep installed but skip on launch
334zot ext enable weather
335zot ext remove weather
336```
337
338For TS / Python extensions, no build step is needed — edit the source
339in place and relaunch zot.
340
341For Go, run `go build -o <name> .` in the extension directory after
342edits, then `zot ext install` (which copies the manifest + binary)
343or `zot --ext .` to test from the working tree.
344
345## Manual debug
346
347The extension is just a process. Drive it directly with shell pipes
348to see exactly what's happening on the wire:
349
350```bash
351{
352  printf '%s\n' '{"type":"hello_ack","protocol_version":1,"zot_version":"x","provider":"a","model":"o","cwd":"/tmp"}'
353  sleep 0.2
354  printf '%s\n' '{"type":"command_invoked","id":"1","name":"weather","args":"Berlin"}'
355  sleep 0.5
356  printf '%s\n' '{"type":"shutdown"}'
357} | ./weather
358```
359
360Compare what comes out of stdout to the expected wire format. If a
361frame doesn't match what zot expects, it's discarded silently and
362logged to `ext-<name>.log`.
363
364## Process to follow with the user
365
3661. Ask what the extension should DO. One sentence.
3672. Pick the right capability:
368   - "I want a slash command that triggers a prompt" → `command` only
369   - "I want the model to be able to do X" → `tool`
370   - "I want to gate / log every bash command" → `event` + `intercept`
3713. Pick a language. Default to **Go via packages/agent/ext** for new
372   extensions if the user has Go installed; **TypeScript via tsx**
373   if they prefer JS-flavored ergonomics; **Python** for one-off
374   scripts.
3754. Write the extension dir (manifest + source).
3765. For Go, build it. For TS / Python, mark the script executable.
3776. Suggest `zot --ext <path>` for testing without committing to an
378   install.
3797. When happy, `zot ext install <path>`.
380
381Don't try to write a full SDK or framework on top of the protocol
382unless the user asked for one — the wire format is small enough
383that a 30-line raw script is the right answer for most extensions.

SKILL.md RawHistoryFolder